JWT/OIDC auth method (API)

warning

Note: This engine can use external X.509 certificates as part of TLS or signature validation. Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer usable without a workaround. See the deprecation FAQ for more information.

This is the API documentation for the OpenBao JWT/OIDC auth method plugin. To learn more about the usage and operation, see the OpenBao JWT/OIDC method documentation.

This documentation assumes the plugin method is mounted at the /auth/jwt path in OpenBao. Since it is possible to enable auth methods at any location, please update your API calls accordingly.

Configure

Configures the validation information to be used globally across all roles. One (and only one) of oidc_discovery_url, jwks_url, and jwt_validation_pubkeys must be set.

Method	Path
`POST`	`/auth/jwt/config`

Parameters

oidc_discovery_url (string: <optional>) - The OIDC Discovery URL, without any .well-known component (base path). Cannot be used with "jwks_url" or "jwt_validation_pubkeys".
oidc_discovery_ca_pem (string: <optional>) - The contents of a CA certificate or chain of certificates, in PEM format, to use to validate connections to the OIDC Discovery URL. If not set, system certificates are used.
oidc_client_id (string: <optional>) - The OAuth Client ID from the provider for OIDC roles.
oidc_client_secret (string: <optional>) - The OAuth Client Secret from the provider for OIDC roles.
oidc_response_mode (string: <optional>) - The response mode to be used in the OAuth2 request. Allowed values are "query" and "form_post". Defaults to "query".
oidc_response_types (comma-separated string, or array of strings: <optional>) - The response types to request. Allowed values are "code" and "id_token". Defaults to "code". Note: "id_token" may only be used if "oidc_response_mode" is set to "form_post".
jwks_url (string: <optional>) - JWKS URL to use to authenticate signatures. Cannot be used with "oidc_discovery_url" or "jwt_validation_pubkeys".
jwks_ca_pem (string: <optional>) - The contents of a CA certificate or chain of certificates, in PEM format, to use to validate connections to the JWKS URL. If not set, system certificates are used.
jwt_validation_pubkeys (comma-separated string, or array of strings: <optional>) - A list of PEM-encoded public keys to use to authenticate signatures locally. Cannot be used with "jwks_url" or "oidc_discovery_url".
bound_issuer (string: <optional>) - The value against which to match the iss claim in a JWT.
jwt_supported_algs (comma-separated string, or array of strings: <optional>) - A list of supported signing algorithms. Defaults to [RS256] for OIDC roles. Defaults to all available algorithms for JWT roles.
default_role (string: <optional>) - The default role to use if none is provided during login.
provider_config (map: <optional>) - Configuration options for provider-specific handling. Providers with specific handling include: Azure, Google, SecureAuth, IBM ISAM. The options are described in each provider's section in OIDC Provider Setup.
namespace_in_state (bool: true) - Pass namespace in the OIDC state parameter instead of as a separate query parameter. With this setting, the allowed redirect URL(s) in OpenBao and on the provider side should not contain a namespace query parameter. This means only one redirect URL entry needs to be maintained on the provider side for all vault namespaces that will be authenticating against it. Defaults to true for new configs.

Sample payload

