Authentication

MCP authentication in Archestra has two separate layers: the client-facing gateway layer and the upstream MCP server layer.

This separation is important because the MCP client usually should not know how every upstream system is authenticated. Cursor, Claude Desktop, Copilot CLI, Open WebUI, or a custom agent authenticates once to an MCP Gateway. Archestra then decides which installed MCP server connection and which upstream credential should be used for each tool call.

That means one gateway can expose tools backed by different credential models. A GitHub tool might use a user's OAuth token, a Jira tool might use an enterprise IdP token exchange, and an internal self-hosted tool might require no external credential at all. The client still talks to the same gateway.

The two layers are:

• Gateway authentication: how a client proves it can call POST /v1/mcp/<gateway-id>
• Upstream MCP server authentication: how Archestra authenticates to the MCP server or external system behind that gateway when a tool actually runs

Clients only send the gateway-facing token. Archestra resolves upstream MCP server authentication separately at execution time, using the caller identity, the gateway or Agent tool assignment, and the installed MCP server credential configuration.

Use this page to choose the gateway authentication method for your client, then choose how upstream credentials should be stored, resolved, exchanged, or forwarded when tools execute.

Gateway Authentication

The MCP Gateway supports six client authentication methods. Choose based on who is calling and whether the request should carry a specific user's identity — that identity is what enables per-user Resolve at call time.

These do not all present the same token to POST /v1/mcp/<gateway-id>:

• OAuth 2.1, OAuth client credentials, OAuth authorization code (manually registered), and ID-JAG all end with an Archestra-issued OAuth access token being sent to the gateway
• JWKS sends an external IdP JWT directly to the gateway
• Bearer token sends a static platform-managed token directly to the gateway.

OAuth 2.1

MCP-native clients such as Claude Desktop, Cursor, Copilot CLI, and Open WebUI authenticate automatically using the MCP Authorization spec. The gateway acts as both the resource server and the authorization server.

The gateway supports the following OAuth flows and client registration methods:

• Authorization Code + PKCE: The standard browser-based authorization flow. The user is redirected to a login and consent screen, and the client receives tokens upon approval.
• DCR (RFC 7591): Clients can register dynamically at runtime by posting their metadata to POST /api/auth/oauth2/register. The gateway returns a client_id for subsequent authorization requests.
• CIMD: Clients can use an HTTPS URL as their client_id. The gateway fetches the client's metadata document from that URL, eliminating the need for a separate registration step.

Endpoint discovery is automatic. The gateway exposes standard well-known endpoints so clients can find the authorization and token URLs without any hardcoded configuration:

• /.well-known/oauth-protected-resource (RFC 9728)
• /.well-known/oauth-authorization-server (RFC 8414)

Token lifetime

Archestra returns the lifetime of user OAuth access tokens through the standard expires_in field. The default lifetime is 1 year, which reduces unnecessary reconnects for MCP-native clients like desktop apps.

Admins can change this in Settings > Organization > Auth. The setting is organization-wide and applies to newly issued user OAuth access tokens, including MCP OAuth 2.1 and custom application authorization-code flows.

OAuth Client Credentials (Applications)

When the caller is an application — a backend service, automation job, or another team's bot — rather than a human, register an MCP OAuth client and use the OAuth 2.0 client_credentials grant. This is the machine-to-machine equivalent of the user OAuth flow: the credential belongs to an application, not a person.

Create and manage these clients under MCPs > Credentials > OAuth Clients. Each client is scoped to an explicit list of gateways and returns a client_id and a one-time client_secret (which you can rotate later). A client can only mint tokens for the gateways on its list, so one team can hand a client to another team for access to a curated set of gateways and nothing else.

Like agents and gateways, each OAuth client has a visibility level — Personal (only its creator), Teams (members of selected teams), or Organization — controlling who can see, edit, rotate, and delete it. New clients default to Personal; sharing with teams requires mcpOauthClient:team-admin, organization-wide visibility requires mcpOauthClient:admin, and admins see every client regardless. Visibility only governs management access — it does not change which gateways the client's tokens can reach at runtime.

The client exchanges its credentials for a short-lived (1-hour) bearer token at POST /api/auth/oauth2/token with:

• grant_type=client_credentials
• client_id and client_secret
• scope=mcp

