open-vault/website/source/docs/auth/jwt.html.md

layout	page_title	sidebar_title	sidebar_current	description
docs	JWT - Auth Methods	JWT	docs-auth-jwt	The JWT auth method allows authentication using JWTs, with support for OIDC Discovery for key fetching

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) for documentation that includes these beta features.

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.

Authentication

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.

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

$ 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:

{
  "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:

   $ vault auth enable jwt
   

2. Use the /config endpoint to configure Vault with local keys or an OIDC Discovery URL. For the list of available configuration options, please see the API documentation.

   $ vault write auth/jwt/config \
       oidc_discovery_url="https://myco.auth0.com/"
   

3. Create a named role:

   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 for more details.