PingAM 7.5.1

SAML v2.0 profile for authorization

Endpoints

RFC 7522 Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants defines the use of SAML v2.0 assertions for requesting access tokens and for client authentication. This page describes how to exchange a JWT bearer token for an access token.

In this profile, the SAML v2.0 identity provider (IDP) authenticates the resource owner, obtains authorization, and prepares a signed assertion to use the AM REST APIs. AM does not interact with the resource owner in this grant flow or present consent pages.

SAML assertion for authorization flow

oauth2-saml2-bearer

  1. The client directs the resource owner to the IDP for authentication.

  2. The IDP authenticates the resource owner and returns a signed assertion.

  3. On success, the IDP supplies a signed assertion.

  4. The IDP redirects the resource owner to the client with the assertion.

  5. The client exchanges the assertion for an access token.

  6. AM validates the assertion and, on success, issues an access token to the client.

    If AM cannot validate the assertion, it returns an error.

  7. The client uses the token when requesting access to protected resources.

  8. The resource server contacts the authorization server to validate the access token.

  9. The authorization server validates the token and responds to the resource server.

  10. The resource server allows the client to access the protected resources.

Configuration requirements

The OAuth 2.0 client application must:

  • Inform the resource owner they grant consent by authenticating with the IDP.

  • Consume the access token and handle errors as necessary.

  • Include Grant Types: SAML2 in its AM profile.

The IDP must:

  • Issue signed assertions.

  • Specify an issuer in the assertion matching the IDP’s name; for example, https://idp.example.com:8443/idp.

  • Specify an audience in the assertion matching the service provider’s (SP) name; for example, https://openam.example.com:8443/openam/.

  • Specify the resource owner with an identifier known to AM; otherwise, AM returns an error such as the following:

    {"error_description":"AM identity should not be null","error":"server_error"}

    When using a transient flow, configure an identity in the SP’s Transient User setting to map all transient ID references to a specific identity.

The AM configuration must include:

  • The OAuth 2.0 provider and SAML v2.0 SP in the same AM server.

  • A requirement in the SP configuration for signed assertions from the IDP.

  • A circle of trust with the IDP and the SP.

  • Grant Types: SAML2 in the OAuth 2.0 provider configuration. (This is the case by default.)

Example access token request

$ curl \
--request POST \
--user 'myClient:forgerock' \
--data 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer' \
--data 'assertion=<saml-assertion>' \
--data 'redirect_uri=https://www.example.com:443/callback' \
--data 'scope=openid' \
'https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/access_token'

As shown in the example, the request includes these parameters:

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer

Required for this grant.

assertion=<saml-asserion>

The base64-encoded, then URL-encoded SAML v2.0 assertion.

scope=openid

Example scope. The scope parameter is required if no default scopes are set for the client.