Skip to content
Connect2id

SAML 2.0 grant handler

1. Overview

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.

The flow:

  1. A user initiates login to an application;
  2. 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;
  3. 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 under OP7106.

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.

Prerequisites:

  1. The client must be registered for the SAML 2.0 bearer grant urn:ietf:params:oauth:grant-type:saml2-bearer;
  2. The SAML 2.0 assertion issuer must match the client_id;
  3. The SAML 2.0 audience and recipient must match the token endpoint URI or the OP issuer;
  4. The SAML 2.0 assertion must be HMAC protected with the client_secret or signed with a registered RSA or EC key; the following XML digital signature algorithms are accepted:
    • HMAC-SHA-2:
      • https://www.w3.org/2001/04/xmldsig-more#hmac-sha256
      • https://www.w3.org/2001/04/xmldsig-more#hmac-sha384
      • https://www.w3.org/2001/04/xmldsig-more#hmac-sha512
    • RSA signature with SHA-2:
      • https://www.w3.org/2001/04/xmldsig-more#rsa-sha256
      • https://www.w3.org/2001/04/xmldsig-more#rsa-sha384
      • https://www.w3.org/2001/04/xmldsig-more#rsa-sha512
    • ECDSA signature with SHA-2:
      • https://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256
      • https://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384
      • https://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512
  5. 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.

Prerequisites:

  1. 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.
  2. 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.
  3. If the SAML 2.0 assertion grant is found valid, the handler must resolve the client_id which 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 client_id.

To implement a grant handler for SAML 2.0 assertions issued by a third party, use the ThirdPartyJWTGrantHandler SPI.

The ServiceContext interface provided at SPI initialisation time can be used to verify a resolved client_id and obtain registered client metadata.