OpenID Connect (OIDC) Auth Method

Use the oidc auth method to authenticate to Nomad with OIDC. This method allows authentication via a configured OIDC provider using the user's web browser. Initiate this method from the Nomad UI or the command line.

Prerequisites

General knowledge of OIDC concepts
Nomad Access Control List fundamentals.

Refer to auth-method create for the parameters required to create an OIDC auth-method.

JWT Verification

Nomad uses OIDC discovery to verify JWT signatures against public keys from the issuer. Nomad first fetches keys from the OIDC Discovery URL during authentication and then applies OIDC validation criteria such as iss and aud.

OIDC Authentication

Nomad includes two built-in OIDC login flows: the Nomad UI, and the CLI using nomad login.

Redirect URIs

Properly setting redirect URIs is an important part of OIDC auth method configuration. You must configure these in both Nomad and the OIDC provider, and these configurations must align.

Specify the redirect URIs for an auth method with the AllowedRedirectURIs parameter in the auth method config. The Nomad UI and CLI use different redirect URIs, so you need to configure one or both, depending on your installation.

Note: Redirect URI is used interchangeably with callback address.

Logging in via the UI requires the redirect URI http://{host:port}/ui/settings/tokens.

Logging in via the CLI requires the redirect URI http://{host:port}/oidc/callback.

Nomad UI

Select one of the provider links in the Nomad homepage or navigate directly to /ui/settings/tokens.
Click one of the buttons for your OIDC auth method of choice.
Complete the authentication with the configured provider.

CLI

Execute the nomad login -method=oidc command to log in. If the -oidc-callback-addr flag is not specified, it will default to localhost:4649.

$ nomad login -method=oidc -oidc-callback-addr=<host:port>

Complete the login via your OIDC provider. Launching browser to:

    https://myco.auth0.com/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A4649%2Foidc%2Fcallback&client_id=r3qXc2bix9eF...

Your browser opens to the generated URL to complete the provider's login. Enter the URL manually if the browser does not automatically open.

OIDC Configuration Troubleshooting

The amount of configuration required for OIDC is relatively small, but it can be tricky to debug why things aren't working. The following are tips for setting up OIDC:

Monitor the log output for the Nomad servers for important information about OIDC validation failures.
Ensure correct redirect URIs in Nomad and on the provider. URIs need to match exactly. Check http/https, 127.0.0.1/localhost, port numbers, and whether trailing slashes are present.
The BoundAudiences option is typically not required. OIDC providers use the client_id as the audience and OIDC validation expects this.
Check your provider for scopes that are required to receive all of the information you need. You often need to request the scopes profile and groups, which you may set with OIDCScopes=["profile", "groups"] in the auth method configuration.
If you're seeing claim-related errors in logs, review the provider's docs very carefully to see how they're naming and structuring their claims. Depending on the provider, you may be able to construct a simple curl implicit grant request to obtain a JWT that you can inspect. This example decodes the JWT located in the access_token field of a JSON response.
```
jq --raw-output '.access_token / "." | .[1] | @base64d' jwt.json
```
With debug level logging, use the VerboseLogging option in the auth method configuration to log the received OIDC token. This can be helpful when debugging provider setup and verifying that the received claims are what you expect. Since claims data is logged verbatim and may contain sensitive information, do not use this option in production.

Trusted Identity Attributes via Claim Mappings

The authentication step can return data from JWT claims as trusted identity attributes for use in binding rule selectors and bind name interpolation.

The ClaimMappings and ListClaimMappings attributes control how Nomad maps claims to identity attributes. Both are maps of items to copy, with elements of the form "<JWT claim>":"<attribute suffix>".

Use ClaimMappings to map singular values and ListClaimMappings to map lists of values.

This examples contains ClaimMappings and ListClaimMappings. The configuration instructs Nomad to copy the values in the JWT claims "givenName" and "surname" to attributes named "value.first_name" and "value.last_name" respectively. Additionally, Nomad should copy the list of values in the JWT claim "groups" to an attribute named "list.roles".

{
  "Name": "example-auth-method",
  "Type": "<jwt|oidc>",
  "Description": "Example auth method",
  "Config": {
    "ClaimMappings": {
      "givenName": "first_name",
      "surname": "last_name"
    },
    "ListClaimMappings": {
      "groups": "roles"
    }
  }
}

The following table shows the resulting attributes and the ways they may be used in rule bindings:

Attributes	Supported selector operations	Can be interpolated
`value.first_name`	Equal, Not Equal, In, Not In, Matches, Not Matches	yes
`value.last_name`	Equal, Not Equal, In, Not In, Matches, Not Matches	yes
`list.groups`	In, Not In, Is Empty, Is Not Empty	no

Refer to the binding-rule documentation for more examples on using selectors.

Claim Specifications and JSON Pointer

Use the ClaimMappings and ListClaimMappings fields to point to data within the JWT. If the desired key is at the top of level of the JWT, you may provide the name directly. If it is nested at a lower level, you may use a JSON Pointer.

This example shows decoded JWT claims.

{
  "division": "North America",
  "groups": {
    "primary": "Engineering",
    "secondary": "Software"
  },
  "iss": "https://my-corp-app-name.auth0.com/",
  "sub": "auth0|eiw7OWoh5ieSh7ieyahC3ief0uyuraphaengae9d",
  "aud": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
  "iat": 1589224148,
  "exp": 1589260148,
  "nonce": "eKiihooH3Fah8Ieshah4leeti6ien3"
}

Use the following syntax to reference data:

Top-level key: Use direct reference. For example, "division" refers to "North America".
Nested key: Use JSON Pointer syntax. For example, "/groups/primary" refers to "Engineering".

You may use any valid JSON Pointer as a selector. Refer to the JSON Pointer RFC for a full description of the syntax.