Skip to main content

IAM configuration examples for JWT authentication

Discover examples of the IAM configurations for various identity providers for use with JWT authentication​

This page includes examples of the IAM configuration for various IdPs and symmetric keys.

Auth0​

An access token generated by Auth0 doesn't contain the roles claim. To add an equivalent claim to the access token, you add this Action to a Login trigger in your Auth0 tenant:

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

Because roles is a restricted claim on the Auth0 platform, the resulting claim name is my-roles not roles. Therefore, you must set roles_claim to my-roles in Vault's IAM configuration.

Auth0 also provides a URL to a JWKS endpoint that contains the public key in JWT format. You can find this value in the Auth0 console. In the Dashboard, open Applications, Advanced Settings, then Endpoints. The endpoint has the format of https://<tenant-id>.<region>.auth0.com/.well-known/jwks.json.

To simplify identifying log message messages relating to Auth0 tokens for this tenant, consider setting the ISS value to the host value.

[idps]

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

[idps.app1.conf]
  iss = "https://abc.abc.auth0.com" 
  aud = "my-app" # Configured by your application.
  roles_claim = "my-roles"
  jwks_uri = "https://abc.abc.auth0.com/.well-known/jwks.json"

Google Cloud Platform​

You can use token authentication and authorization when you deploy your backend application on a Google Cloud Platform (GCP) service such as Cloudrun. In this case, GCP generates an ID token.

To configure Vault IAM to support the ID token:

  • In the conf table, set.

    • jwks_uri to the GCP certificate hosting URL, i.e., "https://www.googleapis.com/oauth2/v3/certs"
    • iss to "https://accounts.google.com".
    • aud to the audience you use when generating the ID token. For example, "https://my-cloud-run-service.a.run.app/"
    • roles_claim to "email", as the token created by GCP places the role you want to claim in the email key of the JWT token it generates. See Google identity guide to validating ID tokens for more information.

  • In the conf table bound_claims sub-table set email_verified = true

    • In the roles_map table, map the email of the service account used to authenticate with Vault to the Vault role assigned to it. This mapping takes the format "<your-backend-service-account-email>" = "<role-in-vault>". For example, "my-product-prod-sa@myproject.iam.gserviceaccount.com" = "VaultAdmin".

The resulting configuration looks something like this:

[idps]

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

[idps.app1.conf]
  jwks_uri    = "https://www.googleapis.com/oauth2/v3/certs"
  iss         = "https://accounts.google.com"
  aud         = "https://my-cloud-run-service.a.run.app/"
  roles_claim = "email"

[idps.app1.conf.bound_claims]
  email_verified = true

[idps.app1.roles_map]
  "myemail@example.com" = "VaultAdmin"

You can generate an ID token using this Go code:

func GenerateIDToken(ctx context.Context) (string, error) {
  // The audience should match the "aud" field in the IAM configuration.
  ts, err := idtoken.NewTokenSource(ctx, "https://my-cloud-run-service.a.run.app/")
  if err != nil {
    return"  ", fmt.Errorf("idtoken.NewTokenSource: %w", err)
  }

  token, err := ts.Token()
  if err != nil {
    return "", fmt.Errorf("ts.Token: %w", err)
  }

  return token.AccessToken, nil
}

See Get an ID token from the metadata server to learn more about ID token generation and find code samples for other languages.

Keys configuration for symmetric keys​

So Vault can verify the signature of a JWT with a public key without being able to generate new tokens itself, use asymmetric keys for JWT authentication (e.g., RS256 or ES256 signing algorithms).

To use asymmetric keys, externalize the key configuration to a secret file, such as /etc/pvault/secrets/secrets_iam_app1_jwt_hs256_key/content or PVAULT_SECRETS_IAM_APP1_JWT_HS256_KEY IAM secrets environment variable for better security.

You then configure Vault to use the asymmetric key for JWT verification by referencing the asymmetric key in the keys key of the conf table. For example, if you externalize the key to an environment variable, the resulting configuration is:

[idps]

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

[idps.app1.conf]
keys = "{\"kty\": \"oct\",\"k\": \"${secret:APP1_JWT_HS256_KEY}\",\"alg\": \"HS256\",\"kid\": \"abc\"}"

On this page