AI Identity Gateway

The AI Identity Gateway mode extends the Maverics Orchestrator into the world of AI agents and tool-use. As AI agents interact with enterprise systems through the Model Context Protocol (MCP), they need identity — who is the agent acting on behalf of, what permissions does it have, and which tools can it access. The AI Identity Gateway solves these challenges through two specialized app types: MCP Bridge and MCP Proxy.

Console terminology: In the Maverics Console, the combination of applications, policies, headers, and connector bindings is managed through User Flows. In YAML, these elements are configured directly within each app’s configuration block under apps[].policies[].

App Types

The AI Identity Gateway provides two app types, each designed for a different deployment pattern. Both share provider-level settings for transports and OAuth authorization to authenticate inbound agent connections.

MCP Bridge App

Translate REST APIs into MCP tools — reads OpenAPI specs and generates an MCP tool catalog with delegated authorization

MCP Proxy App

Proxy MCP traffic to upstream MCP servers with identity injection, per-tool authorization, and delegation token exchange

Agent Identity

AI agents present unique identity challenges that traditional user authentication does not address. When an agent calls an MCP tool on behalf of a user, the system must track both the agent’s identity and the delegated user identity — ensuring that the agent can only access resources the user has authorized. The AI Identity Gateway propagates identity context through the entire agent-to-tool chain:

Agent authentication — Verify the identity of the AI agent itself before allowing any tool access
User delegation — Carry the delegating user’s identity and permissions through agent tool calls
Scope enforcement — Restrict agent actions to the specific permissions the user has granted
Audit trail — Log both agent and user identity for every tool invocation, enabling compliance and forensics

When to use each sub-mode

MCP Bridge — Choose this when you have existing REST APIs you want AI agents to access. MCP Bridge translates REST APIs into MCP tools automatically.
MCP Proxy — Choose this when you have existing MCP servers that need identity. MCP Proxy adds authentication and authorization to MCP connections.

How It Works

The AI Identity Gateway processes agent requests through a layered pipeline that validates identity, enforces authorization, and preserves audit context at every step:

Agent connection — An AI agent connects to the AI Identity Gateway Orchestrator’s MCP endpoint via SSE or Streamable HTTP transport.
OAuth discovery — The gateway returns protected resource metadata (RFC 9470) via /.well-known/oauth-protected-resource, which lists the Auth Provider Orchestrator (or other authorization servers) the agent can authenticate against.
Agent authentication — The agent authenticates against the Auth Provider Orchestrator and obtains an access token. The agent presents this token to the AI Identity Gateway Orchestrator.
Token validation — The AI Identity Gateway Orchestrator validates the agent’s token against the configured authorization server. The token identifies both the agent and the delegating user.
Tool discovery — The agent requests available tools. For MCP Bridge apps, tools are generated from OpenAPI specs. For MCP Proxy apps, tools are discovered from upstream MCP servers. Tools from multiple apps can be namespaced to avoid naming conflicts.
Tool invocation with authorization — When the agent invokes a tool, the AI Identity Gateway Orchestrator evaluates OPA policies on the inbound request, performs token exchange via the Auth Provider Orchestrator to obtain a scoped delegation token, and forwards the request to the upstream service.
Response and audit — The upstream response flows back through the Orchestrator to the agent, with full audit logging capturing the agent identity, delegating user identity, tool name, and outcome.

Key Concepts

Two-Deployment Architecture

The AI Identity Gateway involves two orchestrator roles that are typically (but not necessarily) separate deployments:

Auth Provider Orchestrator — Runs the OIDC Provider with OIDC apps. Acts as the OAuth authorization server. 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 MCP Proxy apps. Handles MCP transport, tool routing, inbound authorization (OPA policies), and upstream forwarding.

The AI Identity Gateway Orchestrator includes an OIDC connector that points to the Auth Provider Orchestrator’s well-known URL. This is how the two deployments connect — the gateway discovers the auth server’s signing keys and token endpoints through the standard OIDC discovery mechanism. For simpler deployments, both roles can run on a single orchestrator instance. In production, they are typically separate to isolate the token-issuing infrastructure from the MCP gateway. See AI Identity overview for a step-by-step walkthrough of configuring both deployments.

MCP (Model Context Protocol)

MCP is an open protocol for AI agents to discover and invoke tools. The AI Identity Gateway adds identity and authorization to MCP, which the protocol does not natively provide. The Orchestrator acts as an MCP server to agents while acting as an MCP client (or REST client) to upstream services.

Provider-Level vs App-Level

Provider-level settings are shared across all MCP apps: inbound transports (how agents connect) and OAuth authorization (how agent tokens are validated). Individual MCP Bridge and MCP Proxy apps configure their own upstream connections, tool catalogs, and per-tool authorization. This separation means all MCP apps on one Orchestrator share the same inbound endpoint.

Delegation vs Impersonation

