ACL auth methods HTTP API

The /acl/auth-methods and /acl/auth-method endpoints are used to manage ACL auth methods.

Create auth method

This endpoint creates an ACL auth method. The request is always forwarded to the authoritative region.

Method	Path	Produces
`POST`	`/acl/auth-method`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`management`

Parameters

Name (string: <required>) - Name is the identifier of the ACL auth method. The name can contain alphanumeric characters, dashes, and underscores. This name must be unique and must not exceed 128 characters.
Type (string: <required>) - ACL auth method type, supports OIDC and JWT.
TokenLocality (string: <required>) - Defines whether the ACL auth method creates a local or global token when performing SSO login. This field must be set to either local or global.
TokenNameFormat (string <optional>) - Defines the token name format for the generated tokens This can be lightly templated using HIL ${foo} syntax. Defaults to ${auth_method_type}-${auth_method_name}.
MaxTokenTTL (duration: <required>) - Defines the maximum life of a token created by this method. When set, it will initialize the ExpirationTime field on all tokens to a value of Token.CreateTime + AuthMethod.MaxTokenTTL. This field is not persisted beyond its initial use. Can be specified in the form of "60s" or "5m" (i.e., 60 seconds or 5 minutes, respectively).
Default (bool: false) - Defines whether this ACL Auth Method is to be set as default when running nomad login command.
Config (ACLAuthMethodConfig: <required>) - The raw configuration to use for the auth method. This parameter is part of the auth method configuration, not specific to Nomad.
- OIDCDiscoveryURL (string: <required>) - The OIDC discovery URL, without any .well-known component (base path). Required for OIDC method type. Either this, the JWKSURL or the JWTValidationPubKeys is required for JWT method type.
- OIDCClientID (string: <required>) - The OAuth client ID configured with your OIDC provider. Required for OIDC method type.
- OIDCClientSecret (string: <required>) - The OAuth client secret configured with your OIDC provider. Required for OIDC method type.
- OIDCDisableUserInfo (bool: false) - When set to true, Nomad will not make a request to the identity provider to get OIDC UserInfo. You may wish to set this if your identity provider doesn't send any additional claims from the UserInfo endpoint.
- OIDCScopes (array<string>) - List of OIDC scopes.
- JWTValidationPubKeys (array<string>) - A list of PEM-encoded public keys to use to validate JWT signatures locally. Either this, the JWKSURL or the OIDCDiscoveryURL is required for JWT method type.
- JWKSURL (string) - JSON Web Key Sets url for authenticating JWT signatures. Either this, the JWTValidationPubKeys or the OIDCDiscoverURL is required for JWT method type.
- BoundAudiences (array<string>) - List of aud claims that are valid for login; any match is sufficient.
- AllowedRedirectURIs (array<string>) - A list of allowed values for redirect_uri. Must be non-empty.
- DiscoveryCaPem (array<string>) - PEM encoded CA certs for use by the TLS client used to talk with the OIDC discovery URL. If not set, system certificates are used.
- JWKSCACert (string) - PEM encoded CA cert for use by the TLS client used to talk with the JWKS server.
- SigningAlgs (array<string>) - A list of supported signing algorithms. Defaults to RS256.
- ExpirationLeeway (duration) - Duration in seconds of leeway when validating expiration of a JWT to account for clock skew.
- NotBeforeLeeway (duration) - Duration in seconds of leeway when validating not before values of a JWT to account for clock skew.
- ClockSkewLeeway (duration) - Duration in seconds of leeway when validating all JWT claims to account for clock skew.
- ClaimMappings (map[string]string) - Mappings of claims (key) that will be copied to a metadata field (value). Use this if the claim you are capturing is singular (such as an attribute).
  When mapped, the values in each list can be any of a number, string, or boolean and will all be stringified when returned.
- ListClaimMappings (map[string]string) - Mappings of claims (key) will be copied to a metadata field (value). Use this if the claim you are capturing is list-like (such as groups).

Sample payload

{
  "Name": "example-acl-auth-method",
  "Type": "OIDC",
  "TokenLocality": "local",
  "TokenNameFormat": "${auth_method_type}-${value.user}",
  "MaxTokenTTL": "1h0m0s",
  "Default": false,
  "Config": {
    "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
    "OIDCClientID": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
    "OIDCClientSecret": "example-client-secret",
    "OIDCScopes": [
      "groups"
    ],
    "BoundAudiences": [
      "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
    ],
    "AllowedRedirectURIs": [
      "http://localhost:4646/oidc/callback"
    ],
    "ClaimMappings": {
      "http://example.com/first_name": "first_name",
      "http://example.com/last_name": "last_name"
    },
    "ListClaimMappings": {
      "http://nomad.com/groups": "groups"
    }
  }
}

