Authentication

Reference for authentication policies — mcpAuthentication, jwtAuth, apiKey, and basicAuth.

The mcpAuthentication policy validates incoming Bearer tokens from MCP clients against a configured OAuth 2.0 / OIDC authorization server. When enabled, Agentgateway enforces token validity before allowing any MCP traffic and optionally serves OAuth 2.0 Protected Resource Metadata at /.well-known/oauth-protected-resource/<path>.

Configuration location

mcpAuthentication is set under binds[].listeners[].routes[].policies:

binds:
- port: 3000
  listeners:
  - routes:
    - policies:
        mcpAuthentication:
          issuer: https://auth.example.com
          audiences:
          - https://gateway.example.com/mcp
          jwks:
            url: https://auth.example.com/.well-known/jwks.json

Fields

issuer · string · required

The expected iss (issuer) claim in the JWT. Must exactly match the issuer URL of your authorization server.

issuer: https://auth.example.com

audiences · string[] · required

A list of accepted aud (audience) values. The token must contain at least one of these values.

audiences:
- https://gateway.example.com/mcp

jwks · object · required

Source of the JSON Web Key Set (JWKS) used to verify token signatures. Exactly one of file or url must be set.

Show jwks fields

jwks.url · string

HTTP(S) URL of the JWKS endpoint. Agentgateway fetches and caches keys from this URL.

jwks:
  url: https://auth.example.com/.well-known/jwks.json

jwks.file · string

Path to a local JWKS file on disk. The path is relative to the directory from which the Agentgateway binary runs (not relative to the config file).

jwks:
  file: ./keys/jwks.json

mode · string

Token enforcement mode. When set to strict, Agentgateway rejects requests that do not carry a valid Bearer token. When omitted or set to a permissive value, tokens are validated when present but not required.

mode: strict

provider · object

Optional provider hint for non-spec-compliant authorization servers. When set, Agentgateway activates a compatibility adapter that adjusts /.well-known/oauth-authorization-server responses. Exactly one of auth0 or keycloak must be specified.

Show provider options

provider.auth0 · object

Enables the Auth0 compatibility adapter. Set to an empty object {}.

provider:
  auth0: {}

provider.keycloak · object

Enables the Keycloak compatibility adapter. Set to an empty object {}.

provider:
  keycloak: {}

resourceMetadata · object

Configures the OAuth 2.0 Protected Resource Metadata document served at /.well-known/oauth-protected-resource/<path>. MCP clients use this to discover the correct authorization server.

Show resourceMetadata fields

resourceMetadata.resource · string · required

The canonical URI of the protected resource. Typically the full URL of the MCP endpoint.

resource: https://gateway.example.com/mcp

resourceMetadata.scopesSupported · string[]

OAuth 2.0 scopes supported by this resource.

scopesSupported:
- read:all
- offline_access

resourceMetadata.bearerMethodsSupported · string[]

Accepted methods for submitting Bearer tokens. Valid values: header, body, query.

bearerMethodsSupported:
- header
- body
- query

resourceMetadata.resourceDocumentation · string

URI pointing to human-readable documentation for the resource.

resourceMetadata.resourcePolicyUri · string

URI pointing to a policy document for the resource.

jwtValidationOptions · object

Fine-grained control over which RFC 7519 registered claims must be present in the token before validation proceeds.

Show jwtValidationOptions fields

jwtValidationOptions.requiredClaims · string[] · default: "[\"exp\"]"

Claims that must be present in the token payload. Only the following values are recognized: exp, nbf, aud, iss, sub. Other claims (including iat and jti) are silently ignored.

This setting controls presence only. Standard claims such as exp and nbf are still validated for value correctness (e.g., expiry is always enforced when exp is present) regardless of this list.

Use an empty list [] to require no specific claims:

jwtValidationOptions:
  requiredClaims: []

Default: ["exp"]

Examples

Standard OIDC provider

mcpAuthentication:
  mode: strict
  issuer: https://auth.example.com
  audiences:
  - https://gateway.example.com/stdio/mcp
  jwks:
    url: https://auth.example.com/.well-known/jwks.json
  resourceMetadata:
    resource: https://gateway.example.com/stdio/mcp
    scopesSupported:
    - read:all
    bearerMethodsSupported:
    - header
    - body
    - query

Keycloak provider

mcpAuthentication:
  issuer: http://localhost:7080/realms/mcp
  audiences:
  - mcp_proxy
  jwks:
    url: http://localhost:7080/realms/mcp/protocol/openid-connect/certs
  provider:
    keycloak: {}
  resourceMetadata:
    resource: http://localhost:3000/keycloak/mcp
    scopesSupported:
    - profile
    - offline_access
    - openid
    bearerMethodsSupported:
    - header
    - body
    - query

