open-vault/website/source/api/auth/jwt/index.html.md.erb

---
layout: "api"
page_title: "JWT/OIDC - Auth Methods - HTTP API"
sidebar_title: "JWT/OIDC"
sidebar_current: "api-http-auth-jwt-oidc"
description: |-
  This is the API documentation for the Vault JWT/OIDC authentication
  method plugin.
---

# JWT/OIDC Auth Method (API)

This is the API documentation for the Vault JWT/OIDC auth method
plugin. To learn more about the usage and operation, see the
[Vault JWT/OIDC 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                         |
| :--------------------------- | :--------------------- |
| `POST`   | `/auth/jwt/config`           |

### Parameters

- `oidc_discovery_url` `(string: <optional>)` - 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: <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.
- `jwks_url` `(string: <optional>)` - JWKS URL to use to authenticate signatures. Cannot be used with "oidc_discovery_url" or "jwt_validation_pubkeys".
- `jwks_ca_pem` `(string: <optional>)` - 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: <optional>)` - 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: <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                         |
| :--------------------------- | :--------------------- |
| `GET`    | `/auth/jwt/config`           |

### 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                         |
| :--------------------------- | :--------------------- |
| `POST`   | `/auth/jwt/role/:name`       |

### Parameters
- `name` `(string: <required>)` - Name of the role.
- `role_type` `(string: <optional>)` - Type of role, either "oidc" (default) or "jwt".
- `bound_audiences` `(array: <optional>)` - List of `aud` claims to match against.
   Any match is sufficient. Required for "jwt" roles, optional for "oidc" roles. 
- `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.
- `clock_skew_leeway` `(int: <optional>)` - The amount of leeway to add to all claims to 
  account for clock skew, in seconds.  Defaults to `60` seconds if set to `0` and can be disabled
  if set to `-1`. Only applicable with "jwt" roles.
- `expiration_leeway` `(int: <optional>)` - The amount of leeway to add to expiration (`exp`) claims to 
  account for clock skew, in seconds. Defaults to `150` seconds if set to `0` and can be disabled
  if set to `-1`. Only applicable with "jwt" roles. 
- `not_before_leeway` `(int: <optional>)` - The amount of leeway to add to not before (`nbf`) claims to 
  account for clock skew, in seconds. Defaults to `150` seconds if set to `0` and can be disabled
  if set to `-1`. Only applicable with "jwt" roles. 
- `bound_subject` `(string: <optional>)` - If set, requires that the `sub`
  claim matches this value.
- `bound_claims` `(map: <optional>)` - If set, a map of claims/values to match against.
  The expected value may be a single string or a list of strings.
- `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.

<%= partial "partials/tokenfields" %>

### 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                         |
| :--------------------------- | :--------------------- |
| `GET`   | `/auth/jwt/role/:name`        |

### 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                         |
| :--------------------------- | :--------------------- |
| `LIST`   | `/auth/jwt/role`            |

### 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                         |
| :--------------------------- | :--------------------- |
| `DELETE` | `/auth/jwt/role/:name`       |

### 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                         |
| :--------------------------- | :--------------------- |
| `POST`   | `/auth/jwt/oidc/auth_url`    |

### 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/ui/vault/auth/jwt/oidc/callback"
}
```

### Sample Request

```
$ curl \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/jwt/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=https%3A%2F%2Fvault.myco.com3A8200%2Fui%2Fvault%2Fauth%2Fjwt%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                         |
| :--------------------------- | :--------------------- |
| `GET`    | `/auth/jwt/oidc/callback`    |

### 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                         |
| :--------------------------- | :--------------------- |
| `POST`   | `/auth/jwt/login`            |

### 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
    },
    ...
}
```