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).
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.
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
Our Connect2id support team is available if you need help with configuring a SAML 2.0 bearer assertion grant handler or implementing your own.