Build an Agentic Identity Flow

This tutorial walks through configuring two Maverics deployments to support agentic AI workflows:

1. AI Identity Gateway - Hosts the MCP proxy or MCP bridge for AI agent communication
2. OIDC Provider - Hosts the OIDC Provider and handles token exchange

Architecture Overview

+-------------+    (2)    +---------------------+    (4)    +------------+
|  AI Agent   |---------->| AI Identity Gateway |---------->| MCP Server |
+-------------+           +---------------------+           +------------+
       |                            |
       |(1)                         |(3)
       v                            v
      +-------------------------------------+        +---------------+
      |            OIDC Provider            |--(1)-->| Federated IDP |
      +-------------------------------------+        +---------------+

1. Agent authenticates user. OIDC Provider federates to existing IDP. Policy can control token issuance.
2. Agent sends MCP request with user access token. Policy can control tool access.
3. Gateway exchanges user access token for an ephemeral, finely scoped access token. Policy can control token exchange and permitted scopes.
4. Gateway forwards request with exchanged token to the backend.

How to Use This Tutorial

This tutorial has two parts. The Milestones section provides a step-by-step progression with testing checkpoints. The Deployment Reference section provides configuration details for each component. Work through the milestones in order, consulting the deployment reference sections as needed.

A template Maverics account has been provided as a reference. This template account has been fully populated with the resources pertinent to this tutorial. For access to a template account, please contact support@strata.io.

Prerequisites

• Two Maverics instances (they can run on the same host)
• An MCP client (agent) for testing connectivity and tool invocation (see the test infrastructure section below for a sample MCP client)
• A target API or MCP server to route requests to (see the test infrastructure section below for a sample MCP server)
• Understanding of OIDC and token exchange concepts

Test Infrastructure

To enable easy testing, an open source MCP client and and MCP server can be used. If you already have an MCP client (agent) and MCP server available, feel free to skip this section.

MCP Client

The MCP Inspector is an MCP client that can be used for testing. The Inspector fully implements the MCP authorization spec and can be easily run locally. The Inspector can be started with a single command:

npx @modelcontextprotocol/inspector

After starting the Inspector, be sure to configure it to use the Streamable HTTP transport. Please note that the MCP client will ultimately point at the AI Identity Gateway as its target URL.

MCP Server

The MCP Everything is a sample MCP server that can be used for testing. This server comes with a collection of pre-packaged tools. The server can be started with a single command:

npx @modelcontextprotocol/server-everything streamableHttp

Be sure to pass the streamableHttp flag when starting the server.

AI Identity Gateway & OIDC Provider

In order to install and deploy a Maverics Orchestrator, please see the installation documentation.

Milestones

This tutorial is designed for iterative testing. Each milestone builds on the previous, in order to keep your deployments functional throughout.

Milestone 0: Basic connectivity

Configure (AI Identity Gateway and OIDC Provider): Deploy both Maverics instances. Please note that only minimal environment configuration is required to start the Orchestrator's HTTP server. Ensure TLS is configured and each instance is reachable over the network.

