203269a5d4
* Fix argument name in JWT/OIDC login CLI example * Fix groups_claim documented as required when creating roles for JWT/OIDC
300 lines
8 KiB
Markdown
300 lines
8 KiB
Markdown
---
|
|
layout: "api"
|
|
page_title: "JWT/OIDC - Auth Methods - HTTP API"
|
|
sidebar_current: "docs-http-auth-jwt"
|
|
description: |-
|
|
This is the API documentation for the Vault JWT authentication
|
|
method plugin.
|
|
---
|
|
|
|
# JWT Auth Method (API)
|
|
|
|
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.
|
|
- `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.
|
|
|
|
### 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.
|
|
- `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.
|
|
- `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.
|
|
|
|
### 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"
|
|
}
|
|
```
|
|
|
|
### 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/roles` | `200 application/json` |
|
|
|
|
### Sample Request
|
|
|
|
```
|
|
$ curl \
|
|
--header "X-Vault-Token: ..." \
|
|
--request LIST \
|
|
https://127.0.0.1:8200/v1/auth/jwt/roles
|
|
```
|
|
|
|
### 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
|
|
```
|
|
|
|
## 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` |
|
|
|
|
### Sample Payload
|
|
|
|
- `role` `(string: <required>)` - Name of the role against which the login is being
|
|
attempted.
|
|
- `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
|
|
},
|
|
...
|
|
}
|
|
```
|