Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Backport of auth/jwt: adds documentation for multi-jwks config parameter into release/1.16.x #25520

Merged
merged 1 commit into from
Feb 21, 2024
Merged

Backport of auth/jwt: adds documentation for multi-jwks config parameter into release/1.16.x #25520

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion website/content/api-docs/auth/jwt.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,9 @@ set.
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.
- `jwks_pairs` `(list of JSON object: <optional>)` - List of JWKS URL and optional CA certificate pairs. CA certificates must be in PEM format. Must be a list of JSON objects with format `[{"jwks_url": "", "jwks_ca_pem": ""}]`. Cannot be used with "jwks_url" or "jwks_ca_pem".
- `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.
- `bound_issuer` `(string: <optional>)` - The value against which to match the `iss` claim in a JWT. Cannot be configured when `jwks_pairs` is set.
- `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.
- `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](/vault/docs/auth/jwt/oidc-providers).
Expand Down
23 changes: 17 additions & 6 deletions website/content/docs/auth/jwt/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -181,14 +181,25 @@ only needs to validate the provided JWT.
JWT signatures will be verified against public keys from the issuer. This process can be done in
three different ways, though only one method may be configured for a single backend:

- **Static Keys**. A set of public keys is stored directly in the backend configuration.
- **Static Keys**. A set of public keys is stored directly in the backend configuration. See the
[jwt_validation_pubkeys](/vault/api-docs/auth/jwt#jwt_validation_pubkeys)
configuration option.

- **JWKS**. A JSON Web Key Set ([JWKS](https://tools.ietf.org/html/rfc7517)) URL (and optional
certificate chain) is configured. Keys will be fetched from this endpoint during authentication.
- **JWKS**. A JSON Web Key Set ([JWKS](https://tools.ietf.org/html/rfc7517)) URL and optional
certificate chain is configured. Keys will be fetched from this endpoint for authentication.
See the [jwks_url](/vault/api-docs/auth/jwt#jwks_url) and [jwks_ca_pem](/vault/api-docs/auth/jwt#jwks_ca_pem)
configuration options.

- **OIDC Discovery**. An OIDC Discovery URL (and optional certificate chain) is configured. Keys
- **JWKS Pairs**. A list of JSON Web Key Set ([JWKS](https://tools.ietf.org/html/rfc7517)) URLs and optional
certificate chain for each is configured. Keys will be fetched from each endpoint for authentication,
stopping at the first set to successfully verify the JWT signature. See the
[jwks_pairs](/vault/api-docs/auth/jwt#jwks_pairs) configuration option.

- **OIDC Discovery**. An OIDC Discovery URL and optional certificate chain is configured. Keys
will be fetched from this URL during authentication. When OIDC Discovery is used, OIDC validation
criteria (e.g. `iss`, `aud`, etc.) will be applied.
criteria (e.g. `iss`, `aud`, etc.) will be applied. See the [oidc_discovery_url](/vault/api-docs/auth/jwt#oidc_discovery_url)
and [oidc_discovery_ca_pem](/vault/api-docs/auth/jwt#oidc_discovery_ca_pem) configuration
options.

If multiple methods are needed, another instance of the backend can be mounted and configured
at a different path.
Expand Down Expand Up @@ -251,7 +262,7 @@ management tool.
$ vault auth enable oidc
```

1. Use the `/config` endpoint to configure Vault. To support JWT roles, either local keys, a JWKS URL, or an OIDC
1. Use the `/config` endpoint to configure Vault. To support JWT roles, either local keys, JWKS URL(s), or an OIDC
Discovery URL must be present. For OIDC roles, OIDC Discovery URL, OIDC Client ID and OIDC Client Secret are required. For the
list of available configuration options, please see the [API documentation](/vault/api-docs/auth/jwt).

Expand Down
Loading