Sample request

$ curl \
    --request POST \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    --data @payload.json \
    https://localhost:4646/v1/acl/auth-method

Sample response

{
    "MaxTokenTTL": "1h0m0s",
    "Name": "example-acl-auth-method",
    "Type": "OIDC",
    "TokenLocality": "local",
    "TokenNameFormat": "${auth_method_type}-${value.user}",
    "Default": false,
    "Config": {
        "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
        "OIDCClientID": "v1rpi2myptmv1rpi2myptmv1rpi2mypt",
        "OIDCClientSecret": "example-client-secret",
        "OIDCScopes": [
            "groups"
        ],
        "BoundAudiences": [
            "v1rpi2myptmv1rpi2myptmv1rpi2mypt"
        ],
        "AllowedRedirectURIs": [
            "http://localhost:4646/oidc/callback"
        ],
        "DiscoveryCaPem": null,
        "SigningAlgs": null,
        "ClaimMappings": {
            "http://example.com/first_name": "first_name",
            "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
            "http://nomad.com/groups": "groups"
        }
    },
    "CreateTime": "2022-12-08T11:04:43.46206Z",
    "ModifyTime": "2022-12-08T11:04:43.46206Z",
    "CreateIndex": 12,
    "ModifyIndex": 12
}

Update auth method

This endpoint updates an existing ACL auth method. The request is always forwarded to the authoritative region.

Method	Path	Produces
`POST`	`/acl/auth-method/:method_name`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`management`

Parameters

Name (string: <required>) - Names is the identifier of the ACL auth method. The name can contain alphanumeric characters, dashes, and underscores. This name must be unique and must not exceed 128 characters.
Type (string: <required>) - ACL auth role SSO identifier. Currently, the only supported Type is "OIDC."
TokenLocality (string: "") - Defines whether the ACL auth method creates a local or global token when performing SSO login. This field must be set to either "local" or "global"
TokenNameFormat (string <optional>) - Defines the token name format for the generated tokens This can be lightly templated using HIL '${foo}' syntax. Defaults to '${auth_method_type}-${auth_method_name}'
MaxTokenTTL (duration: <required>) - Defines the maximum life of a token created by this method. When set it will initialize the ExpirationTime field on all tokens to a value of Token.CreateTime + AuthMethod.MaxTokenTTL. This field is not persisted beyond its initial use. Can be specified in the form of "60s" or "5m" (i.e., 60 seconds or 5 minutes, respectively).
Default (bool: false) - Defines whether this ACL auth method is to be set as default when running nomad login command.
Config (ACLAuthMethodConfig: nil) - The raw configuration to use for the auth method. This parameter is part of the auth method configuration, not specific to Nomad.
- OIDCDiscoveryURL (string: "") - The OIDC discovery URL, without any .well-known component (base path).
- OIDCClientID (string: "") - The OAuth client ID configured with your OIDC provider.
- OIDCClientSecret (string: "") - The OAuth client secret configured with your OIDC provider.
- OIDCDisableUserInfo (bool: false) - When set to true, Nomad will not make a request to the identity provider to get OIDC UserInfo. You may wish to set this if your identity provider doesn't send any additional claims from the UserInfo endpoint.
- OIDCScopes (array<string>) - List of OIDC scopes.
- BoundAudiences (array<string>) - List of aud claims that are valid for login; any match is sufficient.
- AllowedRedirectURIs (array<string>) - A list of allowed values for redirect_uri. Must be non-empty.
- DiscoveryCaPem (array<string>) - PEM encoded CA certs for use by the TLS client used to talk with the OIDC discovery URL. If not set, system certificates are used.
- SigningAlgs (array<string>) - A list of supported signing algorithms. Defaults to RS256.
- ClaimMappings (map[string]string) - Mappings of claims (key) that will be copied to a metadata field (value). Use this if the claim you are capturing is singular (such as an attribute).
  When mapped, the values in each list can be any of a number, string, or boolean and will all be stringified when returned.
- ListClaimMappings (map[string]string) - Mappings of claims (key) will be copied to a metadata field (value). Use this if the claim you are capturing is list-like (such as groups).

Sample Payload

