Embedded user authorization
Use when your application has its own UI, such as a portal or AI agent platform.
During an embedded user authorization flow, the person signs in to their Identity Provider and connects one MCP Server: A server that implements the Model Context Protocol to provide tools, resources, or data to AI agents and MCP clients.Learn more(opens in new tab). At the end of the flow, your application gets an MCP Identity Gateway: A component that brokers MCP traffic between MCP clients and target MCP servers, validating authorization and presenting Aembit-managed credentials on each request.Learn more access token that acts as that person, and calls MCP Identity Gateway with it. MCP Identity Gateway presents the person’s own credential to the MCP server.
Your application must run a standard OAuth authorization code flow with PKCE (Proof Key for Code Exchange): An OAuth 2.0 extension that prevents authorization code interception attacks. The client creates a cryptographic challenge during the authorization request and proves possession of the original secret when exchanging the code for a token.Learn more(opens in new tab) against Aembit. The people who use your application must sign in with SSO through an OpenID Connect (OIDC): An identity layer built on top of OAuth 2.0 that lets applications verify the identity of a user or workload and obtain basic profile information using JSON Web Tokens (JWTs).Learn more(opens in new tab) Identity Provider. The Client Workload: Client Workloads represent AI agents, software applications, scripts, or automated processes that initiate access requests to Server Workloads. They can act on behalf of a user under blended identity or operate autonomously, as when one service calls another.Learn more that represents your application must have Enforce SSO on.
When to use embedded user authorization
Section titled “When to use embedded user authorization”- People connect MCP servers without leaving your application.
- Your application decides which MCP server a person authorizes.
How embedded user authorization works
Section titled “How embedded user authorization works”What the person sees
Section titled “What the person sees”Connecting an MCP server takes the person through their Identity Provider’s sign-in page and the MCP server’s consent page.
- Your application starts the flow, and the person’s browser goes to the sign-in page of the person’s Identity Provider. The Identity Provider might skip that page when the person already has a session there.
- The browser goes to the MCP server’s consent page, where the person approves access.
- The browser returns to your application.
Aembit shows no page of its own along the way, such as an Identity Provider picker or a status page. Aembit sends the person to the MCP server each time your application runs the flow, even when Aembit already holds a token for that person and MCP server. Most MCP servers show their consent page on every run, and some skip it for a person who already consented. See Consent at the MCP server.
What your application does
Section titled “What your application does”Your application starts the flow by sending the person’s browser to Aembit’s authorize endpoint, naming the MCP server the person is authorizing. Every redirect in the following diagram passes through the person’s browser.
After the flow, your application calls MCP Identity Gateway with the access token. MCP Identity Gateway finds the person’s stored MCP server token and presents it to the MCP server.
For every parameter, rule, and error in this flow, see Embedded user authorization reference.
Access Policy requirements
Section titled “Access Policy requirements”Each Access Policy: Access Policies define, enforce, and audit access between Client and Server Workloads by cryptographically verifying workload identity and contextual factors rather than relying on static secrets.Learn more in the flow requires a specific Credential Provider: Credential Providers obtain the specific access credentials—such as API keys, OAuth tokens, or temporary cloud credentials—that Client Workloads need to authenticate to Server Workloads.Learn more.
- The Client-to-Gateway Policy: The Access Policy that validates which MCP client can connect to the MCP Identity Gateway and authenticates users through your Identity Provider. Also called left-side auth; you create one per MCP client and Gateway combination.Learn more needs an OIDC ID Token Credential Provider, with its Audience set to the MCP Identity Gateway URL.
- The Gateway-to-Server Policy: The Access Policy that authorizes the MCP Identity Gateway to access an MCP server on behalf of authenticated users—the Gateway itself is the Client Workload. Also called right-side auth; each MCP server behind the Gateway needs its own.Learn more needs exactly one active MCP User-Based Access Token Credential Provider and no active SSO Access Token Passthrough Credential Provider. Exactly one Gateway-to-Server Policy must match the MCP server the person is authorizing.
Token lifetimes
Section titled “Token lifetimes”When the MCP server issues a refresh token, Aembit refreshes the stored MCP server token on its own for as long as the MCP server honors that refresh token.
The access token your application gets lasts for the lifetime the Client-to-Gateway Policy’s Credential Provider sets. When that Credential Provider has Enable Refresh Token Support turned on, your application also gets a refresh token. Your application exchanges the refresh token for a new access token until the Credential Provider’s Absolute Token Lifetime ends. Without a valid refresh token, your application must run the flow again when the access token expires. Aembit then sends the person back to the MCP server.
Limitations
Section titled “Limitations”- Each run of the flow authorizes one MCP server. A person who needs more than one MCP server goes through the flow once for each.
- Your application names the MCP server in the
mcp_server_urlparameter, an Aembit addition that neither OAuth nor the MCP authorization specification defines. Your application’s OAuth client must be able to add a custom parameter to the authorize request.