Token exchange supports two modes. Delegation (default) produces tokens with an act claim showing both user and agent identity — ideal for auditability. Impersonation produces tokens that fully assume the user’s identity with no trace of the agent — needed when upstream services don’t understand the act claim.

Per-Tool Authorization

Each tool can have its own OAuth scopes and token TTL, enabling least-privilege access. A read-only tool gets narrow scopes; a write tool gets broader scopes. Tool names support exact matching and regex patterns for wildcarding.

Inbound vs Outbound

This is the critical architectural distinction. Inbound configuration (transports, OAuth) controls how agents connect TO the Orchestrator. Outbound configuration (upstream, token exchange) controls how the Orchestrator connects to backend services. They are independently configured.

Setup

Console UI
Configuration

In the Maverics Console, MCP Provider settings are configured in the Deployment Settings dialog under the MCP Provider section.General

Field	Required	Description
Enabled	Yes	Toggle to enable the MCP Provider. On by default.
Server Name	No	MCP server name for identification. Defaults to “Maverics AI Identity Gateway”.

Agent Connection and Session ManagementTransports (HTTP Stream):

Field	Required	Description
Stream Endpoint	Yes	URL path where agents connect via Streamable HTTP (e.g., `/mcp`).

Session:

Field	Required	Description
Header Name	No	HTTP header used for session IDs. Default: `Mcp-Session-Id`.
Session Timeout	Yes	Duration before idle sessions expire. Default: 1 hour.
Allow Client Termination	No	Toggle to allow clients to terminate their own sessions. On by default.

OAuth 2.0 Authorization Settings

Field	Required	Description
Enable OAuth Authorization	No	Toggle to enable OAuth authorization for inbound MCP connections. Off by default.

The Console UI provides a subset of the full YAML configuration. SSE transport configuration, keep-alive settings, OAuth server details (well-known endpoint, token validation method, expected audiences), and metadata refresh intervals are only available in YAML. See the Configuration tab for the complete reference.

The AI Identity Gateway requires the MCP Provider top-level key for shared provider settings (transports and OAuth authorization). Individual MCP apps (MCP Bridge and MCP Proxy) are configured under the apps array — see the MCP Bridge App and MCP Proxy App pages for app-level configuration.

# This mcpProvider config runs on the AI Identity Gateway Orchestrator
mcpProvider:
  enabled: true
  transports:
    stream:
      enabled: true
      path: "/mcp"
      session:
        enabled: true
        headerName: "Mcp-Session-Id"
        timeout: 1h
  authorization:
    oauth:
      enabled: true
      metadataPath: /.well-known/oauth-protected-resource
      servers:
        - wellKnownEndpoint: https://auth.example.com/.well-known/oauth-authorization-server
          tokenValidation:
            expectedAudiences:
              - https://gateway.example.com/
            method: jwt

Configuration Reference

The mcpProvider top-level key configures the MCP server behavior shared across all MCP apps (MCP Bridge and MCP Proxy). It defines the inbound transports (how AI agents connect to the Orchestrator) and OAuth authorization (how agent tokens are validated). Every MCP app served by this Orchestrator instance uses these provider-level settings.