{
  "oidc_discovery_url": "https://myco.auth0.com/",
  "bound_issuer": "https://myco.auth0.com/"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/jwt/config

Read config

Returns the previously configured config.

Method	Path
`GET`	`/auth/jwt/config`

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    https://127.0.0.1:8200/v1/auth/jwt/config

Sample response

{
  "data":{
    "oidc_discovery_url": "https://myco.auth0.com/",
    "oidc_discovery_ca_pem": [],
    "bound_issuer": "https://myco.auth0.com/",
    "jwt_validation_pubkeys": []
  },
  ...
}

Create/Update role

Registers a role in the method. Role types have specific entities that can perform login operations against this endpoint. Constraints specific to the role type must be set on the role. These are applied to the authenticated entities attempting to login. At least one of the bound values must be set.

Method	Path
`POST`	`/auth/jwt/role/:name`

Parameters

name (string: <required>) - Name of the role.
role_type (string: <optional>) - Type of role, either "oidc" (default) or "jwt".
bound_audiences (array: <optional>) - List of aud claims to match against. Any match is sufficient. For "jwt" roles, at least one of bound_audiences, bound_subject, bound_claims or token_bound_cidrs is required. Optional for "oidc" roles.
user_claim (string: <required>) - The claim to use to uniquely identify the user; this will be used as the name for the Identity entity alias created due to a successful login. The claim value must be a string.
user_claim_json_pointer (bool: false) - Specifies if the user_claim value uses JSON pointer syntax for referencing claims. By default, the user_claim value will not use JSON pointer.
clock_skew_leeway (int or string: <optional>) - The amount of leeway to add to all claims to account for clock skew, in seconds. Defaults to 60 seconds if set to 0 and can be disabled if set to -1. Accepts an integer number of seconds, or a Go duration format string. Only applicable with "jwt" roles.
expiration_leeway (int or string: <optional>) - The amount of leeway to add to expiration (exp) claims to account for clock skew, in seconds. Defaults to 150 seconds if set to 0 and can be disabled if set to -1. Accepts an integer number of seconds, or a Go duration format string. Only applicable with "jwt" roles.
not_before_leeway (int or string: <optional>) - The amount of leeway to add to not before (nbf) claims to account for clock skew, in seconds. Defaults to 150 seconds if set to 0 and can be disabled if set to -1. Accepts an integer number of seconds, or a Go duration format string. Only applicable with "jwt" roles.
bound_subject (string: <optional>) - If set, requires that the sub claim matches this value.
bound_claims (map: <optional>) - If set, a map of claims (keys) to match against respective claim values (values). The expected value may be a single string or a list of strings. The interpretation of the bound claim values is configured with bound_claims_type. Keys support JSON pointer syntax for referencing claims.
bound_claims_type (string: "string") - Configures the interpretation of the bound_claims values. If "string" (the default), the values will treated as string literals and must match exactly. If set to "glob", the values will be interpreted as globs, with * matching any number of characters.
groups_claim (string: <optional>) - The claim to use to uniquely identify the set of groups to which the user belongs; this will be used as the names for the Identity group aliases created due to a successful login. The claim value must be a list of strings. Supports JSON pointer syntax for referencing claims.
claim_mappings (map: <optional>) - If set, a map of claims (keys) to be copied to specified metadata fields (values). Keys support JSON pointer syntax for referencing claims.
oidc_scopes (list: <optional>) - If set, a list of OIDC scopes to be used with an OIDC role. The standard scope "openid" is automatically included and need not be specified.
allowed_redirect_uris (list: <required>) - The list of allowed values for redirect_uri during OIDC logins.
verbose_oidc_logging (bool: false) - Log received OIDC tokens and claims when debug-level logging is active. Not recommended in production since sensitive information may be present in OIDC responses.
max_age (int or string: <optional>) - Specifies the allowable elapsed time in seconds since the last time the user was actively authenticated with the OIDC provider. If set, the max_age request parameter will be included in the authentication request. See AuthRequest for additional details. Accepts an integer number of seconds, or a Go duration format string.

token_ttl (integer: 0 or string: "") - The incremental lifetime for generated tokens. This current value of this will be referenced at renewal time.
token_max_ttl (integer: 0 or string: "") - The maximum lifetime for generated tokens. This current value of this will be referenced at renewal time.
token_policies (array: [] or comma-delimited string: "") - List of token policies to encode onto generated tokens. Depending on the auth method, this list may be supplemented by user/group/other values.
policies (array: [] or comma-delimited string: "") - DEPRECATED: Please use the token_policies parameter instead. List of token policies to encode onto generated tokens. Depending on the auth method, this list may be supplemented by user/group/other values.

token_bound_cidrs (array: [] or comma-delimited string: "") - List of CIDR blocks; if set, specifies blocks of IP addresses which can authenticate successfully, and ties the resulting token to these blocks as well.
token_strictly_bind_ip (bool: false) - If set, the token will be restricted to the source IP address making the initial login request. This conflicts with token_bound_cidrs.
token_explicit_max_ttl (integer: 0 or string: "") - If set, will encode an explicit max TTL onto the token. This is a hard cap even if token_ttl and token_max_ttl would otherwise allow a renewal.
token_no_default_policy (bool: false) - If set, the default policy will not be set on generated tokens; otherwise it will be added to the policies set in token_policies.
token_num_uses (integer: 0) - The maximum number of times a generated token may be used (within its lifetime); 0 means unlimited. If you require the token to have the ability to create child tokens, you will need to set this value to 0.
token_period (integer: 0 or string: "") - The maximum allowed period value when a periodic token is requested from this role.
token_type (string: "") - The type of token that should be generated. Can be service, batch, or default to use the mount's tuned default (which unless changed will be service tokens). For token store roles, there are two additional possibilities: default-service and default-batch which specify the type to return unless the client requests a different type at generation time.

Sample payload

{
  "policies": ["dev", "prod"],
  "bound_subject": "sl29dlldsfj3uECzsU3Sbmh0F29Fios1@clients",
  "bound_audiences": "https://myco.test",
  "user_claim": "https://openbao/user",
  "groups_claim": "https://openbao/groups",
  "bound_claims": {
    "department": "engineering",
    "sector": "7g"
  },
  "claim_mappings": {
    "preferred_language": "language",
    "group": "group"
  }
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/jwt/role/dev-role

Read role

Returns the previously registered role configuration.

Method	Path
`GET`	`/auth/jwt/role/:name`

Parameters

name (string: <required>) - Name of the role.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    https://127.0.0.1:8200/v1/auth/jwt/role/dev-role

Sample response

{
  "data":{
    "bound_subject": "sl29dlldsfj3uECzsU3Sbmh0F29Fios1@clients",
    "bound_audiences": [
      "https://myco.test"
    ],
    "bound_cidrs": [],
    "user_claim": "https://openbao/user",
    "groups_claim": "https://openbao/groups",
    "policies": [
      "dev",
      "prod"
    ],
    "period": 0,
    "ttl": 0,
    "num_uses": 0,
    "max_ttl": 0
  },
  ...
}

List roles

Lists all the roles that are registered with the plugin.

Method	Path
`LIST`	`/auth/jwt/role`

Parameters

after (string: "") - Optional entry to begin listing after for pagination; not required to exist.
limit (int: 0) - Optional number of entries to return; defaults to all entries.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    https://127.0.0.1:8200/v1/auth/jwt/role

Sample response

{
  "data": {
    "keys": [
      "dev-role",
      "prod-role"
    ]
  },
  ...
}

Delete role

Deletes the previously registered role.

Method	Path
`DELETE`	`/auth/jwt/role/:name`

Parameters

name (string: <required>) - Name of the role.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://127.0.0.1:8200/v1/auth/jwt/role/dev-role

OIDC authorization URL request

Obtain an authorization URL from OpenBao to start an OIDC login flow.

Method	Path
`POST`	`/auth/jwt/oidc/auth_url`

Parameters

role (string: <optional>) - Name of the role against which the login is being attempted. Defaults to configured default_role if not provided.
redirect_uri (string: <required>) - Path to the callback to complete the login. This will be of the form, "https://.../oidc/callback" where the leading portion is dependent on your OpenBao server location, port, and the mount of the JWT plugin. This must be configured with OpenBao and the provider. See Redirect URIs for more information.
client_nonce (string: <optional>) - Optional client-provided nonce that must match the client_nonce value provided during a subsequent request to the callback API.

Sample payload

{
  "role": "dev-role",
  "redirect_uri": "https://openbao.myco.com:8200/ui/openbao/auth/jwt/oidc/callback"
}

Sample request

$ curl \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/jwt/oidc/auth_url

Sample response

{
  "request_id": "c701169c-64f8-26cc-0315-078e8c3ce897",
  "data": {
    "auth_url": "https://myco.auth0.com/authorize?client_id=r3qXcK2bezU3Sbmh0K16fatW6&nonce=851b69a9bfa5a6a5668111314414e3687891a599&redirect_uri=https%3A%2F%2Fopenbao.myco.com3A8200%2Fui%2Fopenbao%2Fauth%2Fjwt%2Foidc%2Fcallback&response_type=code&scope=openid+email+profile&state=1011e726d24960e09cfca2e04b36b38593cb6a22"
  },
  ...
}

OIDC callback

Exchange an authorization code for an OIDC ID Token. The ID token will be further validated against any bound claims, and if valid an OpenBao token will be returned.

Method	Path
`GET`	`/auth/jwt/oidc/callback`

Parameters

state (string: <required>) - Opaque state ID that is part of the Authorization URL and will be included in the the redirect following successful authentication on the provider.
nonce (string: <required>) - Opaque nonce that is part of the Authorization URL and will be included in the the redirect following successful authentication on the provider.
code (string: <required>) - Provider-generated authorization code that OpenBao will exchange for an ID token.
client_nonce (string: <optional>) - Optional client-provided nonce that must match the client_nonce value provided during the prior request to the auth_url API.

Sample request

$ curl \
    https://127.0.0.1:8200/v1/auth/jwt/oidc/callback?state=n2kfh3nsl&code=mn2ldl2nv98h2jl&nonce=ni42i2idj2jj

Sample response

{
    "auth":{
        "client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c",
        "accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d",
        "policies":[
            "default",
            "dev",
            "prod"
        ],
        "lease_duration":2764800,
        "renewable":true
    },
    ...
}

Fetch a token. This endpoint takes a signed JSON Web Token (JWT) and a role name for some entity. It verifies the JWT signature to authenticate that entity and then authorizes the entity for the given role.

Method	Path
`POST`	`/auth/jwt/login`

Parameters

role (string: <optional>) - Name of the role against which the login is being attempted. Defaults to configured default_role if not provided.
jwt (string: <required>) - Signed JSON Web Token (JWT).

Sample payload

{
  "role": "dev-role",
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Sample request

$ curl \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/jwt/login

Sample response

{
    "auth":{
        "client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c",
        "accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d",
        "policies":[
            "default",
            "dev",
            "prod"
        ],
        "lease_duration":2764800,
        "renewable":true
    },
    ...
}

JWT/OIDC auth method (API)

Configure​

Parameters​

Sample payload​

Sample request​

Read config​

Sample request​

Sample response​

Create/Update role​

Parameters​

Sample payload​

Sample request​

Read role​

Parameters​

Sample request​

Sample response​

List roles​

Parameters​

Sample request​

Sample response​

Delete role​

Parameters​

Sample request​

OIDC authorization URL request​

Parameters​

Sample payload​

Sample request​

Sample response​

OIDC callback​

Parameters​

Sample request​

Sample response​

JWT login​

Parameters​

Sample payload​

Sample request​

Sample response​

Configure

Parameters

Sample payload

Sample request

Read config

Sample request

Sample response

Create/Update role

Parameters

Sample payload

Sample request

Read role

Parameters

Sample request

Sample response

List roles

Parameters

Sample request

Sample response

Delete role

Parameters

Sample request

OIDC authorization URL request

Parameters

Sample payload

Sample request

Sample response

OIDC callback

Parameters

Sample request

Sample response

JWT login

Parameters

Sample payload

Sample request

Sample response