Skip to navigation
FabricPlugins

Authenticate requests with JWT Auth

Key Auth and JWT Auth are the two main ways to authenticate callers on a route. Key Auth checks a gateway key. JWT Auth checks a JSON Web Token (JWT) that your identity provider (IdP), such as Okta, issued. The gateway validates the token, reads its claims, and passes them on, so that other plugins can enforce policy on them. This topic explains how JWT Auth works and how to combine it with the Agent Scope Gate plugin to limit which MCP tools a user can see.

JWT Auth isn’t available when Postman hosts your data plane. It validates tokens against an identity provider that you register with the gateway, and the console shows a warning on the plugin form when you use a Postman-hosted data plane. For more information, see Deployment options.

Understand JWT Auth

The plugin validates each token against the signing keys that your identity provider publishes. If the token is valid, the gateway treats the request as authenticated and maps claims from the token to the caller’s identity. Other plugins on the route can then use those claims.

Choose JWT Auth over Key Auth when your users or agents already sign in through an identity provider and you want the gateway to use that identity instead of a separate gateway key.

Configure JWT Auth

To add JWT Auth to a route, do the following:

  1. Select Plugins, find JWT Auth in the Auth category, and then select Use.

  2. Enter a Name, set Scope kind to route, and set Scope name to the route that you want to protect.

  3. In Identity provider, select the identity provider that you registered with the gateway.

  4. Optionally, open Advanced and adjust the following settings:

    SettingWhat it does
    Token sourcesWhere the gateway reads the token, in order. The first match wins. Leave it empty to read a bearer token from the Authorization header.
    Claim fieldsThe names of the claims that the gateway reads for the subject, principal, kind, scopes, tenant, user, session, installation, and consumer type. Each has a default, for example sub for the subject and scopes for the scopes.

  5. Select Save.

If you read the token from a cookie, browsers send it automatically, so the request is exposed to cross-site request forgery. Set the cookie HttpOnly and Secure with SameSite=Lax or Strict, and require a CSRF token on requests that change state. The gateway validates the token but doesn’t add CSRF protection.

Limit MCP tools with claims

The Agent Scope Gate plugin checks the scopes on the authenticated caller before it lets a request through. When the caller’s scopes come from JWT claims, you can control what each person or agent can do.

For example, suppose one user’s token has a scope that allows only read tools, and another user’s token also allows delete operations. With Agent Scope Gate on an MCP route, the first user sees only the read tools. The second user sees the delete tools as well.

To configure the Agent Scope Gate, do the following:

  1. Select Plugins, find Agent Scope Gate, and then select Use.
  2. Enter a Name, and set the scope to the MCP route.
  3. In Required scopes, enter the scopes that the caller must have, as a comma-separated list, for example workspace:read, agent:run.
  4. In Scope match, choose whether the caller needs all of the scopes or any of them.
  5. Select Save.

You can also require a consumer group, allow only certain principal types such as bot or human, and set different scope requirements for individual tools. A request without the required scopes is rejected.

Next steps