SAML and API Gateways: Separate SSO from API Authorization

SAML remains deeply embedded in enterprise single sign-on, while modern APIs commonly use OAuth access tokens and OpenID Connect. Problems begin when teams treat those artifacts as interchangeable or ask an API gateway to infer authorization from an assertion that was issued for a different audience and flow.

This week's widely discussed Hacker News thread on SAML's complexity is a useful prompt to revisit the boundary. The practical answer is not "SAML is obsolete" or "OAuth replaces SAML everywhere." It is to assign each protocol a clear job, validate every artifact in its intended context, and keep application authorization explicit.

Key Takeaways

SAML 2.0 is commonly used for browser-based enterprise SSO, while OAuth access tokens authorize API access and OIDC adds an identity layer.
A validly signed SAML assertion is not automatically valid for a particular API, action, or tenant.
Terminate the enterprise login flow at a trusted relying party, then issue or obtain an API-appropriate session or access token.
Validate issuer, audience, recipient, time conditions, signature, and replay controls before consuming SAML claims.
At the gateway, authenticate the API credential and enforce route, method, scope, and tenant policy separately.
Preserve the SAML bearer assertion OAuth authorization grant as a standards-defined alternative, but treat client authentication separately: a pending standards update says new applications must not use SAML bearer assertions for client authentication.

SAML, OAuth, and OIDC Solve Different Problems

The SAML 2.0 Core specification defines XML assertions and protocols for communicating authentication and authorization statements. In a common web SSO flow, an identity provider authenticates a user and sends an assertion through the browser to a service provider's assertion consumer service.

OAuth 2.0 is an authorization framework. A client presents an access token to a resource server to exercise delegated or client-specific access. The current OAuth 2.0 Security Best Current Practice updates deployment guidance and deprecates less safe historical patterns. OpenID Connect adds an end-user authentication layer: its ID token communicates the authentication event and subject to the client. It should not be substituted for an API access token without an explicit design.

These roles can coexist:

flowchart LR
    U[Enterprise user] -->|Browser SSO| I[Identity provider]
    I -->|SAML response| R[Relying party or identity broker]
    R -->|Session or OAuth flow| C[Application client]
    C -->|Access token| G[API gateway]
    G -->|Authorized request| A[Application API]

The diagram shows a common architecture, not the only standards-compliant path. RFC 7522 currently permits a SAML 2.0 bearer assertion as an OAuth authorization grant or for client authentication. The pending draft-ietf-oauth-rfc7523bis-11, already in the RFC Editor queue but not yet an RFC, says new applications must not use this client-authentication method. Existing deployments should assess migration and stricter audience validation. Authorization-grant clients must target the intended authorization server—using its issuer identifier, token endpoint URL, or SAML Entity ID—and servers must reject assertions that do not identify them. In either case, validate the applicable issuer, signature, replay, and authorization-server requirements; a SAML assertion is not a bearer token for every API.

Why Direct Assertion-to-API Designs Become Fragile

A SAML assertion may contain a subject, authentication context, attributes, conditions, and an intended audience. None of those fields alone proves that a caller may invoke DELETE /accounts/{id} or read a different tenant's data.

Several boundaries are easy to blur:

Authentication versus authorization: the assertion can report how the identity provider authenticated a subject; the API still needs a policy for the requested resource and action.
Signed versus acceptable: a valid XML signature protects the correctly resolved signed element under a configured key. The consumer must bind the claims it uses to that validated element, reject ambiguous or duplicate-ID selections, and still validate the issuer, audience, recipient, time window, subject confirmation, and expected flow.
Attribute present versus trusted for policy: an attribute such as role=admin is usable only when the issuer, schema, mapping, and authorization policy explicitly establish its meaning.
One-time login versus repeated API calls: replay defenses for a browser SSO response do not automatically create suitable token lifetime, revocation, proof-of-possession, or scope semantics for APIs.
Human session versus workload identity: a service process needs its own client or workload credentials; copying a user's SSO artifact into a background job loses actor and delegation boundaries.

This is why the safest general pattern is to consume SAML at the enterprise login boundary and expose an API credential designed for the resource server. It reduces the number of components that parse complex signed XML and gives the API a token with explicit issuer, audience, expiry, client, and scope semantics.

When SAML is the required enterprise federation protocol, the relying party or broker should pin its behavior to the organization's metadata and profile. The validation checklist includes:

