OAuth resource server configuration

The OAuth resource server configuration is a Vault Enterprise feature that defines how Vault validates JSON Web Tokens (JWTs) issued by OAuth 2.0 authorization servers (called OAuth JWTs in Vault). By configuring one or more validation profiles, you establish trust relationships between Vault and external identity providers, enabling Vault to accept their JWTs as authentication credentials on every request without a separate login step.

This configuration positions Vault as an OAuth 2.0 resource server. Each profile tells Vault which issuer to trust, how to verify token signatures, and which claims to enforce.

For API usage details, refer to the /sys/config/oauth-resource-server documentation.

Profiles

A profile defines how Vault validates JWTs from a specific authorization server. Each profile represents a trust relationship with one issuer. You can configure multiple profiles to accept tokens from different authorization servers.

When Vault receives an OAuth JWT, it extracts the iss (issuer) claim and looks up the corresponding profile. If no profile matches the issuer, Vault rejects the token.

Profile fields

Field	Description
`name`	Unique name for the profile within the namespace. Used as the path identifier in API operations.
`config_id`	Stable unique identifier generated by Vault when the profile is created.
`issuer_id`	The expected `iss` claim value. Must be unique across all profiles in the namespace. Required on create.
`use_jwks`	If `true`, Vault fetches public keys from a JWKS endpoint. If `false`, Vault uses static PEM-encoded public keys. Defaults to `true`.
`jwks_uri`	The JWKS endpoint URI to fetch signing keys from. Required when `use_jwks` is `true`.
`jwks_ca_pem`	Optional CA certificate (PEM-encoded) for TLS verification of the JWKS endpoint.
`public_keys`	List of static public keys, each with a `key_id` and `pem` field. Required when `use_jwks` is `false`.
`audiences`	List of allowed `aud` claim values.
`user_claim`	The JWT claim that identifies the user. Defaults to `sub`.
`supported_algorithms`	List of accepted signing algorithms (for example, `RS256`, `ES256`).
`jwt_type`	The expected token type: `access_token` or `transaction_token`. Defaults to `access_token`.
`clock_skew_leeway`	Tolerance in seconds for clock differences when validating time-based claims.
`no_default_policy`	If `true`, tokens authenticated through the profile do not automatically receive the `default` policy.
`enabled`	If `false`, the profile is ignored during JWT validation. Defaults to `true`.

Key validation modes

Each profile uses exactly one of two mutually exclusive modes for validating JWT signatures:

JWKS mode (use_jwks=true): Vault fetches the authorization server's public keys from the configured jwks_uri. Vault caches these keys and refreshes them when it encounters an unrecognized key ID, subject to rate limiting to prevent abuse.
Static key mode (use_jwks=false): Vault uses PEM-encoded public keys provided directly in the profile configuration. Each key includes a key_id that Vault matches against the JWT kid header.

You cannot configure both jwks_uri and public_keys on the same profile.

Supported algorithms

Profiles accept asymmetrically signed JWTs only. The following signing algorithms are supported:

RSA: RS256, RS384, RS512, PS256, PS384, PS512
ECDSA: ES256, ES384, ES512

HMAC algorithms (HS256, HS384, HS512), opaque tokens, and JWE (JSON Web Encryption) are not supported.

Issuer uniqueness

Each issuer_id must be unique across all profiles in a namespace. This constraint enables Vault to perform a direct lookup from the JWT iss claim to the correct profile without scanning all profiles.

Enabling and disabling profiles

Set enabled to false to disable a profile without deleting it. Disabled profiles are skipped during JWT validation. This allows you to temporarily suspend trust for a specific issuer without losing the profile configuration.

Namespace isolation

Profiles are scoped to the namespace in which they are created:

Profiles in the root namespace are accessible only within the root namespace.
Profiles in a child namespace are accessible only within that child namespace.
There is no cross-namespace visibility or inheritance of profiles.

Each namespace maintains its own independent set of profiles with its own issuer uniqueness constraint.

How profiles are used

When a client presents an OAuth JWT in the X-Vault-Token header, Vault uses the configured profiles to validate the token. Vault extracts the iss claim, finds the matching enabled profile, verifies the token signature against the profile's keys, and checks the token's claims (audience, expiration, and required fields) against the profile's settings.

After validation, Vault resolves the caller's identity through a Vault Identity entity alias bound to the profile's issuer and the value of the configured user_claim. The entity's policies become the caller's baseline permissions.

Note

Vault requires an Agent Registry record for the entity that acts as the agent in the request. In a delegated (on-behalf-of) request, the actor must have a registration. In a non-delegated request, the subject must have a registration.

Managing profiles

You manage profiles through the sys/config/oauth-resource-server path:

Path	Operations	Description
`sys/config/oauth-resource-server`	List	Every profile `name` in the namespace.
`sys/config/oauth-resource-server/<name>`	Create, Read, Update, Delete	The profile whose `name` matches the value you provide.

For complete request and response schemas, refer to the /sys/config/oauth-resource-server documentation.