SAML v2.0 Profile for Authorization Grant

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.

Note

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.

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

    • Response Types: token

    • Grant Types: SAML2

  • The OAuth 2.0 provider is configured. Ensure that:

    • The token Response Type Plugin is configured.

    • The SAML2 Supported Grant Type is configured.

The following diagram demonstrates the SAML v2.0 Profile for Authorization Grants:

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

The steps in the diagram are described below:

  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/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.

Read a different version of :