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

---
layout: docs
page_title: Workload Identity
description: Nomad's workload identity feature isolates and uniquely identities each workload so you can associate Access Control List (ACL) policies to jobs. Learn about workload identity claims, claims attributes specific to Nomad Enterprise, default workload ACL policy, and workload identity for Consul and Vault.
---

# Workload Identity

This page provides conceptual information about Nomad's workload identity
feature, which isolates and uniquely identities each workload so you can associate Access Control List (ACL) policies to jobs. Learn about workload identity claims, claims attributes specific to Nomad Enterprise, default workload ACL policy, and workload identity for Consul and Vault.

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
```

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
```

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

```shell-session
nomad acl policy apply \
   -namespace default 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/glossary#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/how-scheduling-works
[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/secure/acl/consul
[vault_int]: /nomad/docs/secure/vault