> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
Secure AI agent access to your APIs and MCP tools with identity, authentication, and authorization on every call. The Maverics Orchestrator lets you control which agents can access which tools, trace every action back to the human user who authorized it, and audit everything -- so AI agents operate with the same identity governance as your human users.
The Orchestrator provides two approaches for securing AI agent access through the **Model Context Protocol (MCP)**, an open standard that lets AI agents discover and invoke tools in a structured, protocol-driven way. Each approach adds identity, authentication, and authorization to MCP connections in a different way, depending on your architecture and what you already have in place.
Whether you have existing REST APIs you want to open up to AI agents or existing MCP servers that need identity awareness -- there is an approach that fits your situation.
## Choose Your Approach
| Approach | When to Use | How It Works |
| - | - | - |
| **Expose APIs to Agents** | You have existing REST APIs you want AI agents to access | Translates REST APIs into MCP tools automatically -- agents discover and invoke tools via MCP while the Orchestrator handles the REST translation behind the scenes |
| **Protect MCP Servers** | You have existing MCP servers that need identity | Proxies MCP connections with identity injection -- the Orchestrator sits between agents and your MCP servers, adding authentication and authorization to every tool invocation |
> [!TIP]
>
> Not sure which approach to start with? If you have REST APIs today and want to
> expose them to AI agents, start with **MCP Bridge**. If you already have MCP
> servers running, start with **MCP Proxy**.
## Agent Identity Concepts
AI agents are not humans -- but they still need identity. When an AI agent accesses a tool, reads data, or performs an action on behalf of a user, something needs to answer these questions: Who is this agent? Who authorized it to act? What is it allowed to do? And what did it actually do?
Agent identity addresses this by adding three capabilities that traditional service accounts lack:
* **Delegation chains** -- Every agent action traces back to the human user who authorized it. When Agent X accesses a tool, the system knows that Alice delegated authority to Agent X and that Alice's permissions (not just the agent's) determine what the agent can do. This is implemented through OAuth 2.0 token exchange, which supports two modes. **Delegation** (default) produces a token with an `act` claim that identifies both the user and the agent acting on their behalf, giving downstream services full visibility for auditability. **Impersonation** produces a token that fully assumes the user's identity, with no trace of agent involvement -- use this when downstream services do not support the actor claim pattern. See the [MCP Bridge](/reference/orchestrator/applications/mcp-bridge#token-exchange) and [MCP Proxy](/reference/orchestrator/applications/mcp-proxy#token-exchange) references for configuration details.
* **Dynamic scopes** -- Agent permissions can change based on context. An agent might have broad scopes for one task and narrow scopes for another, depending on what the delegating user authorized. Scopes are named permissions (like `read:orders`, `write:invoices`, or `admin:users`) that your identity provider issues in the agent's token.
* **Action-level audit** -- Every tool invocation is logged with the full identity context: which agent, which user, which tool, what parameters, and what result. This gives you a complete audit trail that satisfies compliance requirements and enables forensic analysis when something goes wrong.
The Maverics Orchestrator works with your existing identity provider to manage agent identity. You register agents in your identity provider (just like you register applications), configure their scopes and permissions, and the Orchestrator enforces those permissions at runtime -- whether you are using [MCP Bridge](/guides/ai-identity/mcp-bridge) or [MCP Proxy](/guides/ai-identity/mcp-proxy) mode.
## How Token Security Works
The AI Identity Gateway involves two orchestrator deployments working together:
* **Auth Provider Orchestrator** -- A separate orchestrator deployment running as an OIDC Provider (authorization server). It handles agent authentication, token issuance, and token exchange (minting short-lived, scoped delegation tokens for each tool invocation).
* **AI Identity Gateway Orchestrator** -- Runs the MCP Provider with MCP Bridge and/or MCP Proxy apps. It handles MCP transport, tool routing, inbound authorization (OPA policies), and upstream forwarding.
These can be the same orchestrator instance for simpler deployments, but are typically separate deployments in production.
Every tool invocation gets its own token. When an agent calls a tool, the AI Identity Gateway Orchestrator does not reuse the agent's existing token or forward it to the upstream service. Instead, it requests a token exchange from the Auth Provider Orchestrator -- trading the agent's token for a brand-new token specific to that single tool call. Each token carries only the scopes that tool needs (like `employee:List` for listing employees) and expires in seconds (typically a `ttl` of `5s`). A different tool call a moment later gets a completely different token with different scopes.
```mermaid theme={null}
sequenceDiagram
participant Agent as AI Agent
participant Gateway as AI Identity Gateway
(Orchestrator)
participant AuthServer as Auth Provider
(Orchestrator / OIDC Provider)
participant API as Tool / API
Agent->>Gateway: Connect to MCP endpoint
Gateway-->>Agent: 401 + /.well-known/oauth-protected-resource
Agent->>Gateway: GET /.well-known/oauth-protected-resource
Gateway-->>Agent: Protected resource metadata (lists authorization servers)
Agent->>AuthServer: OAuth authorization flow
AuthServer-->>Agent: Access token
Agent->>Gateway: Invoke tool (with access token)
Gateway->>Gateway: Validate token + evaluate OPA policies
Gateway->>AuthServer: Token exchange: mint scoped token
ttl: 5s, scopes: [employee:List]
AuthServer-->>Gateway: Short-lived delegation token
Gateway->>API: Forward request with delegation token
API-->>Gateway: Response
Gateway-->>Agent: Tool result
```
## MCP Spec OAuth Discovery (RFC 9470)
When an agent first connects to the AI Identity Gateway, it goes through a standards-based OAuth discovery flow:
1. The agent connects to the AI Identity Gateway Orchestrator's MCP endpoint.
2. The gateway returns a `401` along with a pointer to its protected resource metadata endpoint.
3. The gateway exposes `/.well-known/oauth-protected-resource` (per RFC 9470), which returns protected resource metadata including the list of authorization server(s) the agent can authenticate against.
4. The agent reads the metadata, authenticates against the Auth Provider Orchestrator (one of the listed authorization servers), and obtains a token.
5. The agent returns to the gateway with a valid token. The gateway validates the token and proceeds with tool discovery and invocation.
This flow means agents do not need to be pre-configured with authorization server URLs -- they discover them dynamically from the gateway's protected resource metadata.
Traditional approaches give agents broad, long-lived tokens that accumulate permissions. The Orchestrator takes the opposite approach: every tool invocation gets a fresh, minimal-privilege token that expires in seconds. No single token ever carries more permissions than a single tool needs, and no token lives longer than it takes to complete the call.
## Set Up the Auth Provider
**1. Set up the OIDC Provider for agent tokens**
The OIDC Provider you configure here is the Orchestrator's own token minting infrastructure. It does not just validate tokens from an external provider -- it issues short-lived, narrowly scoped tokens for each tool invocation. You configure it with token exchange grant types so it can mint delegation tokens that carry both the agent's identity and the delegating user's identity.
**Console UI**
> [!NOTE]
>
> **Console UI documentation is coming soon.** This section will walk you
> through configuring this component using the Maverics Console's visual
> interface, including step-by-step screenshots and field descriptions.
**Configuration**
This configuration is for the **Auth Provider Orchestrator** deployment -- the separate orchestrator instance that runs the OIDC Provider. It is not the same deployment as the AI Identity Gateway Orchestrator that runs the MCP Provider.
Configure the `oidcProvider` and register the AI Identity Gateway as an OIDC application with token exchange grants and custom scopes for MCP tools.
```yaml maverics.yaml theme={null}
connectors:
- name: upstream-idp
type: oidc
oidcWellKnownURL: https://your-idp.example.com/.well-known/openid-configuration
oauthClientID: orchestrator-client
oauthClientSecret:
oauthLoginRedirect:
urls:
- https://your-auth-server.example.com/oidc-callback
oauthLogoutRedirect:
urls:
- https://your-auth-server.example.com/logout
disablePKCE: false
scopes: openid profile email
oidcProvider:
correlateSession: true
discovery:
issuer: https://your-auth-server.example.com
endpoints:
wellKnown: https://your-auth-server.example.com/.well-known/oauth-authorization-server
jwks: https://your-auth-server.example.com/oauth2/jwks
auth: https://your-auth-server.example.com/oauth2/auth
token: https://your-auth-server.example.com/oauth2/token
userinfo: https://your-auth-server.example.com/oauth2/userinfo
introspect: https://your-auth-server.example.com/oauth2/introspect
jwks:
- algorithm: RSA256
publicKey:
privateKey:
```
The OIDC Provider issues tokens that the AI Identity Gateway validates when agents connect. The `jwks` section defines the signing keys used to sign tokens -- the gateway fetches the public key from the `jwks` endpoint to verify token signatures.
> [!WARNING]
>
> Treat agent credentials with the same care as user passwords. Store the
> client secret in a [secret provider](/reference/orchestrator/configuration/secret-providers)
> \-- never in source code, configuration files, or environment variables that
> might be logged or exposed.
**2. Register the gateway client with token exchange**
Register the AI Identity Gateway as an OIDC application that can perform token exchange. This client uses the `urn:ietf:params:oauth:grant-type:token-exchange` grant type to exchange a user's token for a delegation token scoped to specific downstream APIs.
**Console UI**
> [!NOTE]
>
> **Console UI documentation is coming soon.** This section will walk you
> through configuring this component using the Maverics Console's visual
> interface, including step-by-step screenshots and field descriptions.
**Configuration**
Define the gateway client in the `apps` section with `grantTypes` that include both `client_credentials` and `token-exchange`. Configure `customScopes` for the MCP tools the gateway will broker access to.
```yaml maverics.yaml theme={null}
apps:
- name: ai-identity-gateway
type: oidc
clientID: ai-identity-gateway
credentials:
secrets:
-
grantTypes:
- client_credentials
- urn:ietf:params:oauth:grant-type:token-exchange
accessToken:
type: jwt
allowedAudiences:
- https://your-api.example.com/
- https://mcp-server.example.com/
customScopes:
scopes:
- name: user:List
- name: user:Get
- name: user:Create
- name: user:Update
- name: item:List
- name: item:Get
- name: item:Create
claimsMapping:
email: upstream-idp.email
name: upstream-idp.name
sub: upstream-idp.sub
```
The `grantTypes` array enables both `client_credentials` (for machine-to-machine auth) and `urn:ietf:params:oauth:grant-type:token-exchange` (RFC 8693 token exchange for delegation). The `allowedAudiences` list restricts which downstream services the gateway can request tokens for. The `customScopes` define the per-tool permissions that can be included in exchanged tokens.
Administrators can also configure token minting policies on the OIDC Provider app (`authorization.tokenMinting.accessToken.policies`) to apply OPA-based governance over which tokens get issued during exchange. This provides a second control point beyond inbound OPA policies -- inbound policies control which tool calls are allowed, while token minting policies control which tokens are issued. See the [OIDC Provider reference](/reference/modes/oidc-provider) for configuration details.
### Per-Tool Token Exchange
Each tool in the `tools` array gets its own `ttl` and `scopes`, and each tool invocation triggers a separate token exchange operation. This is not a single token with all scopes -- every tool call gets its own freshly minted token.
For example, when an agent calls `listEmployees`, the Orchestrator mints a token with only `employee:List` scope, valid for 5 seconds. When the same agent calls `createEmployee` a moment later, the Orchestrator performs a completely separate token exchange, minting a different token with only `employee:Create` scope, also valid for 5 seconds. The first token has already expired by the time the second call completes.
This means no token ever accumulates permissions across tools, and no token outlives its purpose. The `ttl` and `scopes` fields in the YAML above are not just configuration -- they define the security boundary for each individual tool invocation.
> [!TIP]
>
> Document your scope naming convention and share it with your team. Consistent
> scope names (like always using the `action:resource` pattern) make policies
> easier to write, review, and audit.
## Guides
> **[Expose APIs to Agents](/guides/ai-identity/mcp-bridge)**
>
> Make your existing REST APIs available to AI agents as discoverable MCP tools with full identity and authorization
> **[Protect MCP Servers](/guides/ai-identity/mcp-proxy)**
>
> Add identity governance to your existing MCP servers -- authenticate every agent and authorize every tool call
## Troubleshooting
> **Agent credentials rejected by identity provider**
>
> If an agent cannot authenticate with its client credentials, check the
> following:
>
> * Verify the client ID and client secret are correct. Client secrets are
> often only shown once when created -- if you have lost the secret, generate
> a new one in your identity provider.
> * Check that the agent's application registration is active and has not
> been disabled or deleted in the identity provider.
> * Confirm the grant type is set to "client\_credentials" in the agent's
> application registration.
> * Verify that the token endpoint URL in the Orchestrator's identity
> connector matches your identity provider's actual token endpoint.
> * If the agent's credentials have an expiration date, check whether they
> have expired.
> **Delegation chain not resolving**
>
> If the Orchestrator cannot resolve the delegation chain (the agent
> authenticates but the user context is missing):
>
> * Verify that the delegated token includes the `act` (actor) claim or
> whatever custom claim your identity provider uses for delegation.
> * Check that the token exchange was performed correctly -- the original
> user token must be exchanged for a delegated agent token, not simply
> passed through.
> * Verify that the gateway client's `grantTypes` includes
> `urn:ietf:params:oauth:grant-type:token-exchange`.
> * If your identity provider does not support the standard OAuth 2.0 token
> exchange, check the Orchestrator's identity connector documentation for
> provider-specific delegation configuration.
> * Enable debug logging in the Orchestrator to see the full token contents
> and identify which claims are present or missing.
> **Token exchange fails with invalid audience**
>
> If the token exchange succeeds but the downstream service rejects the
> exchanged token:
>
> * Verify the `allowedAudiences` in the gateway client includes the audience
> value used in the MCP app's `outbound.tokenExchange.audience`.
> * Check that the downstream service's expected audience matches the
> `audience` value in the token exchange configuration.
> * Review the exchanged token's claims (using a JWT debugger) to confirm
> the `aud` claim contains the expected value.
## Related Pages
> **[AI Identity Gateway Reference](/reference/modes/ai-identity-gateway)**
>
> Detailed configuration reference for all AI Identity Gateway modes and settings
> **[Security Guides](/guides/security/overview)**
>
> TLS, secrets management, authorization policies, and compliance guides
> **[Authentication Guides](/guides/authentication/overview)**
>
> SSO, OIDC, SAML federation, and identity provider migration guides