---
layout: docs
page_title: identity Block - Job Specification
description: |-
  The "identity" block allows tasks to use their Nomad Workload Identity via an
  environment variable or file.
---

# `identity` Block

<Placement
  groups={[
    ['job', 'group', 'task', 'identity'],
  ]}
/>

The `identity` block allows a task access to its [Workload Identity][] via an
environment variable or file. Nomad will create a _default_ identity for all
workloads, but it is *not* exposed to a task. You may also set additional
identities intended for use with external applications such as Vault, Consul, or
OIDC authentication.

For example, the following will expose the default Workload Identity as an
environment variable and file to the task, and a second Workload Identity
configured for a third-party OIDC provider:

```hcl
job "docs" {
  group "example" {
    task "api" {

      identity {
        env         = true
        file        = true

        # Restart on token renewal to get the new env var
        change_mode = "restart"
      }

      identity {
        name        = "example"
        aud         = ["oidc.example.com"]
        file        = true
        ttl         = "1h"

        # Send a HUP signal when the token file is updated
        change_mode   = "signal"
        change_signal = "SIGHUP"
      }

      # ...
    }
  }
}
```

## `identity` Parameters

- `name` `(string: "default")` - The name of the workload identity, which must
  be unique per task. Only one `identity` block in a task can omit the `name`
  field.
- `aud` `([]string: nil)` - The audience field for the workload identity. This
  should always be set for non-default identities.
- `change_mode` `(string: "noop")` - Specifies the behavior Nomad should take when the token changes.

  - `"noop"` - take no action. The default since tasks may choose to reload
      tokens only when their current token gets rejected or implement their own
      change detection.
  - `"restart"` - restart the task.
  - `"signal"` - send a configurable signal to the task. Must set `change_signal`.

- `change_signal` `(string: "")` - Specifies the signal to send to the task as a
  string like `"SIGHUP"` or `"SIGUSR1"`. This option is required if the
  `change_mode` is `signal`.
- `env` `(bool: false)` - If true the workload identity will be available in the
  task's `NOMAD_TOKEN` environment variable.
- `file` `(bool: false)` - If true the workload identity will be available in
  the task's filesystem via the path `secrets/nomad_token`. If the
  [`task.user`][taskuser] parameter is set, the token file will only be
  readable by that user. Otherwise the file is readable by everyone but is
  protected by parent directory permissions.
- `ttl` `(string: "")` - The lifetime of the identity before it expires. The
  client will renew the identity at roughly half the TTL. This is specified
  using a label suffix like "30s" or "1h". You may not set a TTL on the default
  identity. You should always set a TTL for non-default identities.

## Task API

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

[taskuser]: /nomad/docs/job-specification/task#user "Nomad task Block"
[Workload Identity]: /nomad/docs/concepts/workload-identity "Nomad Workload Identity"
[windows]: https://devblogs.microsoft.com/commandline/af_unix-comes-to-windows/
[taskapi]: /nomad/api-docs/task-api
