Skip to content

Reference for the OAuth requests your application sends in Embedded user authorization: An MCP authorization flow in which your application signs a user in through an OIDC Identity Provider and authorizes their access to one MCP server, with no Aembit page in the browser. The MCP Identity Gateway then uses that access on the user's behalf.Learn more, and for what Aembit returns. For how the flow works, see Embedded user authorization. To configure your Aembit Tenant: Aembit Tenants serve as isolated, dedicated environments within Aembit that provide complete separation of administrative domains and security configurations.Learn more, see Set up embedded user authorization.

Aembit treats your application as a public OAuth client, so your application holds no client secret and uses 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) for each code exchange. Configure these client settings in your application’s OAuth library:

PropertyValue
Client IDThe Aembit Client ID that the Aembit Tenant UI shows for an OIDC 1.0 Identity Provider
Client secretNone
Grant typesauthorization_code and refresh_token
PKCERequired, with the S256 method
Scopeopenid only
Aembit consentNone; Aembit shows no consent page

Your application uses two Aembit endpoints. It sends the person’s browser to the authorize endpoint to start the flow, and calls the token endpoint directly to exchange the code and refresh tokens. In each URL, replace <tenant-id> with your Aembit Tenant ID and <stack> with your Aembit Tenant’s stack:

EndpointURL
Authorizehttps://<tenant-id>.id.<stack>.aembit.io/connect/authorize
Tokenhttps://<tenant-id>.id.<stack>.aembit.io/connect/token

Your OAuth library can also read both endpoints from the discovery document at https://<tenant-id>.id.<stack>.aembit.io/.well-known/openid-configuration.

The authorize request starts the flow. Your application must send every parameter except state. All are standard OAuth parameters except mcp_server_url, which is specific to Aembit. Your application sends the person’s browser to the authorize endpoint with a URL that carries these query parameters:

ParameterRequiredValue
client_idYesThe Aembit Client ID from the Identity Provider’s page in the Aembit Tenant UI
redirect_uriYesYour application’s callback URL, matching a Redirect URI identifier
response_typeYescode
scopeYesopenid
stateNo (recommended)A value your application generates and checks on return. Aembit returns it unchanged
code_challengeYesThe PKCE challenge
code_challenge_methodYesS256
mcp_server_urlYesThe URL of the MCP server the person is authorizing
resourceYesThe MCP Identity Gateway URL that the Client-to-Gateway Policy’s Server Workload matches

mcp_server_url is an Aembit parameter. Neither OAuth nor the MCP authorization specification defines it, so your OAuth client must be able to add it to the authorize request.

mcp_server_url must meet every one of these rules, or Aembit rejects the request with invalid_request:

  • Present in the request
  • An absolute URL with a host
  • HTTPS
  • At most 2048 characters long
  • No user information and no fragment
  • A host that is not internal

Aembit then matches mcp_server_url to the Server Workload of one Gateway-to-Server Policy. Aembit ignores letter case in the scheme and host, a default port, and a trailing slash, and compares the path and query exactly.

