open-vault/website/content/api-docs/auth/jwt.mdx

443 lines
16 KiB
Plaintext
Raw Normal View History

2018-07-11 19:08:49 +00:00
---
layout: api
page_title: JWT/OIDC - Auth Methods - HTTP API
2018-07-11 19:08:49 +00:00
description: |-
2019-03-22 05:15:59 +00:00
This is the API documentation for the Vault JWT/OIDC authentication
2018-07-11 19:08:49 +00:00
method plugin.
---
2019-03-22 05:15:59 +00:00
# JWT/OIDC Auth Method (API)
2018-07-11 19:08:49 +00:00
@include 'x509-sha1-deprecation.mdx'
2019-03-22 05:15:59 +00:00
This is the API documentation for the Vault JWT/OIDC auth method
2018-07-11 19:08:49 +00:00
plugin. To learn more about the usage and operation, see the
[Vault JWT/OIDC method documentation](/vault/docs/auth/jwt).
2018-07-11 19:08:49 +00:00
This documentation assumes the plugin method is mounted at the
`/auth/jwt` path in Vault. 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
2018-07-11 19:08:49 +00:00
set.
| Method | Path |
| :----- | :----------------- |
| `POST` | `/auth/jwt/config` |
2018-07-11 19:08:49 +00:00
### Parameters
2019-05-09 20:32:50 +00:00
- `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".
2018-07-11 19:08:49 +00:00
- `oidc_discovery_ca_pem` `(string: <optional>)` - The 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.
2019-03-18 23:38:54 +00:00
- `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". If using Vault namespaces, and oidc_response_mode is "form_post", then "namespace_in_state" should be set to false.
- `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".
2019-05-09 20:32:50 +00:00
- `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 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".
2018-07-11 19:08:49 +00:00
- `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](https://github.com/hashicorp/cap/blob/main/jwt/algs.go) for JWT roles.
2019-03-18 23:38:54 +00:00
- `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. The options are described in each provider's section in [OIDC Provider Setup](/vault/docs/auth/jwt/oidc-providers).
- `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 Vault 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.
2018-07-11 19:08:49 +00:00
### Sample Payload
```json
{
"oidc_discovery_url": "https://myco.auth0.com/",
"bound_issuer": "https://myco.auth0.com/"
}
```
### Sample Request
```shell-session
2018-07-11 19:08:49 +00:00
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/auth/jwt/config
2018-07-11 19:08:49 +00:00
```
# Read Config
Returns the previously configured config.
| Method | Path |
| :----- | :----------------- |
| `GET` | `/auth/jwt/config` |
2018-07-11 19:08:49 +00:00
### Sample Request
```shell-session
2018-07-11 19:08:49 +00:00
$ curl \
--header "X-Vault-Token: ..." \
https://127.0.0.1:8200/v1/auth/jwt/config
```
### Sample Response
```json
{
"data":{
"oidc_discovery_url": "https://myco.auth0.com/",
"oidc_discovery_ca_pem": [],
"bound_issuer": "https://myco.auth0.com/",
"jwt_validation_pubkeys": []
},
...
}
```
## Create 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` |
2018-07-11 19:08:49 +00:00
### Parameters
2018-07-11 19:08:49 +00:00
- `name` `(string: <required>)` - Name of the role.
2019-03-18 23:38:54 +00:00
- `role_type` `(string: <optional>)` - Type of role, either "oidc" (default) or "jwt".
2019-04-08 22:08:55 +00:00
- `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.
2018-07-11 19:08:49 +00:00
- `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](/vault/docs/auth/jwt#claim-specifications-and-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.
2018-07-11 19:08:49 +00:00
- `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).
2020-03-14 21:45:30 +00:00
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](/vault/docs/auth/jwt#claim-specifications-and-json-pointer)
syntax for referencing claims.
2020-03-14 21:45:30 +00:00
- `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
2018-07-11 19:08:49 +00:00
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](/vault/docs/auth/jwt#claim-specifications-and-json-pointer)
syntax for referencing claims.
2019-03-18 23:38:54 +00:00
- `claim_mappings` `(map: <optional>)` - If set, a map of claims (keys) to be copied to
specified metadata fields (values). Keys support [JSON pointer](/vault/docs/auth/jwt#claim-specifications-and-json-pointer)
syntax for referencing claims.
2019-03-18 23:38:54 +00:00
- `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](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)
for additional details. Accepts an integer number of seconds, or a Go duration format string.
@include 'tokenfields.mdx'
2018-07-11 19:08:49 +00:00
### Sample Payload
```json
{
"policies": ["dev", "prod"],
2018-07-11 19:08:49 +00:00
"bound_subject": "sl29dlldsfj3uECzsU3Sbmh0F29Fios1@clients",
"bound_audiences": "https://myco.test",
"user_claim": "https://vault/user",
2019-03-18 23:38:54 +00:00
"groups_claim": "https://vault/groups",
"bound_claims": {
"department": "engineering",
"sector": "7g"
},
"claim_mappings": {
"preferred_language": "language",
"group": "group"
}
2018-07-11 19:08:49 +00:00
}
```
### Sample Request
```shell-session
2018-07-11 19:08:49 +00:00
$ 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` |
2018-07-11 19:08:49 +00:00
### Parameters
- `name` `(string: <required>)` - Name of the role.
### Sample Request
```shell-session
2018-07-11 19:08:49 +00:00
$ curl \
--header "X-Vault-Token: ..." \
https://127.0.0.1:8200/v1/auth/jwt/role/dev-role
```
### Sample Response
```json
{
"data":{
"bound_subject": "sl29dlldsfj3uECzsU3Sbmh0F29Fios1@clients",
"bound_audiences": [
"https://myco.test"
],
"bound_cidrs": [],
"user_claim": "https://vault/user",
"groups_claim": "https://vault/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` |
2018-07-11 19:08:49 +00:00
### Sample Request
```shell-session
2018-07-11 19:08:49 +00:00
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://127.0.0.1:8200/v1/auth/jwt/role
2018-07-11 19:08:49 +00:00
```
### Sample Response
2019-03-18 23:38:54 +00:00
```json
2018-07-11 19:08:49 +00:00
{
"data": {
"keys": [
"dev-role",
"prod-role"
]
},
...
}
```
## Delete Role
Deletes the previously registered role.
| Method | Path |
| :------- | :--------------------- |
| `DELETE` | `/auth/jwt/role/:name` |
2018-07-11 19:08:49 +00:00
### Parameters
- `name` `(string: <required>)` - Name of the role.
### Sample Request
```shell-session
2018-07-11 19:08:49 +00:00
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://127.0.0.1:8200/v1/auth/jwt/role/dev-role
```
2019-03-18 23:38:54 +00:00
## OIDC Authorization URL Request
Obtain an authorization URL from Vault to start an OIDC login flow.
| Method | Path |
| :----- | :------------------------ |
| `POST` | `/auth/jwt/oidc/auth_url` |
2019-03-18 23:38:54 +00:00
### 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&#x3A;//.../oidc/callback" where the leading portion is dependent on your Vault
2019-03-18 23:38:54 +00:00
server location, port, and the mount of the JWT plugin. This must be configured with Vault and the
provider. See [Redirect URIs](/vault/docs/auth/jwt#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](/vault/api-docs/auth/jwt#oidc-callback) API.
2019-03-18 23:38:54 +00:00
### Sample Payload
```json
{
"role": "dev-role",
"redirect_uri": "https://vault.myco.com:8200/ui/vault/auth/jwt/oidc/callback"
2019-03-18 23:38:54 +00:00
}
```
### Sample Request
```shell-session
2019-03-18 23:38:54 +00:00
$ curl \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/auth/jwt/oidc/auth_url
2019-03-18 23:38:54 +00:00
```
### Sample Response
```json
{
"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%2Fvault.myco.com3A8200%2Fui%2Fvault%2Fauth%2Fjwt%2Foidc%2Fcallback&response_type=code&scope=openid+email+profile&state=1011e726d24960e09cfca2e04b36b38593cb6a22"
2019-03-18 23:38:54 +00:00
},
...
}
```
## OIDC Callback
2019-03-18 23:38:54 +00:00
Exchange an authorization code for an OIDC ID Token. The ID token will be further validated
against any bound claims, and if valid a Vault token will be returned.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `/auth/jwt/oidc/callback` |
2019-03-18 23:38:54 +00:00
### Parameters
- `state` `(string: <required>)` - Opaque state ID that is part of the Authorization URL and will
2021-11-15 19:52:04 +00:00
be included in the the redirect following successful authentication on the provider.
2019-03-18 23:38:54 +00:00
- `nonce` `(string: <required>)` - Opaque nonce that is part of the Authorization URL and will
2021-11-15 19:52:04 +00:00
be included in the the redirect following successful authentication on the provider.
2019-03-18 23:38:54 +00:00
- `code` `(string: <required>)` - Provider-generated authorization code that Vault 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](/vault/api-docs/auth/jwt#oidc-authorization-url-request) API.
2019-03-18 23:38:54 +00:00
### Sample Request
```shell-session
2019-03-18 23:38:54 +00:00
$ curl \
https://127.0.0.1:8200/v1/auth/jwt/oidc/callback?state=n2kfh3nsl&code=mn2ldl2nv98h2jl&nonce=ni42i2idj2jj
```
### Sample Response
```json
{
"auth":{
"client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c",
"accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d",
"policies":[
"default",
"dev",
"prod"
],
"lease_duration":2764800,
"renewable":true
},
...
}
```
## JWT Login
2018-07-11 19:08:49 +00:00
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` |
2018-07-11 19:08:49 +00:00
2019-03-18 23:38:54 +00:00
### Parameters
2018-07-11 19:08:49 +00:00
2019-03-18 23:38:54 +00:00
- `role` `(string: <optional>)` - Name of the role against which the login is being
attempted. Defaults to configured `default_role` if not provided.
2018-07-11 19:08:49 +00:00
- `jwt` `(string: <required>)` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT).
### Sample Payload
```json
{
"role": "dev-role",
"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
2018-07-11 19:08:49 +00:00
}
```
### Sample Request
```shell-session
2018-07-11 19:08:49 +00:00
$ curl \
--request POST \
--data @payload.json \
https://127.0.0.1:8200/v1/auth/jwt/login
```
### Sample Response
```json
{
"auth":{
"client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c",
"accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d",
"policies":[
"default",
"dev",
"prod"
],
"lease_duration":2764800,
"renewable":true
},
...
}
```