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 block.

Workload Identity Claims

Nomad workload identity for tasks include the following identity claims.

{
  "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.

{
  "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 if a role is specified in the job.

{
  "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 EnterpriseEnterprise

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

{
  "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 value have the additional claim vault_namespace.

{
  "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 block to your jobspec:

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:

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

You can then apply this policy to a specific task:

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:

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:

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:

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 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 and Vault integration pages for more information.