OAuth 2.0 - SAML Bearer Flow

Overview

The SAML bearer grant type (RFC7522) allows a client application to exchange a SAML assertion for an access token. The SAML assertion contains information about the user's identity, such as their name, email address, and other attributes. The client application sends the JWT to the Safewhere Identify, which validates the assertion and returns an access token to the client application.

And Safewhere Identify supports both SAML 1.1 assertion and SAML 2.0 assertion bearer grant type.

OpenId Connect Discovery endpoint

The OpenID Connect Discovery endpoint now contains two new supported grant types: urn:ietf:params:oauth:grant-type:saml-bearer and urn:ietf:params:oauth:grant-type:saml2-bearer in the grant_types_supported property:

  "grant_types_supported": [
    ...
    "urn:ietf:params:oauth:grant-type:saml-bearer",
    "urn:ietf:params:oauth:grant-type:saml2-bearer"
  ],

Configuration

To use the SAML bearer grant type in Safewhere Identify, you need to configure the OAuth connection by following these steps:

1. Open the existing OAuth/OIDC application.
2. Go to its Security tab and enable the Allow SAML bearer flow.

3. Go to its Connection tab and add Bootstrap token trusted issuer.

• Issuer: The iss (issuer) value of the applied SAML assertion.
• Find Value: The certificate thumbprint to validate the signing of the applied SAML assertion.

Note that Bootstrap token trusted issuers do not allow duplicated certificate thumbprints.

You can also enable additional SAML assertion validation options:

• Received Security Token Encryption certificate: Specify the certificate information so that the Safewhere Identify can decrypt the received SAML assertion when it is encrypted.

• Validate target audience: When enabled, the audience information of the SAML assertion must be the Safewhere Identify Entity ID.
• Detect replay attack when doing token exchange: When enabled, Safewhere Identify OAuth server performs replay attack detection for every token request.

• Signing certificate revocation check: When the selected value is not None, Safewhere Identify performs a revocation check for the signing certificate used to sign the SAML assertion.
• Encryption certificate revocation check: When the selected value is not None, Safewhere Identify performs a revocation check for the encryption certificate used to encrypt the SAML assertion.

SAML 1.1 known issue

• STS SAML1.1 assertion contain trust:BinarySecret that cause error about "trust' is an undeclared prefix. Line 1, position 711."

• STS SAML1.1 assertion that is used for SAML Bearer must have saml:NameIdentifier section.

Ask for a token

Perform a POST operation to the token endpoint:

https://#identifydomain/runtime/oauth2/token.idp

With the following parameters:

Parameter	Description
client_id	Your application's client ID
client_secret	Your application's client secret
grant_type	This must be "urn:ietf:params:oauth:grant-type:saml-bearer" for SAML 1.1 flow or "urn:ietf:params:oauth:grant-type:saml2-bearer" for SAML 2.0 flow
assertion	{SAML Assertion}

The {SAML Assertion} is the base64-encoded SAML assertion that you received from your SAML20 identity provider.

Request body example when grant_type is urn:ietf:params:oauth:grant-type:saml-bearer:

Key	Value
client_id	test_client_id
client_secret	test_client_secret
grant_type	urn:ietf:params:oauth:grant-type:saml-bearer
assertion	PD94bWwgdmVyc2l...zZXJ0aW9uPg==

Request body example when grant_type is urn:ietf:params:oauth:grant-type:saml2-bearer:

Key	Value
client_id	test_client_id
client_secret	test_client_secret
grant_type	urn:ietf:params:oauth:grant-type:saml2-bearer
assertion	PEFzc2VydGlvb...zc2VydGlvbj4=

If the request is valid, Safewhere Identify returns an access_token.

{
    "scope": "identify*empty",
    "token_type": "Bearer",
    "access_token": "eyJh...XdhDEpdR76eO",
    "expires_in": 3600
}

If the request is invalid, you may encounter errors with the following event IDs:

• Event ID 4934: This error occurs when the input SAML assertion fails to validate.

• Event ID 4935: This error occurs when the Bootstrap Token Trusted Issuers on the Connection are not configured correctly, resulting in the inability to load the certificate.