redirect_uri must match a Redirect URI identifier on an active Client Workload in one of these ways:

  • Exactly
  • Against a configured value that ends in /*, with the same scheme, host, and port
  • For localhost and 127.0.0.1, with any port

See Redirect URI.

resource must be an absolute URI, or Aembit rejects the request with invalid_target. Aembit matches it to an active MCP Server Workload that meets these rules:

  • The host matches, and can be a wildcard on the Server Workload
  • The port and TLS setting match
  • The path matches, unless the Server Workload’s URL Path is empty

Aembit sends the person to the MCP server’s authorization server on every run of the flow. It does so even when Aembit already holds a token for that person and MCP server. The prompt value Aembit sends depends on the Authorization URL of the MCP User-Based Access Token Credential Provider:

When the Authorization URL containsprompt valueWhat Aembit asks the authorization server for
login.microsoftonline.comselect_accountAn account picker
phrase.comNoneNothing
Anything elseconsentThe consent page; the authorization server can still skip it

When the flow completes, Aembit redirects the browser to redirect_uri with these query parameters:

ParameterValue
codeThe authorization code
stateThe state value from the authorize request

Your application exchanges the code at the token endpoint with a POST request that carries these form parameters.

ParameterValue
grant_typeauthorization_code
codeThe code from the authorization response
code_verifierThe PKCE verifier that matches code_challenge
client_idThe same Aembit Client ID as the authorize request
redirect_uriThe same redirect_uri as the authorize request

The response holds these fields:

FieldValue
access_tokenAn MCP Identity Gateway access token from the Client-to-Gateway Policy’s Credential Provider
refresh_tokenPresent when that Credential Provider has Enable Refresh Token Support turned on

With an OIDC ID Token Credential Provider, the access token carries the user identifier in its idp_user_id claim.

Your application exchanges a refresh token at the token endpoint with a POST request that carries these form parameters.

ParameterValue
grant_typerefresh_token
refresh_tokenThe refresh token from the last token response
client_idThe same Aembit Client ID as the authorize request

The response holds these fields:

FieldValue
access_tokenA new MCP Identity Gateway access token
refresh_tokenA new refresh token, which replaces the one you sent

Each refresh token works once.

ItemLifetime
Authorization code5 minutes, and it works once
MCP Identity Gateway access tokenThe lifetime the Client-to-Gateway Policy’s Credential Provider sets
Refresh tokenWorks once, until the Credential Provider’s Absolute Token Lifetime ends

Aembit takes the user identifier from the ID token that the Identity Provider returns:

ID token contentsUser identifier
A claim, such as email, holds an email addressThat email address, in lowercase
No claim holds an email addressAnother identifier claim, such as sub or preferred_username
None of these claimsNone; the flow fails with access_denied

Aembit expects the user identifier to be an email address, so configure your Identity Provider to include the person’s email address in the ID token.

Errors that come before Aembit trusts redirect_uri do not reach your application. Aembit returns HTTP 400 or shows an Aembit error page in the browser instead, for conditions such as these:

  • client_id is not a valid Aembit Client ID, names another Aembit Tenant, or names an inactive Identity Provider.
  • redirect_uri matches no Redirect URI identifier (invalid_redirect_uri).
  • mcp_server_url breaks a rule (invalid_request).
  • The PKCE parameters are missing or invalid (invalid_request).
  • resource is not an absolute URI (invalid_target).

Errors after that point redirect the browser to redirect_uri with error, error_description, and the original state.

Aembit returns error=access_denied for each of these conditions, with the error_description that its row shows:

Conditionerror_description
The Client-to-Gateway Policy failsAembit Access Policy validation failed, followed by an authorization event ID
The Client Workload’s Enforce SSO list holds more than one active Identity ProviderMultiple Identity Providers matched for Zero-UI authorization
The Client Workload’s Enforce SSO list holds no active Identity ProviderNo active Identity Provider found for Zero-UI authorization
The ID token holds no user identifierUnable to determine user identity from identity provider.
No Gateway-to-Server Policy matches mcp_server_urlNo access policy found for the specified MCP server.
More than one Gateway-to-Server Policy matches mcp_server_urlMultiple conflicting access policies found for the specified MCP server.
The matched Access Policy does not have exactly one active MCP User-Based Access Token or SSO Access Token Passthrough Credential ProviderThe access policy for this MCP server is not properly configured.
The person declines consent at the MCP serverFailed to authorize credential provider: User declined consent or no authorization code was provided.

When the MCP server’s authorization server returns an error, Aembit passes it to your application as follows:

The authorization server returnserrorerror_description
A standard OAuth error, such as invalid_scope or temporarily_unavailableThe same errorIts error_description, or Upstream authorization failed when it sends none
A nonstandard error that names a redirect URIinvalid_request<upstream-error>: <upstream-description>
A nonstandard error that reports a denialaccess_denied<upstream-error>: <upstream-description>
Any other nonstandard errorserver_error<upstream-error>: <upstream-description>

When Aembit has no safe redirect for an error from the MCP server’s authorization server, it returns HTTP 400 with a JSON body instead.

At the token endpoint, a wrong code_verifier or a code that was already used returns invalid_grant. When the Client-to-Gateway Policy’s Credential Provider is an MCP User-Based Access Token, the token request returns invalid_request.

Aembit records an access authorization event for the Client-to-Gateway Policy when it evaluates the authorize request. The event ID in an Aembit Access Policy validation failed error points to that event. See Audit and report on Workload activity.