Support the SAML 2.0 Bearer Assertion Grant (RFC 7522) as the SAML counterpart of the JWT Authorization Grant #54076

ammad27k · 2026-10-17T11:58:24Z

ammad27k
Oct 17, 2026

Title: Support the SAML 2.0 Bearer Assertion Grant (RFC 7522) as the SAML counterpart of the JWT Authorization Grant

Summary

I'd like to propose, and contribute, support for the SAML 2.0 Bearer Assertion Grant (RFC 7522) in Keycloak. A client that already holds a SAML 2.0 assertion issued by a trusted identity provider could exchange it at the token endpoint for Keycloak access, refresh and ID tokens, with no browser redirect:

POST /realms/{realm}/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer
&assertion=PHNhbWw6QXNzZXJ0aW9uIC4uLg   (base64url-encoded SAML 2.0 Assertion)
&client_id=my-mobile-app
&scope=openid

As RFC 7522 allows, client authentication is optional: confidential clients authenticate as usual, and public clients (mobile apps, SPAs) can use the grant without a client secret when an administrator explicitly allows it (see Public clients).

Keycloak 26.5 added the JWT Authorization Grant (RFC 7523) as the recommended alternative to external-to-internal token exchange V1. This proposal is its SAML counterpart: it reuses the same architecture and configuration model, for identity providers that only speak SAML.

We have run a working implementation of this as a custom provider against Okta and other SAML identity providers, and recently migrated it to Keycloak 26.8.1. I'd like to turn it into an upstream contribution that fits Keycloak's design, and would value the maintainers' guidance before opening a PR.

Motivation

Many organizations, especially in finance, healthcare and the enterprise, federate identity only through SAML 2.0 (ADFS, Okta SAML apps, PingFederate, Shibboleth, in-house IdPs). In these setups the following is common:

A mobile or native app, a backend service or a partner platform already holds a valid, signed (often encrypted) SAML assertion for a user, for example from an IdP-initiated SSO or an embedded login.
It needs OAuth 2.0 / OIDC tokens from Keycloak to call APIs protected by Keycloak, without sending the user through another interactive login.

Today Keycloak has no built-in way to do this with a SAML assertion:

Option	Why it doesn't cover SAML
External-to-internal token exchange V1	Deprecated in favour of the JWT Authorization Grant. It only accepts tokens from OIDC/OAuth/social IdPs that implement `ExchangeExternalToken`; the SAML IdP doesn't.
Standard token exchange V2	Supports internal-to-internal exchange only. It explicitly rejects `subject_issuer` and accepts access tokens only.
JWT Authorization Grant (RFC 7523)	JWT assertions only.
SAML broker login	Requires a browser round-trip through the IdP. It can't be used by a backend or by an app that already has the assertion.

So every SAML-only deployment that needs this has to write and maintain a custom grant or token-exchange provider, including SAML signature validation, decryption, condition checks and replay handling. That is security-sensitive code that belongs in Keycloak's SAML stack.

RFC 7522 is the standard answer to exactly this problem, and the companion of RFC 7523, which Keycloak already implements.

Proposed design

I propose to mirror the JWT Authorization Grant as closely as possible, so administrators get a consistent model and most of the infrastructure is reused.

Request

New grant type urn:ietf:params:oauth:grant-type:saml2-bearer (RFC 7522 §2.1), with the assertion in the assertion form parameter, base64url-encoded.
Client authentication is optional, as in RFC 7522 §2.1. Confidential clients authenticate with their usual method. Public clients identify themselves with client_id and may use the grant only when it is explicitly enabled for them (see below). This is a deliberate difference from the JWT Authorization Grant, which is confidential-only. The main use case is native and mobile apps that receive a SAML assertion and can't hold a client secret.
Gated behind a feature flag (for example saml2-bearer-grant, preview first).

Trust configuration (SAML identity provider)

A new section on the SAML identity provider, analogous to the JWT Authorization Grant section on the OIDC identity provider:

Enable SAML 2.0 Bearer Assertion Grant
Allowed clock skew (or reuse the existing SAML IdP setting)
Maximum allowed assertion lifetime, to reject assertions whose validity window is too long
Allow assertion reuse (default: off)

The IdP's existing SAML settings are honoured, exactly as SAMLEndpoint does for browser logins: idpEntityId, signing certificates / validateSignature, wantAssertionsSigned, wantAssertionsEncrypted, principalType / principalAttribute, NameID policy and allowedClockSkew.

Client configuration

A per-client list of allowed identity providers for this grant, like the existing JWT Authorization Grant client setting, so an assertion from IdP A can't be used by a client that is only meant to trust IdP B.
A per-client switch "Allow SAML 2.0 Bearer Assertion Grant without client authentication", off by default and only available for public clients.

