nomad/website/content/docs/concepts/workload-identity.mdx

---
layout: docs
page_title: Workload Identity
description: Learn about Nomad's workload identity feature
---

# Workload Identity

Every workload running in Nomad is given a default identity. When an
[allocation][] is accepted by the [plan applier][], the leader generates a
Workload Identity for each task in the allocation. This workload identity is a
[JSON Web Token (JWT)][] that has been signed by the leader's keyring.
Additional workload identities may be defined in tasks and services using the
[`identity`][identity-block] block.

## Workload Identity Claims

Nomad workload identity for tasks include the following identity claims.

```json
{
  "nomad_namespace": "default",
  "nomad_job_id": "example",
  "nomad_allocation_id": "5c6328f7-48c5-4d03-bada-91ef2e904d0d",
  "nomad_task": "web"
}
```

Workload identities for Consul services have a claim with the service name
instead of the task name.

```json
{
  "nomad_namespace": "default",
  "nomad_job_id": "example",
  "nomad_allocation_id": "8623ac7a-28ba-20c3-24a6-e615a39bbbf3",
  "nomad_service": "example-cache-redis"
}
```

Workload identities for tasks that use Vault have an additional claim for
[`vault.role`][jobspec_vault_role] if a role is specified in the job.

-> **Note:** This claim will *not* be added if the role is inherited from
the [agent configuration][vault_role_agent_config] and is not present
in the Nomad job specification.

```json
{
  "nomad_namespace": "default",
  "nomad_job_id": "example",
  "nomad_allocation_id": "8623ac7a-28ba-20c3-24a6-e615a39bbbf3",
  "nomad_service": "example-cache-redis"
  "vault_role": "nomad-jwt-login"
}
```

### Nomad Enterprise <EnterpriseAlert inline />

In Nomad Enterprise, tasks and services with a [`consul`][jobspec_consul] block
that defines a [`namespace`][jobspec_consul_ns] value, or inside a `group`
block that does it, have an additional claim called `consul_namespace`.

```json
{
  "consul_namespace": "prod",
  "nomad_namespace": "default",
  "nomad_job_id": "example",
  "nomad_allocation_id": "8623ac7a-28ba-20c3-24a6-e615a39bbbf3",
  "nomad_service": "example-cache-redis"
}
```

Similarly, tasks with a [`vault.namespace`][jobspec_vault_ns] value have the additional claim
`vault_namespace`.

```json
{
  "nomad_namespace": "default",
  "nomad_job_id": "example",
  "nomad_allocation_id": "8623ac7a-28ba-20c3-24a6-e615a39bbbf3",
  "nomad_service": "example-cache-redis"
  "vault_namespace": "prod",
}
```

## Workload Identity for Nomad

While Nomad always creates and uses workload identities internally, the JWT is
not exposed to tasks by default.

To expose Workload Identity to tasks, add an [`identity`][identity-block] block
to your jobspec:

```hcl
task "example" {

  identity {
    # Expose Workload Identity in NOMAD_TOKEN env var
    env = true

    # Expose Workload Identity in ${NOMAD_SECRETS_DIR}/nomad_token file
    file = true
  }

}
```

### Default Workload ACL Policy

By default, a Workload Identity has access to a implicit ACL policy. This policy
grants access to Nomad Variables associated with the job, group, and task, as
described in [Task Access to Variables][]. The implicit policy also allows
access to list or read any Nomad service registration as with the [List Services
API][] or [Read Service API][].

### Workload Associated ACL Policies

You can associate additional ACL policies with workload identities by passing
the `-job`, `-group`, and `-task` flags to `nomad acl policy apply`. When Nomad
resolves a workload identity claim, it will automatically include policies that
match. If no matching policies exist, the workload identity does not have any
additional capabilities.

For example, to allow a workload access to secrets from the namespace "shared",
you can create the following policy file:

```hcl
namespace "shared" {
  variables {
    path "*" {
      capabilities = ["read"]
    }
  }
}
```

You can then apply this policy to a specific task:

```shell-session
nomad acl policy apply \
   -namespace default -job example -group cache -task redis \
   redis-policy ./policy.hcl
```

You can also apply this policy to all tasks in the group by omitting the `-task`
flag:

```shell-session
nomad acl policy apply \
   -namespace default -job example -group cache \
   redis-policy ./policy.hcl
```

And you can apply this policy to all groups in the job by omitting both the
`-group` and `-task` flag:

```shell-session
nomad acl policy apply \
   -namespace default -job example \
   redis-policy ./policy.hcl
```

### Task API

It can be convenient to combine workload identity with Nomad's [Task API]
[taskapi] for  enabling tasks to access the Nomad API.

## Workload Identity for Consul and Vault

Consul and Vault can be configured to accept workload identities from Nomad for
authentication. Refer to the [Consul][consul_int] and [Vault][vault_int]
integration pages for more information.

[allocation]: /nomad/docs/concepts/architecture#allocation
[identity-block]: /nomad/docs/job-specification/identity
[jobspec_consul]: /nomad/docs/job-specification/consul
[jobspec_consul_ns]: /nomad/docs/job-specification/consul#namespace
[jobspec_vault_ns]: /nomad/docs/job-specification/vault#namespace
[jobspec_vault_role]: /nomad/docs/job-specification/vault#role
[vault_role_agent_config]: /nomad/docs/configuration/vault#create_from_role
[plan applier]: /nomad/docs/concepts/scheduling/scheduling
[JSON Web Token (JWT)]: https://datatracker.ietf.org/doc/html/rfc7519
[Task Access to Variables]: /nomad/docs/concepts/variables#task-access-to-variables
[List Services API]: /nomad/api-docs/services#list-services
[Read Service API]: /nomad/api-docs/services#read-service
[windows]: https://devblogs.microsoft.com/commandline/af_unix-comes-to-windows/
[taskapi]: /nomad/api-docs/task-api
[consul_int]: /nomad/docs/integrations/consul-integration
[vault_int]: /nomad/docs/integrations/vault-integration