How Authentication Works

The Maverics Orchestrator handles authentication across five modes, each serving a different protocol: OIDC, SAML, HTTP, LDAP, and MCP. Although each mode speaks a different wire protocol, the three core modes — OIDC Provider, SAML Provider, and HTTP Proxy — follow a common authentication pipeline: intercept the request, authenticate the user against an upstream identity provider, enrich the user’s attributes, establish a cookie-based session, and deliver identity to the application in the format it expects. LDAP Provider and AI Identity Gateway follow a similar pattern but handle authentication state differently: LDAP Provider uses per-connection bind state rather than cookie-based sessions, and AI Identity Gateway uses OAuth token-based state management. This page explains how that pipeline works so you can understand the system holistically before diving into mode-specific configuration. By the end, you will know which steps are shared across the core modes, where LDAP Provider and AI Identity Gateway diverge, and how sessions and Service Extensions fit into the authentication lifecycle. Understanding the shared pipeline also makes it easier to run multiple modes simultaneously. Many deployments combine HTTP Proxy with LDAP Provider for legacy stacks, or run OIDC Provider alongside SAML Provider for mixed application portfolios. Because OIDC Provider, SAML Provider, and HTTP Proxy share the same session and attribute enrichment infrastructure, users authenticated in one of these modes carry their identity context across the system. LDAP Provider uses per-connection bind state and does not participate in the shared session infrastructure. AI Identity Gateway uses token-based state management tied to the upstream OAuth authorization server.

​

The Authentication Pipeline

OIDC Provider, SAML Provider, and HTTP Proxy follow the same six-step pipeline, with steps 2 through 4 shared across these three modes. LDAP Provider and AI Identity Gateway follow a similar pattern but differ in how they handle authentication (step 2) and session state (step 4). Steps 1 and 5 differ by mode across all five modes.

1. Request arrives — A protocol-specific trigger starts the flow. For OIDC, this is an authorization request to the /oauth2/auth endpoint. For SAML, it is an AuthnRequest from a service provider. For HTTP Proxy, it is any HTTP request matching a route pattern. For LDAP, it is a bind operation on the LDAP port. For AI Identity Gateway, it is an MCP connection with an OAuth token.
2. Upstream IdP authentication — The Orchestrator routes the user to a configured upstream identity provider (Azure AD, Okta, PingFederate, or any OIDC/SAML/LDAP connector) for authentication. If multiple IdPs are configured, the Orchestrator tries them in order — if the primary IdP is unavailable, authentication falls back to the next provider seamlessly. The Continuity connector enables health-check-driven failover without application changes.
3. Attribute enrichment — After authentication succeeds, attribute providers load additional claims about the user from directories, databases, and APIs. This enrichment step aggregates identity data from multiple sources into a single profile, regardless of which IdP authenticated the user.
4. Session establishment — For OIDC Provider, SAML Provider, and HTTP Proxy, the Orchestrator creates a server-side session containing the authentication state, tokens, and enriched attributes. An opaque session cookie is returned to the client. All sensitive data stays server-side — the cookie is just an identifier. LDAP Provider maintains per-connection bind state instead of creating a cookie-based session. AI Identity Gateway relies on the upstream OAuth token lifecycle rather than Orchestrator-managed sessions. See the Sessions documentation for configuration details.
5. Identity delivery — The Orchestrator delivers the authenticated identity in the format the application expects. For OIDC, this means issuing ID tokens, access tokens, and optional refresh tokens. For SAML, it means generating a signed assertion. For HTTP Proxy, it means injecting identity headers into the upstream request. For LDAP, it means returning translated directory entries. For AI Identity Gateway, it means propagating identity context through tool invocations.
6. Ongoing operations — After the initial authentication, the Orchestrator manages the ongoing lifecycle: token refresh for OIDC, session expiry and re-authentication for cookie-based modes, and audit logging of identity events.

​

Per-Mode Authentication Flows

Each mode implements the shared pipeline with protocol-specific behavior at the entry and delivery points. The following sections summarize how authentication works in each mode without duplicating the full reference documentation.

​

OIDC Provider

The OIDC Provider mode configures the Orchestrator as an OpenID Connect authorization server, issuing standards-compliant tokens to applications that support OIDC natively.

1. The application redirects the user to the Orchestrator’s authorization endpoint (/oauth2/auth) with standard OIDC parameters (client ID, redirect URI, scopes).
2. The Orchestrator authenticates the user against the configured upstream IdP. The upstream IdP can use any protocol — the Orchestrator handles protocol translation between OIDC, SAML, and LDAP.
3. After authentication and attribute enrichment, the Orchestrator generates OIDC tokens — an ID token, an access token, and optionally a refresh token — with claims mapped from the authenticated identity.
4. The application receives the tokens at its redirect URI and uses them for session establishment and authorization decisions.
5. The Orchestrator serves the JWKS endpoint for token verification, handles token introspection and revocation, and manages refresh token flows.

​

SAML Provider

The SAML Provider mode configures the Orchestrator as a SAML 2.0 identity provider, generating signed assertions for enterprise applications that require SAML federation.

1. A SAML service provider sends an AuthnRequest to the Orchestrator’s SSO endpoint (SP-initiated flow), or a user navigates to an IdP-initiated login URL.
2. The Orchestrator authenticates the user against the upstream IdP. The upstream IdP can use any protocol — the Orchestrator handles protocol translation between OIDC, SAML, and LDAP.
3. After attribute enrichment, the Orchestrator generates a signed SAML assertion containing the NameID and mapped attributes.
4. The SAML response is POSTed to the service provider’s assertion consumer service URL. The SP validates the signature and establishes a session.