Auth0 provider

mcpAuthentication:
  issuer: https://dev-example.eu.auth0.com
  audiences:
  - urn:agent-gateway
  jwks:
    url: https://dev-example.eu.auth0.com/.well-known/jwks.json
  provider:
    auth0: {}
  resourceMetadata:
    resource: http://localhost:3000/auth0/mcp
    scopesSupported:
    - profile
    - openid
    bearerMethodsSupported:
    - header

Local JWKS file with strict validation

mcpAuthentication:
  mode: strict
  issuer: agentgateway.dev
  audiences:
  - test.agentgateway.dev
  jwks:
    file: ./manifests/jwt/pub-key
  jwtValidationOptions:
    requiredClaims:
    - exp
    - sub

When resourceMetadata is configured, Agentgateway automatically registers /.well-known/oauth-protected-resource/<path> and /.well-known/oauth-authorization-server/<path> endpoints. Include these paths in your route matches so the gateway serves them correctly.

The exp claim is always checked when it is present in a token, regardless of whether requiredClaims includes "exp". Including "exp" in requiredClaims only means the token will be rejected if the claim is absent, not that expiry checking is added.

---

jwtAuth

The jwtAuth policy provides generic JWT validation for any route — not limited to MCP. Unlike mcpAuthentication, it does not expose OAuth resource metadata endpoints. Use it for standard API authentication and as the authentication layer alongside mcpAuthorization.

Configuration location: binds[].listeners[].routes[].policies.jwtAuth

The policy supports two forms:

Single provider (shorthand)

policies:
  jwtAuth:
    issuer: agentgateway.dev
    audiences:
    - test.agentgateway.dev
    jwks:
      file: ./manifests/jwt/pub-key

Multiple providers

policies:
  jwtAuth:
    mode: strict
    providers:
    - issuer: https://auth1.example.com
      audiences:
      - https://api.example.com
      jwks:
        url: https://auth1.example.com/.well-known/jwks.json
    - issuer: https://auth2.example.com
      audiences:
      - https://api.example.com
      jwks:
        url: https://auth2.example.com/.well-known/jwks.json

Fields

mode · string

Enforcement mode. When set to strict, requests without a valid token are rejected.

issuer · string

Expected iss claim. Used in the single-provider shorthand form.

audiences · string[]

Accepted aud claim values. Used in the single-provider shorthand form.

jwks · object

JWKS source. One of file (path on disk, relative to binary working directory) or url (HTTP endpoint).

providers · object[]

List of JWT providers for multi-provider configurations. Each provider has issuer, audiences, jwks, and jwtValidationOptions fields identical to the single-provider shorthand.

jwtValidationOptions.requiredClaims · string[] · default: "[\"exp\"]"

Claims that must be present in the token. Recognized values: exp, nbf, aud, iss, sub. Defaults to ["exp"].

Once a JWT is validated, its claims are available as jwt.<claim> in CEL expressions used by mcpAuthorization and authorization policies.

---

apiKey

The apiKey policy authenticates requests using static API keys passed in the Authorization: Bearer header or x-api-key header.

Configuration location: binds[].listeners[].routes[].policies.apiKey

policies:
  apiKey:
    keys:
    - key: my-secret-api-key
      metadata:
        user: alice
    - key: another-secret-key
      metadata:
        user: bob
    mode: strict

Fields

apiKey.keys · object[] · required

List of valid API keys.

Show key fields

key · string · required

The API key value.

metadata · object

Arbitrary metadata associated with this key, available as apiKey.<field> in CEL expressions.

apiKey.mode · string

Enforcement mode. When set to strict, requests without a valid key are rejected.

API key metadata is available in CEL as apiKey.key and any custom metadata fields under apiKey.<field>.

---

basicAuth

The basicAuth policy authenticates requests using HTTP Basic Authentication validated against an htpasswd file.

Configuration location: binds[].listeners[].routes[].policies.basicAuth

policies:
  basicAuth:
    htpasswd:
      file: ./htpasswd
    realm: "My Gateway"
    mode: strict

Fields

basicAuth.htpasswd · object · required

Source of the htpasswd credentials.

Show htpasswd fields

htpasswd.file · string

Path to an htpasswd file on disk.

basicAuth.realm · string

Realm name sent in the WWW-Authenticate header when authentication fails.

basicAuth.mode · string

Enforcement mode. When set to strict, unauthenticated requests are rejected with 401.

Authenticated credentials are available in CEL as basicAuth.username.