From cf508a380d3b936b9b1686d9f64d6e962a91429b Mon Sep 17 00:00:00 2001 From: Austin Gebauer <34121980+austingebauer@users.noreply.github.com> Date: Tue, 20 Feb 2024 16:49:53 +0000 Subject: [PATCH] backport of commit 6d4f5df69c2e26c5cd46550996f85bd5e4551ccf --- website/content/api-docs/auth/jwt.mdx | 3 ++- website/content/docs/auth/jwt/index.mdx | 23 +++++++++++++++++------ 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/website/content/api-docs/auth/jwt.mdx b/website/content/api-docs/auth/jwt.mdx index f5c8cd252c16..4b99126ef80d 100644 --- a/website/content/api-docs/auth/jwt.mdx +++ b/website/content/api-docs/auth/jwt.mdx @@ -39,8 +39,9 @@ set. Note: "id_token" may only be used if "oidc_response_mode" is set to "form_post". - `jwks_url` `(string: )` - JWKS URL to use to authenticate signatures. Cannot be used with "oidc_discovery_url" or "jwt_validation_pubkeys". - `jwks_ca_pem` `(string: )` - 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: )` - 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: )` - 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: )` - The value against which to match the `iss` claim in a JWT. +- `bound_issuer` `(string: )` - 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: )` - 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: )` - The default role to use if none is provided during login. - `provider_config` `(map: )` - 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). diff --git a/website/content/docs/auth/jwt/index.mdx b/website/content/docs/auth/jwt/index.mdx index 7d66ac3d8bb8..f46495876775 100644 --- a/website/content/docs/auth/jwt/index.mdx +++ b/website/content/docs/auth/jwt/index.mdx @@ -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. @@ -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).