Public clients

Without client authentication, the signed assertion is the only proof behind the request. Anyone who obtains a valid assertion could present it with the client_id of any public client that allows the grant. To keep this safe, the following apply when the client is public (some are optional for confidential clients):

Explicit opt-in per client and per IdP: the switch above, plus the allowed-IdP list. A public client never gets this grant by default.
Replay protection is mandatory: the "allow assertion reuse" setting is ignored, and every assertion ID is accepted once only.
Short assertion lifetime: the IdP's maximum allowed assertion lifetime is enforced, so a captured assertion is only useful for a few minutes.
Optional client binding: an IdP setting that requires the client_id to appear in the assertion's AudienceRestriction (or SubjectConfirmationData/@Recipient), so an assertion issued for one app can't be used by another.
Sender-constrained tokens: support DPoP (RFC 9449) on this grant like on other grants, and let administrators require it through client policies.
Client policies: the grant fires its client-policy context for public clients too, so administrators can add conditions (for example, require DPoP, or restrict to specific client scopes).
Events: failures for public clients are logged with the IdP, issuer and assertion ID, so abuse is visible.

Validation (RFC 7522 §3)

Issuer: must match the entity ID of an enabled SAML IdP with the grant enabled. The IdP is looked up by issuer, as the JWT grant does with AlternativeLookupProvider.
Audience: AudienceRestriction must contain a value identifying Keycloak (the realm issuer and/or the IdP's configured SP entity ID).
Subject: must contain a NameID (or the principal configured on the IdP).
Subject confirmation: a SubjectConfirmation with Method="urn:oasis:names:tc:SAML:2.0:cm:bearer", whose SubjectConfirmationData has a NotOnOrAfter in the future and a Recipient equal to the token endpoint URL.
Validity: Conditions NotBefore / NotOnOrAfter, with clock skew, plus the configured maximum lifetime.
Signature: the assertion (or its enclosing Response) must be signed and valid against the IdP's signing certificates.
Encryption: EncryptedAssertion is decrypted with the realm's encryption keys (SAMLDecryptionKeysLocator), and enforced when wantAssertionsEncrypted is on.
Replay protection: the assertion ID is recorded with SingleUseObjectProvider until NotOnOrAfter, and a reused ID is rejected unless reuse is allowed. RFC 7522 §3 recommends this.

Errors return invalid_grant per RFC 7522 §3.1, with details in events rather than in the response.

User resolution

Like the JWT Authorization Grant, by default the user must already exist and be linked to the IdP: look up by federated identity (IdP alias + principal), and reject disabled users or users with pending required actions. That keeps the grant non-interactive and predictable.

Tokens, sessions, policies and events

The same as the JWT Authorization Grant: create the user session and client session, check consents, issue tokens through TokenManager, and record IdP notes on the session. Fire a client-policy context so administrators can restrict or extend the grant with client policies, and emit login events with the IdP alias, issuer and assertion ID.

Implementation sketch

Saml2BearerGrantType / Saml2BearerGrantTypeFactory in org.keycloak.protocol.oidc.grants, next to JWTAuthorizationGrantType.
A small provider interface implemented by SAMLIdentityProvider (the counterpart of JWTAuthorizationGrantProvider) that validates the assertion with the existing SAML core utilities (AssertionUtil, XMLSignatureUtil, SAMLDecryptionKeysLocator, ConditionsValidator, DestinationValidator) and returns a BrokeredIdentityContext.
Admin console: the new section on the SAML IdP page, and the client setting for allowed IdPs.
Tests in the new test framework, using a SAML IdP that issues signed and encrypted assertions, covering every validation rule above and the replay case.
Documentation in the Securing Applications guide, next to the JWT Authorization Grant.

What our current implementation does

Our provider is built as a token-exchange provider (subject_token_type=urn:ietf:params:oauth:token-type:saml2), because the dedicated grant type and the JWT grant's infrastructure didn't exist when we started. It:

matches the SAML IdP by the assertion's Issuer, and validates signatures, conditions, audience, bearer subject confirmation and Recipient;
accepts a bare Assertion as well as a full Response, plain or with EncryptedAssertion;
respects the SAML IdP's configuration, the same way SAMLEndpoint does;
runs the IdP mappers on the resulting BrokeredIdentityContext, so attributes behave as they do for a browser SAML login;
creates the user session and returns the standard token response;
works for public clients: our web application exchanges assertions without a client secret.

For upstream I'd align it with the design above: the dedicated saml2-bearer grant type, the JWT-grant configuration model, the existing-user requirement and replay protection, which our version doesn't have yet.

Open questions for maintainers

Public clients: is optional client authentication acceptable with the safeguards above (explicit opt-in, mandatory replay protection, short lifetime, optional client_id binding, DPoP), or would you prefer to start confidential-only, like the JWT Authorization Grant, and add public clients in a second step?
Grant type, token exchange, or both? I'd implement the RFC 7522 grant type. Should subject_token_type=urn:ietf:params:oauth:token-type:saml2 also be accepted in standard token exchange, or is the grant enough?
Just-in-time provisioning: the JWT Authorization Grant requires an existing linked user. Is that also the right default here, or would an opt-in IdP setting to create or link users (running the IdP mappers, like first broker login without interaction) be acceptable?
Assertion vs. Response: RFC 7522 specifies a single Assertion. In practice IdPs often hand out a whole signed Response with an EncryptedAssertion. Should Keycloak accept a Response too, or strictly an Assertion / EncryptedAssertion?
Shared code: should the validation live in SAMLIdentityProvider (reusing SAMLEndpoint logic), or in a shared SAML assertion validator that both the broker endpoint and the grant use?
Client authentication with SAML assertions (RFC 7522 §2.2) seems a natural follow-up, aligned with federated client authentication. I'd keep it out of this first step unless you'd prefer otherwise.

Contribution

I'm happy to do the full implementation, tests, admin console changes and documentation, and to adjust the design to your feedback before writing the PR. If this direction looks acceptable, I'll open a GitHub issue to track it and link it here.

References

RFC 7522: Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants: https://datatracker.ietf.org/doc/html/rfc7522
RFC 7523: JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants (implemented in Keycloak as the JWT Authorization Grant): https://datatracker.ietf.org/doc/html/rfc7523
RFC 8693: OAuth 2.0 Token Exchange (urn:ietf:params:oauth:token-type:saml2): https://datatracker.ietf.org/doc/html/rfc8693

ahus1 · 2026-10-22T07:37:00Z

ahus1
Oct 22, 2026
Collaborator

Thanks for raising this one. There is an existing GitHub issue here #54099 opened recently. Would that be the same? If yes, please up-vote that issue, and connect with that author.

3 replies

mriduldeka Oct 22, 2026

Hi @ahus1 , My suggestion is to go with this approach because this is following industry standard and implementing RFC 7522 which exchange SAML bearer grant type with OAuth token. My proposed implementation and steps given here are almost same but this proposal tries to implement RFCs which is right way.

We can contribute in this proposal as well if author is ok with that.

mriduldeka Oct 22, 2026

Hi @ammad27k , I have below questions --

Are we creating a OIDC client for corresponding SAML client in keycloak to return OAuth token ?
Can we support relay state also along with SAML assertion in request payload ?
Can we add support for JIT users as well in keycloak during SAML bearer assertion grant ?

cc: @ahus1

ahus1 Oct 22, 2026
Collaborator

Thank you for your interest into the topic. It might be worth searching manually or using AI in the existing open and closed issues of Keycloak regarding this topic, and then post a condensed set of information here.

ahus1 · 2026-10-22T07:48:56Z

ahus1
Oct 22, 2026
Collaborator

One more thing: Please try to find existing issues and discussions related to the topic. Keycloak's OAuth SIG https://www.keycloak.org/community might be a possible place to discuss this, and get a set of people interested.

0 replies

Navigation Menu

Repository navigation

Support the SAML 2.0 Bearer Assertion Grant (RFC 7522) as the SAML counterpart of the JWT Authorization Grant #54076

Uh oh!

{{title}}

Uh oh!

Replies: 2 comments 3 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Support the SAML 2.0 Bearer Assertion Grant (RFC 7522) as the SAML counterpart of the JWT Authorization Grant #54076

Uh oh!

ammad27k Oct 17, 2026

Summary

Motivation

Proposed design

Request

Trust configuration (SAML identity provider)

Client configuration

Public clients

Validation (RFC 7522 §3)

User resolution

Tokens, sessions, policies and events

Implementation sketch

What our current implementation does

Open questions for maintainers

Contribution

Replies: 2 comments · 3 replies

Uh oh!

ahus1 Oct 22, 2026 Collaborator

Uh oh!

Uh oh!

mriduldeka Oct 22, 2026

Uh oh!

Uh oh!

mriduldeka Oct 22, 2026

Uh oh!

ahus1 Oct 22, 2026 Collaborator

Uh oh!

ahus1 Oct 22, 2026 Collaborator

ammad27k
Oct 17, 2026

Replies: 2 comments 3 replies

ahus1
Oct 22, 2026
Collaborator

ahus1 Oct 22, 2026
Collaborator

ahus1
Oct 22, 2026
Collaborator