Access Management 7.3.1

SAML v2.0 profile for authorization grant

Endpoints

The SAML v2.0 profile for authorization grant is designed for environments that want to leverage the REST-based services provided by AM’s OAuth 2.0 support, while keeping their existing SAML v2.0 federation implementation.

The RFC 7522 describes the means to use SAML v2.0 bearer assertions to request access tokens and to authenticate OAuth 2.0 clients.

At present, AM implements the profile to request access tokens.

Consider the following requirements before implementing this flow:

  • The client (the application the resource owner uses to start the flow) must inform the resource owner that, by authenticating to the SAML v2.0 identity provider, the resource owner grants the client access to the protected resources. AM does not present the resource owner with consent pages.

    This client must be able to consume the access token and handle errors as required.

  • The OAuth 2.0 authorization service and SAML v2.0 service provider must be configured in the same AM instance.

  • The service provider must require that assertions are signed.

  • The SAML v2.0 identity provider must issue signed assertions.

    The assertion must contain the SAML v2.0 entity names, as follows:

    • The issuer must be set to the identity provider’s name. For example, https://idp.example.com:8443/idp.

    • The audience must be set to the service provider’s name. For example, https://openam.example.com:8443/openam.

  • The identity provider and the service provider must belong to the same circle of trust.

  • AM must be able to determine the resource owner from the name ID contained in the assertion. Failure to determine the resource owner results in an error similar to:

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

    AM may fail to determine the resource owner if the assertion contains an opaque name ID during transient federation. Because the opaque reference is never stored during a transient flow, the OAuth 2.0 provider cannot determine the resource owner it relates to.

    To work around this, configure an identity in the Transient User field of the SAML v2.0 service provider. This will map all transient ID references to that identity.

  • The OAuth 2.0 client is registered, at least, with the following configuration:

    • Grant Types: SAML2

  • The OAuth 2.0 provider is configured. Ensure that:

    • The SAML2 grant type is configured in the Grant Types field.

The following diagram demonstrates the SAML v2.0 Profile for authorization grants:

SAML v2.0 Profile for Authorization Grant Flow
Figure 1. SAML v2.0 Profile for Authorization Grant Flow

  1. The client requests the SAML v2.0 identity provider the SAML v2.0 assertion related to the resource owner. Usually, this means the client redirects the resource owner to the identity provider for authentication.

  2. The SAML v2.0 identity provider returns the signed assertion to the client.

  3. The client includes the assertion and a special grant type in the call to the OAuth 2.0 token endpoint in the following parameters:

    • grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer

    • assertion=my-assertion

      Note that the assertion must be first base64-encoded, and then URL encoded.

    For example:

    $ curl \
--request POST \
--data "client_id=myClient" \
--data "client_secret=forgerock" \
--data-urlencode "assertion=PHNhbWxwOl…​ZT4" \
--data "grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer" \
--data "redirect_uri=https://www.example.com:443/callback" \
--data "scope=write" \
"https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/access_token"

  4. The AM authorization server validates the assertion. If the assertion is valid, the authorization server returns an access token to the client.

  5. The client request access to the protected resources from the resource server.

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

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

  8. If the token is valid, the resource server allows the client to access the protected resources.