PingOne Advanced Identity Cloud

SAML 2.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 2.0 assertions for requesting access tokens and for client authentication. This page describes how to exchange a SAML 2.0 assertion for an access token.

In this profile, the SAML 2.0 identity provider (IDP) authenticates the resource owner, obtains authorization, and prepares a signed assertion to use the PingOne Advanced Identity Cloud REST APIs. PingOne Advanced Identity Cloud 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. PingOne Advanced Identity Cloud validates the assertion and returns an error if it cannot validate the assertion.

    On success, PingOne Advanced Identity Cloud issues an access token to the client.

  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 PingOne Advanced Identity Cloud 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://<tenant-env-fqdn>:443/am/.

  • Specify the resource owner with an identifier known to PingOne Advanced Identity Cloud; otherwise, PingOne Advanced Identity Cloud 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 PingOne Advanced Identity Cloud configuration must include:

  • The OAuth 2.0 provider and SAML 2.0 SP in the same PingOne Advanced Identity Cloud 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://<tenant-env-fqdn>/am/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 2.0 assertion.

scope=openid

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