Test: Verify each deployment is running by checking the status endpoint (e.g., https://<host>/status).

Expected result: Both the AI Identity Gateway and OIDC Provider return a healthy status response.

Milestone 1: AI Identity Gateway accepts MCP requests

Configure (AI Identity Gateway): Enable the MCP Provider for your AI Identity Gateway deployment. Leave OAuth authorization disabled for now to simplify initial testing.

Test: Connect your MCP client (agent) to the gateway endpoint. This will help resolve basic networking issues.

Expected result: The agent connects successfully. No tools are available yet since no MCP apps are registered.

Milestone 2: Tools route to upstream servers

Configure (AI Identity Gateway): Register an MCP app to expose tools to your agent. Choose MCP Proxy if you have an existing MCP server, or MCP Bridge if you want to expose a REST API. Set both inbound and outbound authorization to unprotected for now.

Test: Verify your agent can discover tools. Attempt to invoke a tool.

Expected result: Tools from your upstream server are available. If your backend doesn't require authentication, tool invocations return results. If your backend is protected, you may see authorization errors - this confirms requests are reaching the backend and will be resolved when token exchange is configured.

Milestone 3:OIDC Provider issues tokens

Configure (OIDC Provider): Enable the OIDC Provider, add an Identity Connector that federates authentication to your existing identity provider, and register a new OIDC app for your agent. The app registered for the agent should use authorization code grant with PKCE and have the AI Identity Gateway as an allowed audience.

Configure (AI Identity Gateway): Enable OAuth authorization on the MCP Provider and point it to the OIDC Provider's well-known endpoint.

Test: Reconnect your agent to the gateway. The agent must support OAuth per the MCP specification. Complete sign-in through your identity provider when prompted.

Expected result: The agent obtains an access token to be used on subsequent tool calls. The user is authenticated via your existing IDP.

Milestone 4: Inbound policy enforced at AI Identity Gateway

Configure (AI Identity Gateway): Update the MCP app's inbound authorization to use OPA policy instead of unprotected. Write a policy that controls tool access based on user identity. Now that tokens contain user attributes, you can write policies based on group membership, roles, or other custom claims.

Test: Invoke tools and verify policy decisions match your expectations. Test both allowed and denied scenarios.

Expected result: Tool invocations are allowed or denied based on your policy rules.

Milestone 5: Token exchange between AI Identity Gateway and OIDC Provider

Configure (OIDC Provider): Register a second OIDC app for the AI Identity Gateway. This app should have the client credentials grant and token exchange grant enabled. Configure the allowed scopes and audiences for your upstream APIs.

Configure (AI Identity Gateway): Add an OIDC connector that points to the AI Identity Gateway app on the OIDC Provider. Update the MCP app's outbound authorization to use token exchange instead of unprotected.

Test: Invoke a tool call.

Expected result: The gateway exchanges the user's token for an upstream token and the backend accepts the request.

Milestone 6: Token exchange policy enforced

Configure (OIDC Provider): Add a token minting policy to the AI Identity Gateway OIDC app. This policy controls when user tokens can be exchanged and what scopes can be requested. Use the policy to enforce rules based on user attributes, the requested audience, or the requested scopes.

Test: Invoke tools and verify token exchange policy decisions match your expectations. Test both allowed and denied scenarios.

Expected result: Token exchange requests are allowed or denied based on your policy rules.

AI Identity Gateway Deployment Reference

The AI Identity Gateway serves as the MCP proxy layer, mediating communication between AI agents and backend MCP servers or APIs. It validates inbound tokens issued by the OIDC Provider, enforces access policies on tool invocations, and performs token exchange for outbound requests to protected resources.

Setup the HTTP Server

Configure the Orchestrator to serve HTTP traffic. It is always recommended to use TLS.

See: HTTP Server

Configure the MCP Provider

Enable the MCP Provider to expose MCP endpoints for AI agents. Configure the transport layer (SSE or streamable HTTP) and session management settings.

Configure OAuth Authorization

Point the MCP Provider's OAuth authorization to the OIDC Provider. This validates that inbound requests carry valid tokens issued by your OIDC Provider. Configure:

• The well-known endpoint of the OIDC Provider
• Expected audiences matching the AI Identity Gateway
• Token validation method (JWT validation or introspection)

See: MCP Provider

Register MCP Apps

Register MCP apps to define how the gateway routes requests. Two app types are available:

1. MCP Proxy - Proxies requests to an upstream MCP server. Use this when you have existing MCP servers and want to add authentication, authorization, and token exchange in front of them.

2. MCP Bridge - Exposes an OpenAPI specification as MCP tools. Use this to make existing REST APIs available to AI agents without modifying the backend.

See: MCP Proxy, MCP Bridge

Configure Inbound Authorization (Policy)

Define policies that control which tools agents can invoke. Use OPA (Open Policy Agent) policies to enforce fine-grained access control based on:

• User identity and attributes from the inbound token
• Tool name and parameters
• Custom business logic

See: MCP Proxy, MCP Bridge, OPA Authorization

Configure Outbound Authorization (Token Exchange)

For protected backend resources, configure token exchange to obtain appropriately-scoped tokens for upstream calls. This requires:

• An OIDC connector pointing to the OIDC Provider's token exchange app
• Audience and scope mappings for each tool or tool pattern
• Optional per-tool TTL settings for exchanged tokens

See: MCP Proxy, MCP Bridge, OIDC Connector

OIDC Provider Deployment Reference

The OIDC Provider handles authentication and token issuance for the agentic flow. It acts as an OIDC Provider that issues tokens to AI agents and supports token exchange for upstream API access. Policy enforcement can be applied throughout the flow to control token issuance, exchange, and resource access.

Setup the HTTP Server

Configure the Orchestrator to serve HTTP traffic. It is always recommended to use TLS.

See: HTTP Server

Configure the OIDC Provider

Set up the Orchestrator as an OIDC Provider with standard OAuth 2.0/OIDC endpoints. This enables token issuance, introspection, and revocation.

See: OIDC Provider, applications and user flows

Configure an Identity Connector

Configure a connector to federate end-user authentication to your existing identity provider (e.g., Microsoft Entra ID, Okta, PingFederate, etc.). When an AI agent initiates an authentication flow, the Orchestrator delegates user authentication to the upstream IDP, enabling single sign-on and leveraging your existing identity infrastructure.

See: Connectors

Register OIDC Apps

Register two OIDC apps:

1. Agent App - A public application for the AI agent to authenticate users and obtain initial tokens. Configure with:

   • Authorization code grant with PKCE
   • Appropriate redirect URLs for your agent
   • Allowed audiences for the AI Identity Gateway

2. AI Identity Gateway App - A confidential application for token exchange operations. The AI Identity Gateway uses this app to exchange user tokens for upstream API access. Policy can be applied at two points: during token exchange (controlling which tokens can be exchanged and for what scopes) and at runtime when the agent accesses protected resources. Configure with:

   • Client credentials grant
   • Token exchange grant (urn:ietf:params:oauth:grant-type:token-exchange)
   • Custom scopes for upstream API access

See: OIDC Provider, applications and user flows

Configure Token Minting Policies using Open Policy Agent (OPA)

Add token minting policies using OPA to enforce custom rules before issuing tokens. Use these to:

• Add custom claims based on user attributes
• Enforce attribute-based access control (ABAC)
• Enforce role-based access control (RBAC)

See: OIDC Provider, applications and user flows