From 826653e7f5a16dbe9df85a19effe787dcd77c155 Mon Sep 17 00:00:00 2001 From: Jim Kalafut Date: Thu, 9 May 2019 13:32:50 -0700 Subject: [PATCH 1/2] JWKS docs (#6645) --- website/source/api/auth/jwt/index.html.md | 6 ++++-- website/source/docs/auth/jwt.html.md | 17 +++++++++++++++++ 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/website/source/api/auth/jwt/index.html.md b/website/source/api/auth/jwt/index.html.md index 17b72b0ed..cf530d80a 100644 --- a/website/source/api/auth/jwt/index.html.md +++ b/website/source/api/auth/jwt/index.html.md @@ -30,11 +30,13 @@ set. ### Parameters -- `oidc_discovery_url` `(string: )` - The OIDC Discovery URL, without any .well-known component (base path). Cannot be used with `jwt_validation_pubkeys`. +- `oidc_discovery_url` `(string: )` - 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: )` - 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. - `oidc_client_id` `(string: )` - The OAuth Client ID from the provider for OIDC roles. - `oidc_client_secret` `(string: )` - The OAuth Client Secret from the provider for OIDC roles. -- `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 `oidc_discovery_url`. +- `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 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: )` - 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. - `jwt_supported_algs` `(comma-separated string, or array of strings: )` - A list of supported signing algorithms. Defaults to [RS256]. ([Available algorithms](https://github.com/hashicorp/vault-plugin-auth-jwt/blob/master/vendor/github.com/coreos/go-oidc/jose.go#L7)) - `default_role` `(string: )` - The default role to use if none is provided during login. diff --git a/website/source/docs/auth/jwt.html.md b/website/source/docs/auth/jwt.html.md index a49cb54cd..8a60daf6c 100644 --- a/website/source/docs/auth/jwt.html.md +++ b/website/source/docs/auth/jwt.html.md @@ -24,6 +24,23 @@ Both methods allow additional processing of the claims data in the JWT. Some of the concepts common to both methods will be covered first, followed by specific examples of OIDC and JWT usage. +### JWT Verification + +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. + +- **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. + +- **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. + +If multiple methods are needed, another instance of the backend can be mounted and configured +at a different path. + ### Bound Claims Once a JWT has been validated as being properly signed and not expired, the From 1d2757e0bbc41d468d83904d012c61193288e68e Mon Sep 17 00:00:00 2001 From: Jim Kalafut Date: Thu, 9 May 2019 13:35:41 -0700 Subject: [PATCH 2/2] changelog++ --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b6e3e84ce..61c37dcb7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ CHANGES: IMPROVEMENTS: + * auth/jwt: A JWKS endpoint may now be configured for signature verification [JWT-43] * ui: KV v1 and v2 will now gracefully degrade allowing a write without read workflow in the UI [GH-6570]