diff --git a/website/source/api/auth/jwt/index.html.md b/website/source/api/auth/jwt/index.html.md index 54f1e2110a..fa1eb7ce62 100644 --- a/website/source/api/auth/jwt/index.html.md +++ b/website/source/api/auth/jwt/index.html.md @@ -32,9 +32,12 @@ set. - `oidc_discovery_url` `(string: )` - The OIDC Discovery URL, without any .well-known component (base path). Cannot be used with `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`. - `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. ### Sample Payload @@ -98,6 +101,7 @@ entities attempting to login. At least one of the bound values must be set. ### Parameters - `name` `(string: )` - Name of the role. +- `role_type` `(string: )` - Type of role, either "oidc" (default) or "jwt". - `bound_audiences` `(array: )` - List of `aud` claims to match against. Any match is sufficient. - `user_claim` `(string: )` - The claim to use to uniquely identify @@ -119,17 +123,17 @@ entities attempting to login. At least one of the bound values must be set. - `bound_cidrs` `(array: )` - If set, a list of CIDRs valid as the source address for login requests. This value is also encoded into any resulting token. +- `bound_claims` `(map: )` - If set, a map of claims/values to match against. - `groups_claim` `(string: )` - 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. -- `groups_claim_delimiter_pattern` `(string: optional)` - A pattern of - delimiters used to allow the `groups_claim` to live outside of the top-level - JWT structure. For instance, a `groups_claim` of `meta/user.name/groups` with - this field set to `//` will expect nested structures named `meta`, - `user.name`, and `groups`. If this field was set to `/./` the groups - information would expect to be via nested structures of `meta`, `user`, - `name`, and `groups`. +- `claim_mappings` `(map: )` - If set, a map of claims (keys) to be copied to + specified metadata fields (values). +- `oidc_scopes` `(list: )` - 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: )` - The list of allowed values for redirect_uri + during OIDC logins. ### Sample Payload @@ -142,7 +146,15 @@ entities attempting to login. At least one of the bound values must be set. "bound_subject": "sl29dlldsfj3uECzsU3Sbmh0F29Fios1@clients", "bound_audiences": "https://myco.test", "user_claim": "https://vault/user", - "groups_claim": "https://vault/groups" + "groups_claim": "https://vault/groups", + "bound_claims": { + "department": "engineering", + "sector": "7g" + }, + "claim_mappings": { + "preferred_language": "language", + "group": "group" + } } ``` @@ -221,7 +233,7 @@ $ curl \ ### Sample Response -```json +```json { "data": { "keys": [ @@ -254,7 +266,97 @@ $ curl \ https://127.0.0.1:8200/v1/auth/jwt/role/dev-role ``` -## Login +## OIDC Authorization URL Request + +Obtain an authorization URL from Vault to start an OIDC login flow. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/jwt/oidc/auth_url` | `200 application/json` | + +### Parameters + +- `role` `(string: )` - Name of the role against which the login is being + attempted. Defaults to configured `default_role` if not provided. +- `redirect_uri` `(string: )` - 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 Vault + server location, port, and the mount of the JWT plugin. This must be configured with Vault and the + provider. See [Redirect URIs](/docs/auth/jwt.html#redirect-uris) for more information. + +### Sample Payload + +```json +{ + "role": "dev-role", + "redirect_uri": "https://vault.myco.com:8200/vault/ui/auth/jwt/oidc/callback" +} +``` + +### Sample Request + +``` +$ curl \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/auth/oidc/auth_url +``` + +### 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=http%3A%2F%2Flocalhost%3A8300%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 a Vault token will be returned. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/jwt/oidc/callback` | `200 application/json` | + +### Parameters + +- `state` `(string: )` - Opaque state ID that is part of the Authorization URL and will + be included in the the redirect following successful authenication on the provider. +- `nonce` `(string: )` - Opaque nonce that is part of the Authorization URL and will + be included in the the redirect following successful authenication on the provider. +- `code` `(string: )` - Provider-generated authorization code that Vault will exchange for + an ID token. + +### Sample Request + +``` +$ 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 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 @@ -264,10 +366,10 @@ entity and then authorizes the entity for the given role. | :------- | :--------------------------- | :--------------------- | | `POST` | `/auth/jwt/login` | `200 application/json` | -### Sample Payload +### Parameters -- `role` `(string: )` - Name of the role against which the login is being - attempted. +- `role` `(string: )` - Name of the role against which the login is being + attempted. Defaults to configured `default_role` if not provided. - `jwt` `(string: )` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT). ### Sample Payload diff --git a/website/source/api/auth/jwt/index_beta.html.md b/website/source/api/auth/jwt/index_beta.html.md deleted file mode 100644 index a67485d2c4..0000000000 --- a/website/source/api/auth/jwt/index_beta.html.md +++ /dev/null @@ -1,410 +0,0 @@ ---- -layout: "api" -page_title: "JWT (Beta) - Auth Methods - HTTP API" -sidebar_title: "JWT" -sidebar_current: "api-http-auth-jwt" -description: |- - This is the API documentation for the Vault JWT authentication - method plugin. ---- - -# JWT Auth Method (API) (Beta) - -This is the API documentation for the Vault JWT auth method -plugin. To learn more about the usage and operation, see the -[Vault JWT method documentation](/docs/auth/jwt.html). - -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` and `jwt_validation_pubkeys` must be -set. - -| Method | Path | Produces | -| :------- | :--------------------------- | :--------------------- | -| `POST` | `/auth/jwt/config` | `204 (empty body)` | - -### 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_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`. -- `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. - -### Sample Payload - -```json -{ - "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 | Produces | -| :------- | :--------------------------- | :--------------------- | -| `GET` | `/auth/jwt/config` | `200 application/json` | - -### Sample Request - -``` -$ 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 | Produces | -| :------- | :--------------------------- | :--------------------- | -| `POST` | `/auth/jwt/role/:name` | `204 (empty body)` | - -### Parameters -- `name` `(string: )` - Name of the role. -- `role_type` `(string: )` - Type of role, either "oidc" (default) or "jwt". -- `bound_audiences` `(array: )` - List of `aud` claims to match - against. Any match is sufficient. -- `user_claim` `(string: )` - 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. -- `policies` `(array: )` - Policies to be set on tokens issued using - this role. -- `ttl` `(int: )` - The initial/renewal TTL of tokens issued using - this role, in seconds. -- `max_ttl` `(int: )` - The maximum allowed lifetime of tokens issued - using this role, in seconds. -- `period` `(int: )` - If set, indicates that the token generated - using this role should never expire, but instead always use the value set - here as the TTL for every renewal. -- `num_uses` `(int: )` - If set, puts a use-count limitation on the - issued token. -- `bound_subject` `(string: )` - If set, requires that the `sub` - claim matches this value. -- `bound_cidrs` `(array: )` - If set, a list of CIDRs valid as the - source address for login requests. This value is also encoded into any - resulting token. -- `bound_claims` `(map: )` - If set, a map of claims/values to match against. -- `groups_claim` `(string: )` - 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. -- `claim_mappings` `(map: )` - If set, a map of claims (keys) to be copied to - specified metadata fields (values). -- `oidc_scopes` `(list: )` - 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: )` - The list of allowed values for redirect_uri - during OIDC logins. - -### Sample Payload - -```json -{ - "policies": [ - "dev", - "prod" - ], - "bound_subject": "sl29dlldsfj3uECzsU3Sbmh0F29Fios1@clients", - "bound_audiences": "https://myco.test", - "user_claim": "https://vault/user", - "groups_claim": "https://vault/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 | Produces | -| :------- | :--------------------------- | :--------------------- | -| `GET` | `/auth/jwt/role/:name` | `200 application/json` | - -### Parameters - -- `name` `(string: )` - 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 - -```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 | Produces | -| :------- | :--------------------------- | :--------------------- | -| `LIST` | `/auth/jwt/role` | `200 application/json` | - -### Sample Request - -``` -$ curl \ - --header "X-Vault-Token: ..." \ - --request LIST \ - https://127.0.0.1:8200/v1/auth/jwt/role -``` - -### Sample Response - -```json -{ - "data": { - "keys": [ - "dev-role", - "prod-role" - ] - }, - ... -} -``` - -## Delete Role - -Deletes the previously registered role. - -| Method | Path | Produces | -| :------- | :--------------------------- | :--------------------- | -| `DELETE` | `/auth/jwt/role/:name` | `204 (empty body)` | - -### Parameters - -- `name` `(string: )` - 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 Vault to start an OIDC login flow. - -| Method | Path | Produces | -| :------- | :--------------------------- | :--------------------- | -| `POST` | `/auth/jwt/oidc/auth_url` | `200 application/json` | - -### Parameters - -- `role` `(string: )` - Name of the role against which the login is being - attempted. Defaults to configured `default_role` if not provided. -- `redirect_uri` `(string: )` - 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 Vault - server location, port, and the mount of the JWT plugin. This must be configured with Vault and the - provider. See [Redirect URIs](/docs/auth/jwt.html#redirect-uris) for more information. - -### Sample Payload - -```json -{ - "role": "dev-role", - "redirect_uri": "https://vault.myco.com:8200/vault/ui/auth/jwt/oidc/callback" -} -``` - -### Sample Request - -``` -$ curl \ - --request POST \ - --data @payload.json \ - https://127.0.0.1:8200/v1/auth/oidc/auth_url -``` - -### 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=http%3A%2F%2Flocalhost%3A8300%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 a Vault token will be returned. - -| Method | Path | Produces | -| :------- | :--------------------------- | :--------------------- | -| `GET` | `/auth/jwt/oidc/callback` | `200 application/json` | - -### Parameters - -- `state` `(string: )` - Opaque state ID that is part of the Authorization URL and will - be included in the the redirect following successful authenication on the provider. -- `nonce` `(string: )` - Opaque nonce that is part of the Authorization URL and will - be included in the the redirect following successful authenication on the provider. -- `code` `(string: )` - Provider-generated authorization code that Vault will exchange for - an ID token. - -### Sample Request - -``` -$ 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 - -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 | Produces | -| :------- | :--------------------------- | :--------------------- | -| `POST` | `/auth/jwt/login` | `200 application/json` | - -### Parameters - -- `role` `(string: )` - Name of the role against which the login is being - attempted. Defaults to configured `default_role` if not provided. -- `jwt` `(string: )` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT). - -### Sample Payload - -```json -{ - "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 - -```json -{ - "auth":{ - "client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c", - "accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d", - "policies":[ - "default", - "dev", - "prod" - ], - "lease_duration":2764800, - "renewable":true - }, - ... -} -``` diff --git a/website/source/api/system/unseal.html.md b/website/source/api/system/unseal.html.md index a7c421a30a..f304369b04 100644 --- a/website/source/api/system/unseal.html.md +++ b/website/source/api/system/unseal.html.md @@ -33,7 +33,7 @@ Either the `key` or `reset` parameter must be provided; if both are provided, - `reset` `(bool: false)` – Specifies if previously-provided unseal keys are discarded and the unseal process is reset. -- `migrate` `(bool: false)` - Available in 1.0 Beta - Used to migrate the seal +- `migrate` `(bool: false)` - Available in 1.0 - Used to migrate the seal from shamir to autoseal or autoseal to shamir. Must be provided on all unseal key calls. diff --git a/website/source/docs/agent/caching/index.html.md b/website/source/docs/agent/caching/index.html.md index 6dd2498377..6fb8658009 100644 --- a/website/source/docs/agent/caching/index.html.md +++ b/website/source/docs/agent/caching/index.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "Vault Agent Caching" -sidebar_title: "Caching BETA" +sidebar_title: "Caching" sidebar_current: "docs-agent-caching" description: |- Vault Agent Caching allows client-side caching of responses containing newly @@ -17,11 +17,9 @@ newly created tokens. The renewals of the cached tokens and leases are also managed by the agent. -> **Note:** Vault Agent Caching works best with servers/clusters that are -running on Vault 1.1-beta2 and above due to changes that were introduced +running on Vault 1.1 and above due to changes that were introduced alongside this feature, such as the exposure of the `orphan` field in token -creation responses. Agent caching functionality was tested against changes -introduced within 1.1 and thus full caching capabilities may not behave as -expected when paired with older server versions. +creation responses. ## Caching and Renewals @@ -52,14 +50,6 @@ configuration will be overridden if the request already has a token attached, in which case, the token present in the request will be used to forward the request to the Vault server. --> **Note:** In Vault 1.1-beta1, if the request doesn't already contain a Vault -token, then the `auto-auth` token will be used to make requests. However, the -resulting secrets from these `auto-auth` token calls are not cached. This -behavior will be changed so that they get cached in the upcoming versions. To -test the caching scenarios in 1.1-beta1, please make login requests or token -creation requests via the agent. These new tokens and their respective leased -secrets will get cached. - ## Cache Evictions The eviction of cache entries pertaining to secrets will occur when the agent diff --git a/website/source/docs/auth/jwt.html.md b/website/source/docs/auth/jwt.html.md index b3f57c1c8e..221941caed 100644 --- a/website/source/docs/auth/jwt.html.md +++ b/website/source/docs/auth/jwt.html.md @@ -4,22 +4,153 @@ page_title: "JWT - Auth Methods" sidebar_title: "JWT" sidebar_current: "docs-auth-jwt" description: |- - The JWT auth method allows authentication using JWTs, with support for OIDC Discovery for key fetching + The JWT auth method allows authentication using OIDC and user-provided JWTs --- # JWT Auth Method --> **NOTE**: The JWT method is receiving a number of improvements in Vault 1.1 including OIDC -authentication, arbitrary bound claims, copying of metadata and more. These features are available -now in the Vault 1.1 beta. Refer to [JWT Auth Method (Beta)](/docs/auth/jwt_beta.html) for -documentation that includes these beta features. +The `jwt` auth method can be used to authenticate with Vault using +[OIDC](https://en.wikipedia.org/wiki/OpenID_Connect) or by providing a [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token). +The OIDC method will allow authentication via a configured OIDC provider using the user's web browser. +This method may be initiated from the Vault UI or the command line. Alternatively, a JWT can be provided +directly. It will be cryptographically verified using locally-provided keys, or, if configured, an +OIDC Discovery service can be used to fetch the appropriate keys. The choice of method is configured per role. -The `jwt` auth method can be used to authenticate with Vault using a JWT. This -JWT can be cryptographically verified using locally-provided keys, or, if -configured, an OIDC Discovery service can be used to fetch the appropriate -keys. +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. -## Authentication +### Bound Claims + +Once a JWT has been validated as being properly signed and not expired, the authorization flow will validate that any +configured "bound" parameters match. In some cases there are dedicated parameters, for example `bound_subject`, which must +match the JWT's `sub` parameter. A role may also be configured to check arbitrary claims through the `bound_claims` +map. The map contains a set of claims and their required values. For example, assume `bound_claims` is set to: + +```json +{ + "division": "Europe", + "department": "Engineering" +} +``` + +Only JWTs containing both the "division" and "department" claims, and respective matching values of "Europe" and "Engineering", +would be authorized. + +### Claims as Metadata + +Data from claims can be copied into the resulting auth token and alias metadata by configuring `claim_mappings`. This role +parameter is a map of items to copy. The map elements are of the form: `"":""`. Assume +`claim_mappings` is set to: + +```json +{ + "division": "organization", + "department": "department" +} +``` + +This specifies that the value in the JWT claim "division" should be copied to the metadata key "organization". The JWT +"department" claim value will also be copied into metadata but will retain the key name. If a claim is configured in `claim_mappings`, +it must existing in the JWT or else the authentication will fail. + +Note: the metadata key name "role" is reserved and may not be used for claim mappings. + + +### Claim specifications and JSON Pointer + +Some parameters (e.g. `bound_claims` and `groups_claim`) are used to point to data within the JWT. If +the desired key is at the top of level of the JWT, the name can be provided directly. If it is nested at a +lower level, a JSON Pointer may be used. + +Assume the following JSON data to be referenced: + +```json +{ + "division": "North America", + "groups": { + "primary": "Engineering", + "secondary": "Software" + } +} +``` + +A parameter of `"division"` will reference "North America", as this is a top level key. A parameter +`"/groups/primary"` uses JSON Pointer syntax to reference "Engineering" at a lower level. Any valid +JSON Pointer can be used as a selector. Refer to the +[JSON Pointer RFC](https://tools.ietf.org/html/rfc6901) for a full description of the syntax + + +## OIDC Authentication + +This section covers the setup and use of OIDC roles. If a JWT is to be provided directly, +refer to the [JWT Authentication](/docs/auth/jwt.html#jwt-authentication) section below. Basic +familiarity with [OIDC concepts] (https://developer.okta.com/blog/2017/07/25/oidc-primer-part-1) +is assumed. + +Vault includes two built-in OIDC login flows: the Vault UI, and the CLI +using a `vault login`. + +### Redirect URIs + +An important part of OIDC role configuration is properly setting redirect URIs. This must be +done both in Vault and with the OIDC provider, and these configurations must align. The +redirect URIs are specified for a role with the `allowed_redirect_uris` parameter. There are +different redirect URIs to configure the Vault UI and CLI flows, so one or both will need to +be set up depending on the installation. + +**CLI** + +If you plan to support authentication via `vault login -method=oidc`, a localhost redirect URI +must be set. This can usually be: `http://localhost:8250/oidc/callback`. Logins via the CLI may +specify a different listening port if needed, and a URI with this port must match one of the +configured redirected URIs. These same "localhost" URIs must be added to the provider as well. + +**Vault UI** + +Logging in via the Vault UI requires a redirect URI of the form: +`https://{host:port}/ui/vault/auth/{path}/oidc/callback` + +The "host:port" must be correct for the Vault server, and "path" must match the path the JWT +backend is mounted at (e.g. "oidc" or "jwt"). +If [namespaces](https://www.vaultproject.io/docs/enterprise/namespaces/index.html) are being used, +they must be added as query parameters, for example: + +`https://vault.example.com:8200/ui/vault/auth/oidc/oidc/callback?namespace=my_ns` + +### OIDC Login (Vault UI) + +1. Select the "OIDC" login method. +1. Enter a role name if necessary. +1. Press "Sign In" and complete the authentication with the configured provider. + +### OIDC Login (CLI) + +The CLI login defaults to path of `/oidc`. If this auth method was enabled at a +different path, specify `-path=/my-path` in the CLI. The default local listening port is 8250. This +can be changed with the `port` option. + +```text +$ vault login -method=oidc port=8400 role=test + +Complete the login via your OIDC provider. Launching browser to: + + https://myco.auth0.com/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A8400%2Foidc%2Fcallback&client_id=r3qXc2bix9eF... +``` + +The browser will open to the generated URL to complete the provider's login. The +URL may be entered manually if the browser cannot be automatically opened. + +### OIDC Provider Configuration + +The OIDC authentication flow has been successfully tested with a number of providers. A full +guide to configuring OAuth/OIDC applications is beyond the scope of Vault documentation, but a +collection of provider configuration steps has been collected to help get started: +[OIDC Provider Setup](/docs/auth/jwt_oidc_providers.html) + +## JWT Authentication + +The authentication flow for roles of type "jwt" is simpler than OIDC since Vault +only needs to validate the provided JWT. ### Via the CLI @@ -68,18 +199,25 @@ authenticate. These steps are usually completed by an operator or configuration management tool. -1. Enable the JWT auth method: +1. Enable the JWT auth method. Either the "jwt" or "oidc" name may be used. The +backend will be mounted at the chosen name. ```text $ vault auth enable jwt + or + $ vault auth enable oidc ``` -1. Use the `/config` endpoint to configure Vault with local keys or an OIDC Discovery URL. For the +1. Use the `/config` endpoint to configure Vault. To support JWT roles, either local keys 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](/api/auth/jwt/index.html). ```text $ vault write auth/jwt/config \ oidc_discovery_url="https://myco.auth0.com/" + oidc_client_id="m5i8bj3iofytj", + oidc_client_secret="f4ubv72nfiu23hnsj", + default_role="demo" ``` 1. Create a named role: diff --git a/website/source/docs/auth/jwt_beta.html.md b/website/source/docs/auth/jwt_beta.html.md deleted file mode 100644 index 6105da3521..0000000000 --- a/website/source/docs/auth/jwt_beta.html.md +++ /dev/null @@ -1,245 +0,0 @@ ---- -layout: "docs" -page_title: "JWT (Beta) - Auth Methods" -sidebar_title: "JWT" -sidebar_current: "docs-auth-jwt" -description: |- - The JWT auth method allows authentication using OIDC and user-provided JWTs ---- - -# JWT Auth Method (Beta) - -The `jwt` auth method can be used to authenticate with Vault using -[OIDC](https://en.wikipedia.org/wiki/OpenID_Connect) or by providing a [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token). -The OIDC method will allow authentication via a configured OIDC provider using the user's web browser. -This method may be initiated from the Vault UI or the command line. Alternatively, a JWT can be provided -directly. It will be cryptographically verified using locally-provided keys, or, if configured, an -OIDC Discovery service can be used to fetch the appropriate keys. The choice of method is configured per role. - -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. - -### Bound Claims - -Once a JWT has been validated as being properly signed and not expired, the authorization flow will validate that any -configured "bound" parameters match. In some cases there are dedicated parameters, for example `bound_subject`, which must -match the JWT's `sub` parameter. A role may also be configured to check arbitrary claims through the `bound_claims` -map. The map contains a set of claims and their required values. For example, assume `bound_claims` is set to: - -```json -{ - "division": "Europe", - "department": "Engineering" -} -``` - -Only JWTs containing both the "division" and "department" claims, and respective matching values of "Europe" and "Engineering", -would be authorized. - -### Claims as Metadata - -Data from claims can be copied into the resulting auth token and alias metadata by configuring `claim_mappings`. This role -parameter is a map of items to copy. The map elements are of the form: `"":""`. Assume -`claim_mappings` is set to: - -```json -{ - "division": "organization", - "department": "department" -} -``` - -This specifies that the value in the JWT claim "division" should be copied to the metadata key "organization". The JWT -"department" claim value will also be copied into metadata but will retain the key name. If a claim is configured in `claim_mappings`, -it must existing in the JWT or else the authentication will fail. - -Note: the metadata key name "role" is reserved and may not be used for claim mappings. - - -### Claim specifications and JSON Pointer - -Some parameters (e.g. `bound_claims` and `groups_claim`) are used to point to data within the JWT. If -the desired key is at the top of level of the JWT, the name can be provided directly. If it is nested at a -lower level, a JSON Pointer may be used. - -Assume the following JSON data to be referenced: - -```json -{ - "division": "North America", - "groups": { - "primary": "Engineering", - "secondary": "Software" - } -} -``` - -A parameter of `"division"` will reference "North America", as this is a top level key. A parameter -`"/groups/primary"` uses JSON Pointer syntax to reference "Engineering" at a lower level. Any valid -JSON Pointer can be used as a selector. Refer to the -[JSON Pointer RFC](https://tools.ietf.org/html/rfc6901) for a full description of the syntax - - -## OIDC Authentication - -This section covers the setup and use of OIDC roles. If a JWT is to be provided directly, -refer to the [JWT Authentication](/docs/auth/jwt.html#jwt-authentication) section below. Basic -familiarity with [OIDC concepts] (https://developer.okta.com/blog/2017/07/25/oidc-primer-part-1) -is assumed. - -Vault includes two built-in OIDC login flows: the Vault UI, and the CLI -using a `vault login`. - -### Redirect URIs - -An important part of OIDC role configuration is properly setting redirect URIs. This must be -done both in Vault and with the OIDC provider, and these configurations must align. The -redirect URIs are specified for a role with the `allowed_redirect_uris` parameter. There are -different redirect URIs to configure the Vault UI and CLI flows, so one or both will need to -be set up depending on the installation. - -**CLI** - -If you plan to support authentication via `vault login -method=oidc`, a localhost redirect URI -must be set. This can usually be: `http://localhost:8250/oidc/callback`. Logins via the CLI may -specify a different listening port if needed, and a URI with this port must match one of the -configured redirected URIs. These same "localhost" URIs must be added to the provider as well. - -**Vault UI** - -Logging in via the Vault UI requires a redirect URI of the form: -`https://{host:port}/ui/vault/auth/{path}/oidc/callback` - -The "host:port" must be correct for the Vault server, and "path" must match the path the JWT -backend is mounted at (e.g. "oidc" or "jwt"). -If [namespaces](https://www.vaultproject.io/docs/enterprise/namespaces/index.html) are being used, -they must be added as query parameters, for example: - -`https://vault.example.com:8200/ui/vault/auth/oidc/oidc/callback?namespace=my_ns` - -### OIDC Login (Vault UI) - -1. Select the "OIDC" login method. -1. Enter a role name if necessary. -1. Press "Sign In" and complete the authentication with the configured provider. - -### OIDC Login (CLI) - -The CLI login defaults to path of `/oidc`. If this auth method was enabled at a -different path, specify `-path=/my-path` in the CLI. The default local listening port is 8250. This -can be changed with the `port` option. - -```text -$ vault login -method=oidc port=8400 role=test - -Complete the login via your OIDC provider. Launching browser to: - - https://myco.auth0.com/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A8400%2Foidc%2Fcallback&client_id=r3qXc2bix9eF... -``` - -The browser will open to the generated URL to complete the provider's login. The -URL may be entered manually if the browser cannot be automatically opened. - -### OIDC Provider Configuration - -The OIDC authentication flow has been successfully tested with a number of providers. A full -guide to configuring OAuth/OIDC applications is beyond the scope of Vault documentation, but a -collection of provider configuration steps has been collected to help get started: -[OIDC Provider Setup](/docs/auth/jwt_oidc_providers.html) - -## JWT Authentication - -The authentication flow for roles of type "jwt" is simpler than OIDC since Vault -only needs to validate the provided JWT. - -### Via the CLI - -The default path is `/jwt`. If this auth method was enabled at a -different path, specify `-path=/my-path` in the CLI. - -```text -$ vault write auth/jwt/login role=demo jwt=... -``` - -### Via the API - -The default endpoint is `auth/jwt/login`. If this auth method was enabled -at a different path, use that value instead of `jwt`. - -```shell -$ curl \ - --request POST \ - --data '{"jwt": "your_jwt", "role": "demo"}' \ - http://127.0.0.1:8200/v1/auth/jwt/login -``` - -The response will contain a token at `auth.client_token`: - -```json -{ - "auth": { - "client_token": "38fe9691-e623-7238-f618-c94d4e7bc674", - "accessor": "78e87a38-84ed-2692-538f-ca8b9f400ab3", - "policies": [ - "default" - ], - "metadata": { - "role": "demo" - }, - "lease_duration": 2764800, - "renewable": true - } -} -``` - -## Configuration - -Auth methods must be configured in advance before users or machines can -authenticate. These steps are usually completed by an operator or configuration -management tool. - - -1. Enable the JWT auth method. Either the "jwt" or "oidc" name may be used. The -backend will be mounted at the chosen name. - - ```text - $ vault auth enable jwt - or - $ vault auth enable oidc - ``` - -1. Use the `/config` endpoint to configure Vault. To support JWT roles, either local keys 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](/api/auth/jwt/index.html). - - ```text - $ vault write auth/jwt/config \ - oidc_discovery_url="https://myco.auth0.com/" - oidc_client_id="m5i8bj3iofytj", - oidc_client_secret="f4ubv72nfiu23hnsj", - default_role="demo" - ``` - -1. Create a named role: - - ```text - vault write auth/jwt/role/demo \ - bound_subject="r3qX9DljwFIWhsiqwFiu38209F10atW6@clients" \ - bound_audiences="https://vault.plugin.auth.jwt.test" \ - user_claim="https://vault/user" \ - groups_claim="https://vault/groups" \ - policies=webapps \ - ttl=1h - ``` - - This role authorizes JWTs with the given subject and audience claims, gives - it the `webapps` policy, and uses the given user/groups claims to set up - Identity aliases. - - For the complete list of configuration options, please see the API - documentation. - -## API - -The JWT Auth Plugin has a full HTTP API. Please see the -[API docs](/api/auth/jwt/index_beta.html) for more details.