It then sends that token to the gateway like any other OAuth access token (Authorization: Bearer <token>). The token is rejected by any gateway not on the client's list, and by gateways in another organization.

Because there is no acting user, per-user dynamic credential resolution does not apply to these tokens — assign tools to a shared connection rather than Resolve at call time. To let a pre-registered application act with the user's identity instead, use the authorization code grant below.

OAuth Authorization Code (On behalf of users)

When a pre-registered application needs to act with the user's Archestra identity — for example an agentic chat backend calling gateways for whoever is signed in — register an MCP OAuth client with the authorization_code grant. Its tokens are user-bound, so unlike client credentials, gateway tools resolve each caller's own permissions and connections, and Resolve at call time works.

Create it under MCPs > Credentials > OAuth Clients, choose the "On behalf of users" grant type, and add one or more redirect URIs. The client is confidential and returns a client_id and one-time client_secret; PKCE is required.

The application runs the standard browser flow:

• GET /api/auth/oauth2/authorize with response_type=code, scope=mcp (add offline_access for a refresh token), the registered redirect_uri, and a PKCE challenge.
• POST /api/auth/oauth2/token with grant_type=authorization_code, client_id, client_secret, and the PKCE verifier.

The result is a normal user OAuth access token, sent to the gateway as Authorization: Bearer <token>. Only the registered application can complete the flow. By default the signed-in user reaches only the gateways their own permissions already allow.

Gateway access grant

Optionally, assign one or more gateways to the client as an access grant. Any user who authenticates through the client may then reach those gateways in addition to their own role-based access — even gateways they otherwise couldn't reach. The grant is additive (it never removes access) and admin-controlled (only admins register clients and set the list).

This lets you gate a gateway behind a specific trusted app: restrict the gateway so it isn't reachable on its own (assign it to a team with no members — an org-wide gateway is open to all members), then grant it through the client. The gateway is then reachable only by users who come through that app. Leave the grant empty for pure identity passthrough, where access stays governed entirely by each user's permissions.

To restrict OAuth flows to pre-registered clients only, set ARCHESTRA_AUTH_DCR_ENABLED=false. This disables Dynamic Client Registration and CIMD auto-registration (above), so the gateway accepts OAuth flows only from clients you registered explicitly — both client_credentials and authorization_code.

Bearer Token

For direct API integrations, clients can authenticate using a static Bearer token with the header Authorization: Bearer arch_<token>. Tokens can be scoped to a specific user, team, or organization. You can create and manage tokens in Settings > Tokens.

Bearer tokens authenticate the client to Archestra. They are not enterprise assertions by themselves. If Archestra also needs to exchange the matched user's IdP token and use the result on the downstream MCP request, it must still have a usable IdP token for that user.

For per-user access to downstream systems like GitHub or Jira, bearer tokens should usually be personal user tokens. Team and organization tokens can authenticate to the gateway, but they do not identify a specific user strongly enough for Archestra to broker per-user downstream credentials on their own.

Identity Assertion JWT Authorization Grant (ID-JAG)

This option implements the MCP Enterprise-Managed Authorization extension using an Identity Assertion JWT Authorization Grant (ID-JAG). It is designed for organizations that already use a corporate IdP to sign users into MCP clients. The identity provider must be able to:

• authenticate the user to the MCP client
• perform RFC 8693 token exchange to issue an ID-JAG
• sign that ID-JAG as a JWT that Archestra can validate through OIDC discovery or a JWKS endpoint

In this flow, the MCP client does not send the user's enterprise JWT directly to the gateway. Instead:

1. The user signs in to the MCP client with the enterprise IdP
2. The MCP client exchanges that identity assertion with the IdP for an ID-JAG
3. The MCP client sends the ID-JAG to Archestra's token endpoint using the JWT bearer grant
4. Archestra validates the ID-JAG against the configured IdP and returns an MCP access token
5. The MCP client calls the gateway with that MCP access token

Archestra supports the second leg of the flow generically at POST /api/auth/oauth2/token with:

• grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
• assertion=<id-jag>
• normal OAuth client authentication for the MCP client (client_secret_basic, client_secret_post, or none for public clients)

Requirements

