Configure connector authentication

Connector authentication sets the credential the Connector Gateway sends to a connector's backend MCP server. Callers authenticate to the gateway with their own identity, and the gateway attaches the outbound credential that the connector's authentication type defines.

Choose an authentication type

Every connector has exactly one authentication type. The console's Authorization method offers every type in the table below.

Console label	API type	What the gateway sends	Needs
None	none	No credential	Nothing
Bearer token	bearerToken	A static token in the Authorization header	A secret
Header injection	headerInjection	A static value in a header you name	A secret
Token exchange (RFC 8693)	tokenExchange	A token obtained by exchanging the caller's token at call time	A token endpoint; a secret is optional
Upstream identity provider	upstreamInject	The calling user's own OAuth token, collected through a per-user consent flow	A connector identity provider
Microsoft Entra on-behalf-of (OBO)	obo	A Microsoft Entra ID token from the On-Behalf-Of (OBO) flow	An identity provider and a secret
AWS STS	awsSts	AWS SigV4-signed requests using temporary credentials from AWS STS web-identity federation	An identity provider; no secret
Cross-app access (XAA)	xaa	A token from the cross-app access (ID-JAG) flow	An identity provider; secrets are optional

Use these guidelines to pick a type:

• Use None for a backend that needs no credential, such as an internal MCP server that's reachable only inside your cluster.
• Use Bearer token or Header injection when the backend accepts one shared API key for every caller. Every user reaches the backend with the same identity.
• Use Upstream identity provider when the backend should act as each user, for example a SaaS MCP server that requires the user's own OAuth grant.
• Use Token exchange (RFC 8693), Microsoft Entra on-behalf-of (OBO), AWS STS, or Cross-app access (XAA) when the backend trusts your identity provider and accepts a token derived from the caller's identity.

Set up the prerequisites in order

Each authentication type references objects that must exist when you save the connector. The connector setup wizard creates some of them as you go: New secret next to a secret picker creates a managed secret, and the Set up an identity provider step creates a connector identity provider from the server's OAuth metadata. When you prepare them yourself, create them in this order:

1. Secrets. Create a managed secret for each static credential or client secret the type needs, or allowlist a Kubernetes Secret that holds it.
2. Identity provider. Register a connector identity provider for types that need one. The provider's client secret is itself a secret, which is why secrets come first.
3. Connector authentication. Configure the connector's authentication type, referencing the secrets and provider.
4. Access. Grant access to the connector through its connector policy.

Configure authentication in the console

Set a connector's authentication on the wizard's Authentication step when you add the connector. For an existing connector, open it and select Configure, then select Next to reach the Set up authorization step.

1. Choose an Authorization method and fill in its fields:

   • Bearer token: under Secret reference, choose the secret that holds the token.
   • Header injection: enter the Header name, for example X-API-Key, and choose the secret that holds its value.
   • Token exchange (RFC 8693): enter the Token URL and Client ID, and optionally an Audience, Scopes, and a Client secret reference.
   • Upstream identity provider: choose the connector identity provider that users authorize against.
   • Microsoft Entra on-behalf-of (OBO): choose the Upstream identity provider whose user tokens the gateway exchanges, enter the Tenant ID and Client ID, set an Audience, Scopes, or both, and choose the Client secret reference. Set Authority only for a non-public Microsoft Entra cloud, and Token cache skew to change how long before expiry the gateway stops reusing an exchanged token.
   • AWS STS: choose the identity provider whose tokens the gateway federates, enter the AWS Region and Service, and set a Fallback role ARN or role mappings that pick a Role ARN from a claim value.
   • Cross-app access (XAA): choose the identity provider, enter the IdP token URL and IdP client ID, the Target token URL, and the Target audience. Optionally set a Target resource, Scopes, a Target client ID, and a client secret reference for each side.

   For each secret, choose Managed secret or Kubernetes Secret as its source. A Kubernetes Secret must be in the enterprise-manager.directory.kubernetesSecretRefs.allowed list of your Helm values.

2. Finish the wizard, or select Save when you configure an existing connector. Saving runs the connector's setup check; see Check setup and publish a connector.

When you configure an existing connector, its stored secret is kept unless you choose a new one. To save a Token exchange (RFC 8693) connector without its client secret, select Remove client secret. For Cross-app access (XAA), select Remove IdP client secret or Remove target client secret.

How users authorize connectors

Users connect to connectors themselves, in the console's user experience:

1. Under Connectors, the user opens a connector listed under Available.
2. The user selects Connect. For a connector that acts as the user, a sign-in window opens and the user completes consent with the identity provider.
3. The connector moves to Enabled, and the gateway serves its tools to every MCP client the user signs in with.

MCP clients also prompt for authorization. When a client connects to the gateway, its sign-in includes a consent step for each enabled connector the user hasn't authorized yet.

Connectors that use Upstream identity provider, Token exchange (RFC 8693), Microsoft Entra on-behalf-of (OBO), awsSts, or xaa act as the user. The gateway forwards or exchanges the user's own token on each call, so the backend sees the individual user. Connectors that use None, Bearer token, or Header injection connect immediately, with no backend-specific sign-in.

The gateway's authorization server stores each user's session and upstream tokens. When the upstream tokens can no longer be used, the connector shows Reconnect required. See Support users' connector access for every connection state.

Each stored authorization is bound to the identity provider configuration that issued it. Changing any of these settings makes every user of that provider authorize again on their next connection:

• The provider's issuer, OAuth endpoints, or client ID
• The requested scopes or additional authorization parameters
• The redirect URI, which derives from global.stacklok.authServerIssuer

Affected users see Reconnect required. Rotating the provider's client secret leaves stored authorizations intact. The gateway keeps the stored authorizations, so if you revert the change, users' existing authorizations work again without another consent step.

Next steps

• Grant and revoke connector access to choose which groups can use the connector.
• Review tool usage to confirm that users are calling the connector's tools.

Related information

• Identity providers - register the providers that per-user and federation types reference
• Managed secrets - store the credentials that static types reference

Troubleshooting

The provider shows a redirect URI error during Connect

The provider rejected the gateway's callback URL, often with an error such as redirect_uri_mismatch. The gateway always uses {issuer}/oauth/callback, where {issuer} is global.stacklok.authServerIssuer. The console shows the exact value as Redirect URI on the identity provider's details and on the Identity providers screen.

Register that exact URL in the allowed redirect URIs of the provider's OAuth app. Providers that use dynamic client registration receive it automatically.