SAML 2.0 bearer assertion grant handler SPI
Clients can use SAML 2.0 assertions to request an access token and optional ID token from the Connect2id server. Such use of SAML 2.0 assertions as OAuth 2.0 authorisation grants is specified in RFC 7522.
The common use case for the SAML 2.0 assertion grant is enabling clients that utilise existing SAML SSO and IdP infrastructure to obtain OAuth 2.0 tokens for accessing protected resources such as web APIs.
- A user initiates login to an application;
- The application as a SAML 2.0 SP redirects the user to the SAML 2.0 IdP and receives a SAML 2.0 assertion on success;
- If access to an OAuth 2.0 protected resource (e.g. web API) is required, the client exchanges the SAML 2.0 assertion for an access token at the token endpoint of the Connect2id server.
2. SAML 2.0 bearer assertion grant handler SPIs
The Connect2id server allows enterprises to apply arbitrary authorisation and business logic to SAML 2.0 assertion grants, in order to determine the properties of the issued tokens (scope, audience, expiration, etc).
This is achieved by means of two flexible plugin interfaces (SPI) -- one for handling self-issued SAML 2.0 assertions and another for handling third-party (Security Token Service, or STS) assertions.
Features of the SAML 2.0 bearer grant handlers:
Support SAML 2.0 assertions that are issued by the client itself (self-issued) or by a third party (Security Token Service);
The clients can act on the behalf of another subject (an end-user) or on their own behalf;
Client authentication is optional. If present, it is independent and orthogonal from the SAML 2.0 assertion. A client can authenticate explicitly with one of the standard methods, such as
private_key_jwt, or implicitly, using the JWT assertion itself;
Permit issue of an OpenID Connect ID token (not covered by the SAML 2.0 grant spec).
If the Connect2id server detects an SPI implementation it will log its loading
INFO main MAIN - [OP7106] Loaded and initialized urn:ietf:params:oauth:grant-type:saml2-bearer grant handler com.nimbusds.openid.connect.provider.spi.grants.saml.selfissued.handler.SimpleSelfIssuedSAMLGrantHandler
2.1 Self-issued SAML 2.0 bearer assertion grant handler
This grant handler SPI is intended for clients which are registered with the Connect2id server and are themselves the issuers of the SAML 2.0 assertions.
- The client must be registered for the SAML 2.0
- The SAML 2.0 assertion issuer must match the
- The SAML 2.0 audience and recipient must match the token endpoint URI or the OP issuer;
- The SAML 2.0 assertion must be HMAC protected with the
client_secretor signed with a registered RSA or EC key; the following XML digital signature algorithms are accepted:
- RSA signature with SHA-2:
- ECDSA signature with SHA-2:
- Explicit client authentication with the token request (using
client_secret_ basic, etc) is optional, as the SAML 2.0 assertion itself can authenticate the client.
To implement a grant handler for SAML 2.0 assertions issued by the client, use the SelfIssuedSAML2GrantHandler SPI.
2.2 Third-party issued SAML 2.0 bearer assertion grant handler
This grant handler SPI is intended for clients which submit SAML 2.0 assertions issued by a third party Identity Provider (IdP) or Secure Token Service (STS), in order to obtain access tokens for protected resources (web APIs) managed by the Connect2id server.
- Explicit client authentication with the token request (e.g. using
client_secret_ basic) is recommended if the SAML 2.0 assertion by itself is not sufficient to authenticate the client.
- The handler is free to determine how the SAML 2.0 assertion is validated and processed. The handler will typically use a trusted certificate chain or store a copy of the issuer's public keys to validate the received SAML 2.0 assertions.
- If the SAML 2.0 assertion grant is found valid, the handler must resolve the
client_idwhich must be registered with the Connect2id server. If no explicit client authentication is provided (see pt. 1), the handler may use a previously agreed upon SAML attribute to establish the
To implement a grant handler for SAML 2.0 assertions issued by a third party, use the ThirdPartyJWTGrantHandler SPI.
interface provided at SPI initialisation time
can be used to verify a resolved
client_id and obtain registered client