upstream/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2026-02-18 18:38:08 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions 7

Remove beta docs (#6431)

Browse source
This commit is contained in:
Jim Kalafut 2019-03-18 16:38:54 -07:00 committed by GitHub
parent da7bc7d799
commit b69038248f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 269 additions and 694 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

128
website/source/api/auth/jwt/index.html.md
View file

@ -32,9 +32,12 @@ set.
- `oidc_discovery_url` `(string: <optional>)` - The OIDC Discovery URL, without any .well-known component (base path). Cannot be used with `jwt_validation_pubkeys`.
- `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.
- `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.
- `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 `oidc_discovery_url`.
- `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]. ([Available algorithms](https://github.com/hashicorp/vault-plugin-auth-jwt/blob/master/vendor/github.com/coreos/go-oidc/jose.go#L7))
- `default_role` `(string: <optional>)` - 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: <required>)` - Name of the role.
- `role_type` `(string: <optional>)` - Type of role, either "oidc" (default) or "jwt".
- `bound_audiences` `(array: <required>)` - List of `aud` claims to match
against. Any match is sufficient.
- `user_claim` `(string: <required>)` - 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: <optional>)` - 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: <optional>)` - If set, a map of claims/values to match against.
- `groups_claim` `(string: <optional>)` - 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: <optional>)` - If set, a map of claims (keys) to be copied to
specified metadata fields (values).
- `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.
### 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: <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://.../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: <required>)` - 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: <required>)` - 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: <required>)` - 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: <required>)` - Name of the role against which the login is being
attempted.
- `role` `(string: <optional>)` - Name of the role against which the login is being
attempted. Defaults to configured `default_role` if not provided.
- `jwt` `(string: <required>)` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT).
### Sample Payload

410
website/source/api/auth/jwt/index_beta.html.md
View file

@ -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: <optional>)` - The OIDC Discovery URL, without any .well-known component (base path). Cannot be used with `jwt_validation_pubkeys`.
- `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.
- `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.
- `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 `oidc_discovery_url`.
- `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]. ([Available algorithms](https://github.com/hashicorp/vault-plugin-auth-jwt/blob/master/vendor/github.com/coreos/go-oidc/jose.go#L7))
- `default_role` `(string: <optional>)` - 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: <required>)` - Name of the role.
- `role_type` `(string: <optional>)` - Type of role, either "oidc" (default) or "jwt".
- `bound_audiences` `(array: <required>)` - List of `aud` claims to match
against. Any match is sufficient.
- `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.
- `policies` `(array: <optional>)` - Policies to be set on tokens issued using
this role.
- `ttl` `(int: <optional>)` - The initial/renewal TTL of tokens issued using
this role, in seconds.
- `max_ttl` `(int: <optional>)` - The maximum allowed lifetime of tokens issued
using this role, in seconds.
- `period` `(int: <optional>)` - 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: <optional>)` - If set, puts a use-count limitation on the
issued token.
- `bound_subject` `(string: <optional>)` - If set, requires that the `sub`
claim matches this value.
- `bound_cidrs` `(array: <optional>)` - 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: <optional>)` - If set, a map of claims/values to match against.
- `groups_claim` `(string: <optional>)` - 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: <optional>)` - If set, a map of claims (keys) to be copied to
specified metadata fields (values).
- `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.
### 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: <required>)` - 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: <required>)` - 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: <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://.../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: <required>)` - 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: <required>)` - 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: <required>)` - 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: <optional>)` - Name of the role against which the login is being
attempted. Defaults to configured `default_role` if not provided.
- `jwt` `(string: <required>)` - 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
},
...
}
```

2
website/source/api/system/unseal.html.md
View file

@ -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.

16
website/source/docs/agent/caching/index.html.md
View file

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Vault Agent Caching"
sidebar_title: "Caching <sup>BETA</sup>"
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

162
website/source/docs/auth/jwt.html.md
View file

@ -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: `"<JWT claim>":"<metadata key>"`. 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:

245
website/source/docs/auth/jwt_beta.html.md
View file

@ -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: `"<JWT claim>":"<metadata key>"`. 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.