​

HTTP Proxy

The HTTP Proxy mode deploys the Orchestrator as an identity-aware reverse proxy, injecting authentication headers into upstream requests without requiring any changes to the application.

1. The Orchestrator intercepts HTTP requests matching configured route patterns (hostname/path combinations) before they reach the upstream application.
2. If the user does not have a valid session, the Orchestrator redirects them to the configured IdP for authentication. After authentication, a session cookie is established.
3. The Orchestrator evaluates location-based authorization rules against the user’s attributes.
4. For authorized requests, the Orchestrator injects identity headers (e.g., SM_USER, X-Remote-User) into the upstream request using template syntax that maps claims from connectors.
5. The request is forwarded to the upstream backend with the injected headers. The application uses these headers for its own identity decisions.

​

LDAP Provider

The LDAP Provider mode configures the Orchestrator as a virtual LDAP directory, presenting a standard LDAP interface to applications while sourcing identity data from modern cloud identity providers.

1. An LDAP-dependent application connects to the Orchestrator’s LDAP endpoint (ldap:// or ldaps://) and sends a bind request with a DN and password.
2. A Service Extension validates the credentials against a cloud identity provider — typically by translating the LDAP bind into an authentication request against the upstream IdP.
3. After successful authentication, the application sends LDAP search requests. A search Service Extension translates these into queries against upstream identity sources and returns matching entries in LDAP format.
4. The Service Extension maps cloud IdP attributes (e.g., Azure AD user properties) into the LDAP attribute names the application expects (e.g., cn, sAMAccountName, memberOf).

​

AI Identity Gateway

The AI Identity Gateway mode extends the Orchestrator into AI agent-to-tool communication, adding identity, authorization, and audit to Model Context Protocol (MCP) connections.

1. An AI agent connects to the Orchestrator’s MCP endpoint via SSE or Streamable HTTP transport and presents an OAuth access token.
2. The Orchestrator validates the agent’s token against the configured OAuth authorization server. The token identifies both the agent and the delegating user.
3. The agent discovers available tools — generated from OpenAPI specs (MCP Bridge) or discovered from upstream MCP servers (MCP Proxy).
4. When the agent invokes a tool, the Orchestrator evaluates OPA policies on the inbound request, performs token exchange to obtain a scoped delegation token, and forwards the request to the upstream service.

​

Sessions and Authentication

After authentication succeeds in OIDC Provider, SAML Provider, or HTTP Proxy mode, the Orchestrator creates a server-side session that persists the user’s authentication state. This session is the bridge between the initial authentication event and subsequent requests — it eliminates the need for re-authentication on every request. LDAP Provider and AI Identity Gateway manage authentication state differently: LDAP Provider maintains per-connection bind state (see the LDAP Provider reference), and AI Identity Gateway relies on the OAuth token lifecycle (see the AI Identity Gateway reference). The session stores authentication state, tokens from upstream identity providers, and enriched attributes from attribute providers. All of this data stays server-side. The client receives only an opaque session cookie (the maverics_session cookie by default) that identifies the session. Because the cookie carries no sensitive data, session hijacking risks are limited to cookie theft, which is mitigated by the Orchestrator’s secure cookie defaults (HttpOnly, Secure, SameSite). On subsequent requests, the Orchestrator checks whether the session cookie maps to a valid, unexpired session. If it does, the user is considered authenticated and the request proceeds without re-authentication. If the session has expired or the cookie is missing, the user is redirected through the full authentication flow. Session lifetime is controlled by two settings: a maximum lifetime (total time since authentication, default 12 hours) and an optional idle timeout (time since last activity, disabled by default). Both can be evaluated dynamically using Service Extensions, enabling context-aware timeout policies — for example, shorter timeouts for contractors and longer timeouts for employees. For multi-node deployments, each Orchestrator instance maintains its own local session store. To ensure users consistently reach the instance that holds their session, configure cookie-based sticky sessions (session affinity) on your load balancer using the maverics_session cookie. For complete session configuration including cookie settings, lifetime controls, and store options, see the Sessions reference.

​

Service Extensions in the Auth Lifecycle

Service Extensions are Go-based hook functions that customize the Orchestrator’s behavior at key points in the authentication and authorization lifecycle. The following hooks are most relevant to authentication:

• isAuthenticatedSE — Runs a custom check to determine whether the user is already authenticated. Available on OIDC, SAML, and HTTP Proxy apps. Must be paired with authenticateSE.
• authenticateSE — Implements custom authentication logic when standard IdP connector authentication is insufficient. Required for LDAP Provider mode. Must be paired with isAuthenticatedSE on OIDC, SAML, and HTTP Proxy apps.
• isAuthorizedSE — Runs custom authorization logic after authentication succeeds. Available on all app types that support authorization rules.
• buildClaimsSE — Constructs custom claims for SAML assertions, replacing the declarative claimsMapping when more complex logic is needed.
• buildIDTokenClaimsSE / buildAccessTokenClaimsSE — Customize the claims included in OIDC ID tokens and access tokens, respectively.
• loadAttrsSE — Loads custom attributes from external sources after authentication, supplementing or replacing the declarative attrProviders configuration.

These hooks provide escape hatches when standard configuration is insufficient. For the full list of 22 hook points and their function signatures, see the Service Extensions reference.

​

Related Pages