trust the configured identity provider and the correct signing key from controlled metadata;
require the expected response and assertion signatures for the selected profile;
verify Issuer, AudienceRestriction, Recipient, and InResponseTo where the flow uses them;
validate NotBefore and NotOnOrAfter with a small, documented clock-skew allowance;
verify subject confirmation and destination against the actual endpoint;
reject unexpected duplicate or ambiguous security-critical XML elements;
record assertion identifiers or equivalent state where replay detection is required;
map attributes through an allowlisted schema rather than passing arbitrary claims downstream.

The exact checks depend on the SAML profile and library. Use a maintained SAML implementation and the OWASP SAML Security Cheat Sheet as a review aid; do not build signature or XML canonicalization logic inside an application handler.

Failure timing depends on the profile. In a browser SSO bridge, reject an invalid SAML response before creating an application session or initiating a subsequent OAuth flow. In the RFC 7522 bearer profile, the assertion is carried in the token request, so the authorization server performs the required SAML validation as part of that exchange. In either case, a later API policy cannot compensate for an audience or signature failure.

Exchange Identity for an API-Appropriate Credential

After successful enterprise login, the application can establish a secure browser session or use an authorization server to issue an access token for the API. The token should name the API audience, client, subject or workload, expiry, and granted scopes or permissions. Short lifetimes reduce exposure; revocation or introspection may be appropriate when fast invalidation is required.

Keep the user's identity and the calling client separate. A browser application acting for a person is different from a batch process using client credentials. When a backend calls another API on the user's behalf, use an explicit delegation or token-exchange design rather than forwarding a SAML response or browser cookie to every service.

An identity broker can bridge a SAML enterprise directory to OIDC/OAuth for modern applications. The broker is then a security boundary: it must preserve the authoritative subject, tenant, authentication context, and relevant attributes without granting broader API access than the source identity and policy allow.

API7.ai's guides to identity authentication protocols and OpenID versus OAuth provide more background on choosing the client-facing protocol.

Enforce API Policy at the Gateway

Once the client presents an OAuth access token, the API gateway can centralize resource-server checks. Pin implementation claims to a deployed release: in Apache APISIX 3.18.0, the openid-connect plugin documents bearer-token verification through introspection or JWKS-based validation, required-scope checks, and authorization-code flows for browser routes.

Configure the mode to match the route. For a machine API, bearer_only: true requires a bearer access token instead of redirecting an unauthenticated caller into a browser login. For an interactive browser route, the authorization-code flow can establish a session. Do not mix the two behaviors on a route merely because both eventually identify a user.

Authentication is only the first gate. Apply authorization by route, method, resource, tenant, and scope. Validate that:

the token issuer and signature or introspection response are trusted;
the token is active and within its time window;
the aud or resource indication matches the API's validation policy;
the client and subject are appropriate for the operation;
required scopes or permissions cover the route and method;
tenant context comes from a trusted mapping, not an unchecked request header.

If the gateway forwards identity context upstream, overwrite caller-supplied copies and send only fields the application needs. A header containing a username or group is not trusted merely because it exists; its trust comes from the gateway's completed validation and a protected gateway-to-upstream path.

Plan for Failure, Rotation, and Mixed Clients

Identity systems fail in several phases. The SAML identity provider can be unavailable during login, an authorization server can fail during token issuance or introspection, and a gateway can lose access to discovery or key material. Decide which existing sessions or tokens remain usable and for how long. Do not convert an identity-provider outage into unconditional access.

Key rotation also needs overlap. Refresh federation metadata and JWKS on a controlled schedule, retain the previous valid key during the issuer's advertised transition, and alert on unknown key identifiers. A cache improves availability but can extend acceptance of stale policy, so its lifetime is part of the security decision.

During migration, browser users, API clients, and service accounts may use different mechanisms. Keep route policy explicit. Apache APISIX 3.18.0 also documents a multi-auth plugin, but supporting multiple methods does not make their identities or assurance levels equivalent. Map each method to a common authorization model deliberately, and retire compatibility paths on a dated plan.

Architecture Checklist

Keep Federation at the Right Boundary

SAML can remain the correct answer for an enterprise identity provider while OAuth access tokens remain the correct answer for a resource server. The architecture becomes easier to reason about when the SAML relying party, authorization server, API gateway, and application each validate the artifact intended for that boundary.

Explore API7 Enterprise to centralize API authentication, authorization, traffic policy, and observability after enterprise identity has been translated into an API-appropriate credential.