Configure JWT authentication

Overview

Vault can authenticate users using JWT access tokens generated by an external identity provider. When Vault receives a JWT access token, it verifies the token's signature and validates the claims in the token. If the token is valid, Vault uses the roles claim in the token to choose the roles of the user.

The JWT access token is validated for each request to determine that:

• It is active (not expired).
• These claims match the setting in the IAM configuration:
  • iss
  • aud
  • kid
• The roles claim contains only one role and that role exists in the IAM configuration.
• It is signed using the public key set in the IAM configuration.

Learn how to configure JWT authentication

You can configure Vault to authenticate users using JWT access tokens generated by an external identity provider. This guide shows you how to configure Vault to authenticate users using JWT access tokens.

Prerequisites

You should know the following information about the JWT access token:

• The issuer (iss).
• The audience (aud).
• The key ID (kid).
• The public key of the key-pair used to sign it.

For this guide, you use jwt.io to generate a JWT access token for testing purposes. For production, you should use an identity provider such as Auth0, Azure AD, etc.

Walkthrough

For this guide, use the following values for the JWT access token:

• The issuer (iss) of the JWT access token is https://jwt.io/
• The audience (aud) of the JWT access token is vault1
• The key ID (kid) of the JWT access token is abc

You generate a key-pair using the following command:

openssl genrsa -out pvault_jwt_private_key.pem 2048
openssl rsa -pubout -in pvault_jwt_private_key.pem -out pvault_jwt_public_key.pem

And turn it into JWT format using a JWK Creator. Identity providers such as Auth0 provide you with a URL to a JWKS endpoint that contains the public key in JWT format.

1. In the IAM configuration file, edit the section defining the IdPs, such as [idps.app1], like this:

[idps]

[idps.app1]
    type = "direct-jwt"

[idps.app1.conf]
    iss = "https://jwt.io/"
    aud = "vault1"
    kid = "abc"
    # Change the value of "keys" to the JWK key.
    keys = "{\"kty\": \"RSA\",\"n\": \"o54d-ACKhVI8-sEX57zGyzpf83cISFNBT1HqY78eQP0bKzX6q5RGAtZS4FixzivS76Gv830sTb50d_qjtgCw8XWjnvPj0sTuYOT4D3wNlInziEaSVwsGQ7zf5BPAHs0sLb5skBRB_YFbcIEhe3uK35vLpz-JqRjoRUdhOJe63gWxx4kcQQRQw9760Zoywkf1YPU3S1klViGoNMelkuYP35Djk1qGM2ELhGXSlaON_1KpfvGNKyNfBZGj4SSJJcIOHcjYEQV0Y8UTUe-AWcz3GKesnulqhaKL7VHjXMlHfdy-j1HBa1PCWMHDWBBsv_OCrY-BSfE7KgTd89UTiTr0lQ\",\"e\": \"AQAB\",\"alg\": \"RS256\",\"kid\": \"abc\",\"use\": \"sig\"}"
    # roles_claim = "roles" # optional, defaults to "roles". To be used if the IDP uses a different claim name for roles.

2. Apply the IAM configuration to Vault.

3. Generate a JWT access token on jwt.io. The headers section should look like this:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "abc"
}

The payload section should look like this:

{
  "iss": "https://jwt.io/",
  "aud": "vault1",
  "sub": "our-jwt-user",
  "exp": 1797026866, // Set an expiration time in the future.
  "roles": ["VaultAdmin"]
}

4. Use the JWT access token to authenticate to Vault:

pvault --authtoken <jwt-token> version

IDPs

Auth0

Basically follow the steps in the Walkthrough section, but notice that by default an access token generated by Auth0 does not contain the roles claim. You need to add an login flow Action to your Auth0 tenant to add an equivalent claim to the access token:

exports.onExecutePostLogin = async (event, api) => {
  if (event.authorization) {
    api.accessToken.setCustomClaim("my-roles", event.authorization.roles);
  }
}

Notice how the claim name is not roles, but my-roles. This is because roles is a restricted claim on Auth0 platform. Vault's IAM configuration should be changed accordingly, by setting the roles_claim option to my-roles:

[idps]

[idps.app1]
    type = "direct-jwt"

[idps.app1.conf]
    ...
    roles_claim = "my-roles"

The JWKS endpoint for Auth0 can be found at https://<tenant>.auth0.com/.well-known/jwks.json.