{
  "Name": "example-acl-auth-method",
  "Type": "OIDC",
  "Tokenlocality": "global",
  "TokenNameFormat": "${auth_method_type}-${value.user}",
  "Maxtokenttl": "1h0m0s",
  "Default": true,
  "Config": {
    "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
    "OIDCClientID": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
    "OIDCClientSecret": "example-client-secret",
    "OIDCScopes": [
      "groups"
    ],
    "BoundAudiences": [
      "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
    ],
    "AllowedRedirectURIs": [
      "http://localhost:4646/oidc/callback"
    ],
    "ClaimMappings": {
      "http://example.com/first_name": "first_name",
      "http://example.com/last_name": "last_name"
    },
    "ListClaimMappings": {
      "http://nomad.com/groups": "groups"
    }
  }
}

Sample Request

$ curl \
    --request POST \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    --data @payload.json \
    https://localhost:4646/v1/acl/auth-method/example-acl-auth-method

Sample Response

{
    "MaxTokenTTL": "1h0m0s",
    "Name": "example-acl-auth-method",
    "Type": "OIDC",
    "TokenLocality": "global",
    "TokenNameFormat": "${auth_method_type}-${value.user}",
    "Default": true,
    "Config": {
        "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
        "OIDCClientID": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
        "OIDCClientSecret": "example-client-secret",
        "OIDCScopes": [
          "groups"
        ],
        "BoundAudiences": [
          "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
        ],
        "AllowedRedirectURIs": [
          "http://localhost:4646/oidc/callback"
        ],
        "ClaimMappings": {
          "http://example.com/first_name": "first_name",
          "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
          "http://nomad.com/groups": "groups"
        }
    },
    "CreateTime": "2022-12-08T11:04:43.46206Z",
    "ModifyTime": "2022-12-08T11:04:43.46206Z",
    "CreateIndex": 12,
    "ModifyIndex": 32
}

List auth methods

This endpoint lists all ACL auth methods. This lists the auth methods that have been replicated to the region, and may lag behind the authoritative region.

Method	Path	Produces
`GET`	`/acl/auth-methods`	`application/json`

The table below shows this endpoint's support for blocking queries, consistency modes and required ACLs.

Blocking Queries	Consistency Modes	ACL Required
`YES`	`all`	None

Sample request

$ curl \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/auth-methods

Sample response

[
    {
        "CreateIndex": 12,
        "Default": true,
        "ModifyIndex": 32,
        "Name": "example-acl-auth-method",
        "Type": "OIDC"
    }
]

Read auth method by name

This endpoint reads an ACL Auth Method with the given name. This queries the auth method that has been replicated to the region, and may lag behind the authoritative region.

Method	Path	Produces
`GET`	`/acl/auth-method/:method_name`	`application/json`

The table below shows this endpoint's support for blocking queries, consistency modes and required ACLs.

Blocking Queries	Consistency Modes	ACL Required
`YES`	`all`	`management` token

Parameters

:method_name (string: <required>) - Specifies the name of the ACL auth method. This is specified as part of the path.

Sample request

$ curl \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/auth-method/example-acl-auth-method

Sample response

{
    "MaxTokenTTL": "1h0m0s",
    "Name": "example-acl-auth-method",
    "Type": "OIDC",
    "TokenLocality": "global",
    "TokenNameFormat": "${auth_method_type}-${value.user}",
    "Default": true,
    "Config": {
      "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
      "OIDCClientID": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
      "OIDCClientSecret": "example-client-secret",
      "OIDCScopes": [
        "groups"
      ],
      "BoundAudiences": [
        "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
      ],
      "AllowedRedirectURIs": [
        "http://localhost:4646/oidc/callback"
      ],
      "ClaimMappings": {
        "http://example.com/first_name": "first_name",
        "http://example.com/last_name": "last_name"
      },
      "ListClaimMappings": {
        "http://nomad.com/groups": "groups"
      }
    },
    "CreateTime": "2022-12-08T11:04:43.46206Z",
    "ModifyTime": "2022-12-08T11:04:43.46206Z",
    "CreateIndex": 12,
    "ModifyIndex": 32
}

Delete auth method

This endpoint deletes the ACL auth method as identified by its name. This request is always forwarded to the authoritative region.

Method	Path	Produces
`DELETE`	`/acl/auth-method/:method_name`	`(empty body)`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`management`

Parameters

method_name (string: <required>) - Specifies the name of auth method to delete and is specified as part of the path.

Sample Request

$ curl \
    --request DELETE \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/auth-method/example-acl-auth-method