Key	Type	Required	Description
`mcpProvider.enabled`	Boolean	Yes	Enable the MCP provider
`mcpProvider.serverName`	String	No	MCP server name for identification. Default: `Maverics AI Identity Gateway`
`mcpProvider.transports.sse.enabled`	Boolean	No	Enable SSE transport (legacy MCP transport)
`mcpProvider.transports.sse.baseURL`	String	No	Base URL for SSE connections. Overrides the default base URL derived from the Orchestrator’s address.
`mcpProvider.transports.sse.basePath`	String	No	Base path prefix for SSE endpoints
`mcpProvider.transports.sse.path`	String	Conditional	SSE connection endpoint path. Required when SSE is enabled.
`mcpProvider.transports.sse.messagePath`	String	Conditional	SSE message posting endpoint path. Required when SSE is enabled.
`mcpProvider.transports.sse.keepAlive.enabled`	Boolean	No	Enable SSE keep-alive pings
`mcpProvider.transports.sse.keepAlive.interval`	String	No	Keep-alive interval (duration string, e.g., `30s`). Must be positive when enabled.
`mcpProvider.transports.stream.enabled`	Boolean	No	Enable Streamable HTTP transport (recommended for new deployments)
`mcpProvider.transports.stream.path`	String	Conditional	Stream endpoint path. Required when stream is enabled.
`mcpProvider.transports.stream.session.enabled`	Boolean	No	Enable session support for stateful MCP interactions
`mcpProvider.transports.stream.session.headerName`	String	Conditional	Session ID header name. Required when sessions are enabled.
`mcpProvider.transports.stream.session.allowClientTermination`	Boolean	No	Allow clients to terminate their sessions
`mcpProvider.transports.stream.session.timeout`	String	No	Session timeout (duration string, e.g., `1h`). Must be positive when enabled.
`mcpProvider.authorization.oauth.enabled`	Boolean	No	Enable OAuth authorization for inbound MCP connections
`mcpProvider.authorization.oauth.metadataPath`	String	Conditional	OAuth Protected Resource metadata path (RFC 9470). Required when OAuth is enabled.
`mcpProvider.authorization.oauth.servers[].wellKnownEndpoint`	String	Yes	OAuth authorization server discovery endpoint
`mcpProvider.authorization.oauth.servers[].refreshInterval`	String	No	Metadata refresh interval (duration string). Must be positive.
`mcpProvider.authorization.oauth.servers[].tokenValidation.expectedAudiences`	Array	Yes	Expected token audiences. At least one required.
`mcpProvider.authorization.oauth.servers[].tokenValidation.method`	String	No	Token validation method: `jwt`, `introspection`, or `auto`. The `auto` method tries JWT first, then falls back to introspection.
`mcpProvider.authorization.oauth.servers[].tokenValidation.jwt.clockSkew`	String	No	Clock skew tolerance for JWT validation (duration string, e.g., `15s`)
`mcpProvider.authorization.oauth.servers[].tokenValidation.introspection.clientID`	String	Conditional	Client ID for token introspection requests. Required when `method` is `introspection` or `auto`.
`mcpProvider.authorization.oauth.servers[].tokenValidation.introspection.clientSecret`	String	Conditional	Client secret for token introspection requests. Required when `method` is `introspection` or `auto`.
`mcpProvider.authorization.oauth.servers[].tokenValidation.introspection.timeout`	String	Conditional	Timeout for introspection requests (duration string, e.g., `5s`). Must be positive. Required when `method` is `introspection` or `auto`.
`mcpProvider.authorization.oauth.servers[].tokenValidation.introspection.maxRetries`	Integer	No	Maximum retry attempts for introspection requests

Inbound vs Outbound

The MCP configuration has a critical directional distinction:

Inbound (mcpProvider.transports) — Configures how AI agents connect TO the Orchestrator. The Orchestrator exposes SSE and/or Streamable HTTP endpoints that agents connect to for tool discovery and invocation.
Outbound (apps[].upstream) — Configures how the Orchestrator connects to upstream services. For MCP Proxy, this is the upstream MCP server. For MCP Bridge, this is the REST API backend. Outbound transport is configured per-app on the respective app pages.

This separation means mcpProvider.transports settings apply to all MCP apps on this Orchestrator instance, while each app independently configures its own outbound connection.

The AI Identity Gateway uses Identity Fabric connectors on the Auth Provider Orchestrator (not on the gateway itself) to authenticate agents and issue tokens. The connector configuration for agent authentication lives on the Auth Provider’s OIDC Provider deployment. These are the most commonly used connectors for agent identity:

Microsoft Entra ID

Microsoft Entra ID for agent authentication

Okta

Okta for agent authentication

Auth0

Auth0 for agent authentication

Generic OIDC

Any OIDC provider for agent authentication

See the connector compatibility matrix for all supported pairings and the Identity Fabric overview for the full connector list.

MCP Bridge App

Full configuration reference, Console UI setup, and troubleshooting for MCP Bridge apps

MCP Proxy App

Full configuration reference, Console UI setup, and troubleshooting for MCP Proxy apps

OIDC Provider

Configure the Auth Provider Orchestrator for token issuance and exchange

Applications

Overview of all application types and how they fit into a deployment

Console Administration

Orchestration

App Types

MCP Bridge App

MCP Proxy App

Agent Identity

How It Works

Key Concepts

Two-Deployment Architecture

MCP (Model Context Protocol)

Provider-Level vs App-Level

Delegation vs Impersonation

Per-Tool Authorization

Inbound vs Outbound

Setup

Configuration Reference

Inbound vs Outbound

Microsoft Entra ID

Okta

Auth0

Generic OIDC

MCP Bridge App

MCP Proxy App

OIDC Provider

Applications

Console Administration

Orchestration

​App Types

MCP Bridge App

MCP Proxy App

​Agent Identity

​How It Works

​Key Concepts

​Two-Deployment Architecture

​MCP (Model Context Protocol)

​Provider-Level vs App-Level

​Delegation vs Impersonation

​Per-Tool Authorization

​Inbound vs Outbound

​Setup

​Configuration Reference

​Inbound vs Outbound

​Related Integrations

Microsoft Entra ID

Okta

Auth0

Generic OIDC

​Related Pages

MCP Bridge App

MCP Proxy App

OIDC Provider

Applications

App Types

Agent Identity

How It Works

Key Concepts

Two-Deployment Architecture

MCP (Model Context Protocol)

Provider-Level vs App-Level

Delegation vs Impersonation

Per-Tool Authorization

Inbound vs Outbound

Setup

Configuration Reference

Inbound vs Outbound

Related Integrations

Related Pages