• The MCP Gateway must be linked to an OIDC Identity Provider in Archestra
• The IdP-issued ID-JAG must be a JWT with header typ=oauth-id-jag+jwt
• The ID-JAG aud claim must match Archestra's OAuth issuer
• The ID-JAG resource claim must point to the target MCP Gateway URL (/v1/mcp/<gateway-id>)
• The ID-JAG client_id claim must match the authenticated MCP client
• The ID-JAG scope must include mcp
• The ID-JAG should include an email claim that matches an existing Archestra user account

Archestra binds the access token it issues to the specific MCP Gateway in the resource claim, so that token cannot be replayed against a different gateway.

See How Enterprise-Managed Authorization Will Secure Remote MCP Servers in the Enterprise for a longer walkthrough of the pattern.

Identity Provider JWKS

Identity Providers (IdPs) configured in Archestra can also be used to authenticate external MCP clients. When an IdP is linked to an Archestra MCP Gateway, the gateway validates incoming JWT bearer tokens against the IdP's JWKS (JSON Web Key Set) endpoint and matches the caller to an Archestra user account. The same team-based access control that applies to Bearer tokens and OAuth also applies here — the JWT's email claim must correspond to an Archestra user who has permission to access the gateway.

After authentication, the gateway resolves credentials for the upstream MCP server. If the upstream server has its own credentials configured (e.g., a GitHub PAT or OAuth token), those are used. If no upstream credentials are configured, the gateway propagates the original JWT as an Authorization: Bearer header, enabling end-to-end identity propagation where the upstream server validates the same JWT against the IdP's JWKS. See End-to-End JWKS below for how to build servers that consume propagated JWTs.

This credential resolution supports a common setup: an admin installs upstream MCP servers (GitHub, Jira, etc.) with service credentials once, and any user who authenticates via their org's IdP can access those tools — the gateway resolves the appropriate upstream token automatically. Both static and per-user credentials work with JWKS authentication.

How It Works

1. Admin configures an OIDC Identity Provider in Settings > Identity Providers
2. Admin creates an MCP Gateway and selects the Identity Provider to use for JWKS Auth
3. External MCP client obtains a JWT from the IdP (e.g., via client credentials flow or user login)
4. Client sends requests to the gateway with Authorization: Bearer <jwt>
5. Gateway discovers the JWKS URL from the IdP's OIDC discovery endpoint
6. Gateway validates the JWT signature, issuer, audience (IdP's client ID), and expiration
7. Gateway extracts the email claim from the JWT and matches it to an Archestra user account
8. Gateway resolves upstream credentials: if the server has its own credentials, those are used; otherwise the original JWT is propagated

Requirements

• The Identity Provider must be an OIDC provider (SAML providers do not support JWKS)
• The IdP must expose a standard OIDC discovery endpoint (.well-known/openid-configuration) with a jwks_uri
• The JWT iss claim must match the IdP's issuer URL
• The JWT aud claim must match the IdP's client ID (if configured)
• The JWT must contain an email claim that matches an existing Archestra user
• The user must have profile:admin permission or be a member of at least one team associated with the gateway they are trying to use

Upstream MCP Server Authentication

MCP servers that connect to external services like GitHub, Atlassian, or ServiceNow need their own credentials. Archestra manages this with a two-token model:

• Gateway Token authenticates the client to the gateway using an Archestra OAuth access token, an ID-JAG-derived Archestra access token, an external IdP JWT via JWKS, or a static bearer token.
• Upstream MCP Server Token authenticates the gateway to the upstream MCP server. This token is resolved and injected by Archestra at runtime.

The client only ever sends the Gateway Token. Archestra resolves the Upstream MCP Server Token behind the scenes.

See MCP Gateway - Authentication for the high-level gateway token and upstream token diagram.

Credentials are configured when you install a server from the MCP Catalog. There are five types of upstream credentials:

• Static secrets: API keys or personal access tokens that are set once at install time and used for all requests.
• OAuth tokens: Obtained by running an OAuth flow against the upstream provider during installation. Archestra stores both the access token and refresh token.
• OAuth client credentials: Shared client credentials stored on the MCP connection and exchanged for a short-lived bearer token when a tool call runs.
• Identity Provider Token Exchange: Retrieved at tool-call time by exchanging the caller's IdP token for the downstream credential the MCP server needs.
• Identity Provider JWT / JWKS: Retrieved at tool-call time by forwarding the caller's IdP JWT to the upstream MCP server for direct JWKS-based validation.

Identity Provider Token Exchange can use a linked downstream IdP that is different from the gateway's primary login IdP, as long as the Archestra user has a usable token for that downstream IdP. See Enterprise-Managed Auth — Linked downstream IdPs.

How credentials are delivered to the upstream server depends on the server type. For passthrough (remote) servers, Archestra sends the credential over HTTP. The primary auth header defaults to Authorization, but you can configure a different header name such as x-api-key when the upstream server expects the token outside the standard authorization header. Additional headers are available for tenant IDs and other non-auth upstream requirements, and non-sensitive static values are stored directly in the catalog item. For hosted (local) servers running in Kubernetes, the gateway connects via stdio transport within the cluster and no auth headers are needed.

Auth credentials are stored in the secrets backend, which uses the database by default. For enterprise deployments, you can configure an external secrets manager.

Credential Resolution

Credential resolution decides which installed MCP server credential should be used for a tool call. A tool assignment can either pin a specific installed connection or ask Archestra to resolve a credential at execution time from the caller identity, following the server's Default credential setting. Resolve at call time is the default for new assignments; pinning a connection is an explicit choice.

Static Credentials

Static credentials are shared credentials configured on an installed MCP server connection. They can be API keys, PATs, service account tokens, OAuth tokens, OAuth client credentials, or other values required by the upstream server.

When you pin a tool to a specific installed MCP server connection instead of using dynamic resolution, Archestra validates the connection against the target Agent or MCP Gateway scope:

• Team-installed connection: can only be assigned to a team-scoped Agent or MCP Gateway that includes that same team
• Personal connection: can only be assigned to a resource the connection owner could access directly
• Resolve at call time: skips static-owner checks because Archestra resolves credentials per caller at execution time

This means a team-shared connection is governed by the team it is shared with, not by the individual who originally installed it. Personal connections still follow the connection owner's access boundary.

Resolve at Call Time

When a tool assignment uses "Resolve at call time" (or an agent is in Auto tool mode), Archestra picks the credential at execution time. Which one is used is defined on the MCP server itself — the Default credential setting on the server's Credentials tab:

• On behalf of the user (default): the chatting identity's own connection takes priority, falling back to a connection it can access. A user token resolves to that user's personal connection, then a connection for a team they belong to, then an org-scoped connection; a team token resolves to that team's connection, then an org-scoped one. A caller with no reachable connection gets an actionable connect prompt.
• Always use one account: every runtime-resolved call goes through the chosen connection, regardless of the caller — a service account. Use this when the whole org or a team should share one upstream account. If that connection is revoked, the server returns to on-behalf-of-the-user resolution.

Missing Credentials

When no credential can be resolved for a caller, the gateway returns an actionable error message that includes a direct link to install the MCP server with their own credentials:

Authentication required for "GitHub MCP Server".
No credentials found for your account (user: alice@example.com).
Set up credentials: https://archestra.example.com/mcp/registry?install=abc-123

The user follows the link, installs the server with their credentials, and retries the tool call.

OAuth 2.1

Use OAuth 2.1 when an upstream MCP server connects to a SaaS API where each user has their own account, such as GitHub or Salesforce.

Your server or its OAuth provider needs to expose two things:

• A /.well-known/oauth-protected-resource endpoint that points to the authorization server
• A 401 response with a WWW-Authenticate header when tokens are missing or expired

Archestra handles endpoint discovery, client registration, Authorization Code + PKCE, token storage, and token injection. Your server receives an Authorization: Bearer <access_token> header with each request from the gateway.

If the MCP server URL is different from the OAuth issuer or metadata host, configure explicit OAuth overrides in the MCP catalog item. Archestra can use a separate authorization server URL, a direct well-known metadata URL, a direct resource metadata URL, or direct authorization and token endpoints instead of deriving everything from the MCP server URL.

Set Protected Resource only when the OAuth provider requires a resource identifier, such as an Entra or OAuth API identifier like api://<client-id> or https://api.example.com. Archestra sends this as the OAuth resource parameter during authorization, token exchange, and refresh. Leave it blank for providers that do not accept resource indicators.

Direct authorization and token endpoints are useful for legacy or self-hosted OAuth providers that expose fixed OAuth URLs but do not publish /.well-known metadata.

OAuth Client Credentials

Use OAuth client credentials when a remote MCP server expects Archestra to obtain a short-lived bearer token from an OAuth 2.0 token endpoint using grant_type=client_credentials.

Archestra stores the shared client_id, client_secret, and optional audience on the installed MCP connection. At runtime it exchanges those values for an access token, injects that token as Authorization: Bearer <token>, and reuses it until the configured refresh window is reached.

This is a shared connection pattern, not a per-user identity pattern:

• install one connection per team or shared scope
• assign tools to that installed connection directly
• do not use Resolve at call time unless you want Archestra to choose among multiple installed shared credentials

Auto-Refresh

For upstream servers that use OAuth, Archestra handles the token lifecycle automatically. When the upstream server returns a 401, Archestra uses the stored refresh token to obtain a new access token and retries the request without any user intervention. Refresh failures are tracked per server and are visible in the MCP server status page.

Troubleshooting refresh failures

no_refresh_token means the provider issued no refresh token, so the connection breaks once its access token expires. The server's Additional scopes field (pre-filled with offline_access) is appended to every authorization request to ask for one — keep it for Microsoft Entra and other standard OIDC providers, and clear it for providers that reject the scope (e.g. Google, which uses access_type=offline). Reconnect after changing it; if it persists, confirm the provider grants offline access to the app, which some tenants gate behind admin consent.

Enterprise Identity Credential Resolution

Archestra can also resolve a token at tool-call time by asking the configured identity provider or broker for one. Instead of storing the downstream token in Archestra ahead of time, Archestra exchanges the signed-in user's IdP token and injects the returned token into the MCP request.

These modes are configured across three places:

• Identity Provider: how Archestra authenticates to the IdP for credential exchange
• MCP catalog item: whether Archestra should exchange a downstream credential or pass through the caller's IdP JWT, plus how the resulting credential should be injected
• Tool assignment: choose Resolve at call time

This model works best for remote MCP servers and local MCP servers using HTTP transport. Local stdio servers do not support per-request token exchange and injection.

For MCP Gateways, this token exchange uses the caller identity that was established at the gateway:

• JWKS: Archestra can use the incoming external IdP JWT directly
• ID-JAG: Archestra uses the enterprise assertion path associated with the gateway's Identity Provider
• OAuth 2.1: Archestra resolves the authenticated Archestra user and then uses that user's linked IdP session, if one exists
• Bearer token: Archestra can only exchange a downstream token if the bearer token maps to a specific user with a linked IdP session

For external MCP clients such as Cursor, ID-JAG and JWKS are usually the clearest options when you want per-user access to upstream systems like GitHub or Jira.

Identity Provider Token Exchange

When Archestra is configured to exchange the caller's IdP token at tool-call time, it uses one of three exchange strategies.

• RFC 8693 token exchange: Archestra exchanges the user's token at the IdP token endpoint and uses the returned bearer token on the downstream MCP request.
• Okta managed credential exchange: Archestra exchanges the user's token for an Okta-managed credential such as a secret or bearer token, then injects the configured value into the downstream MCP request.
• Microsoft Entra on-behalf-of (OBO): Archestra exchanges the signed-in user's Entra access token for the downstream API token the MCP server needs.

Archestra uses the exchange mode configured on the Identity Provider to decide how to exchange the user's IdP token before calling the downstream MCP server.

How To Enable This

Configure all three of the following:

• Identity Provider: In Settings > Identity Providers, open the OIDC provider and fill in the optional Enterprise-Managed Credentials section so Archestra knows how to call the IdP or broker token endpoint.
• MCP catalog item: In the server's multitenant authorization settings, choose either Identity Provider Token Exchange to exchange the caller's IdP token for a downstream token, or Identity Provider JWT / JWKS to forward the caller's IdP JWT directly.
• Tool assignment: Assign the tool with Resolve at call time so Archestra resolves credentials per caller when the tool runs.

See Enterprise-Managed Auth for related setup details.

This works with any gateway auth method that lets Archestra resolve a specific user and a usable IdP token for that user. In practice, JWKS and ID-JAG are the clearest options, OAuth 2.1 also works when the authenticated Archestra user has a linked session with the same IdP, and personal user bearer tokens can work when they map to a specific user with a linked IdP session. Team and organization bearer tokens do not carry enough user identity for per-user downstream token exchange.

Token Exchange Configuration

When you choose Identity Provider Token Exchange on the MCP catalog item, the following fields control what Archestra asks the IdP or broker for and how the returned value is used:

• Requested Credential: The type of value Archestra should request from the IdP or broker. Common options are a bearer token, secret, ID-JAG, service account, or opaque JSON payload.
• Injection Mode: How Archestra should send the returned value to the upstream MCP server. The common modes are Authorization: Bearer, raw Authorization, or a custom header.
• Managed Resource Identifier: The audience, resource ID, or similar target identifier that tells the IdP or broker which downstream system token to mint.
• External Provider Alias: Optional broker-specific selector used when one identity provider can mint tokens for multiple downstream providers. For example, a Keycloak broker might use an alias such as github.
• Response Field Path: Optional field name to extract when the IdP or broker returns a structured payload instead of a raw token or secret.
• Header Name: Only used when the injection mode is a custom header. This sets the exact upstream header name, such as X-Provider-Token.

When To Use It

With Identity Provider Token Exchange, Archestra resolves the caller's enterprise assertion and exchanges it for the downstream credential the MCP server needs.

Use this mode when the upstream system or credential broker expects Archestra to exchange the caller's enterprise identity for a different downstream token.

This is different from using ID-JAG to authenticate to the MCP Gateway:

• ID-JAG at the MCP Gateway exchanges an enterprise assertion for an Archestra-issued MCP access token
• Identity Provider Token Exchange obtains the credential used for the downstream MCP tool call itself

Identity Provider JWT / JWKS

With Identity Provider JWT / JWKS, Archestra resolves the caller's enterprise assertion and forwards that JWT to the upstream MCP server as Authorization: Bearer <jwt>, so the upstream server can validate it against the IdP's JWKS directly.

Use this mode when the upstream MCP server already understands the enterprise IdP's JWTs and should make its own authorization decisions from those claims.

This is different from using JWKS to authenticate to the MCP Gateway:

• JWKS at the MCP Gateway authenticates the caller to Archestra
• Identity Provider JWT / JWKS provides the credential used for the downstream MCP tool call itself

End-to-End JWKS

When an MCP Gateway is configured with Identity Provider JWKS, the gateway propagates the caller's JWT to upstream MCP servers. Your MCP server receives the JWT as an Authorization: Bearer header and can validate it directly against the IdP's JWKS endpoint — statelessly, without any Archestra-specific integration.

This pattern is useful when your MCP server needs to enforce its own access control based on IdP claims (roles, groups, etc.), or when the server is also deployed outside of Archestra and needs to authenticate users independently.

See Building Enterprise-Ready MCP Servers with JWKS and Identity Providers for a full walkthrough with code examples.

ID-JAG vs JWKS

ID-JAG and JWKS both rely on enterprise-issued JWTs, but they solve different problems.

In the product UI, these choices appear in two different places:

• MCP Gateway dialog: choose the Identity Provider the gateway trusts for enterprise client authentication
• MCP catalog item > Multitenant Authorization: choose whether the upstream MCP server should receive an exchanged credential (Identity Provider Token Exchange) or the caller's original IdP JWT (Identity Provider JWT / JWKS)

ID-JAG is a token exchange pattern. The MCP client first obtains an enterprise-issued identity assertion, exchanges it for an ID-JAG, and then exchanges that ID-JAG with Archestra for an MCP access token. Archestra validates the ID-JAG and issues a new gateway token scoped to the target MCP Gateway.

JWKS authentication is direct JWT validation. The MCP client sends the enterprise JWT directly to Archestra, and Archestra validates that JWT against the IdP's JWKS endpoint on each request.

Use ID-JAG when:

• your MCP client uses the ID-JAG token exchange flow
• you want Archestra to mint its own MCP access token for the gateway
• you want the resulting gateway token bound to a specific MCP resource

Use JWKS when:

• your MCP client already has a usable bearer JWT from the enterprise IdP
• you want direct JWT validation without a token exchange step
• you want the original enterprise JWT propagated to upstream MCP servers

In short: ID-JAG exchanges an enterprise assertion for an Archestra-issued MCP token, while JWKS validates and forwards the enterprise JWT directly.