AM 7.3.1

OAuth 2.0 node

Lets AM authenticate users of OAuth 2.0-compliant resource servers.

References in this section are to RFC 6749, The OAuth 2.0 Authorization Framework.

This node and its related services, are deprecated.

For information about the legacy/deprecated social authentication node and module implementations, refer to Social authentication in the ForgeRock Access Management 7 Authentication and Single Sign-On Guide.

Outcomes

  • Account Exists

  • No account Exists

Evaluation continues along the Account Exists path if an account matching the attributes retrieved from the social identity provider is found in the user data store; otherwise, evaluation continues along the No account exists path.

Properties

Property Usage

Client ID (required)

Specifies the client_id parameter as described in section 2.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Client Secret (required)

Specifies the client_secret parameter as described in section 2.3 of The OAuth 2.0 Authorization Framework (RFC 6749).

Authentication Endpoint URL (required)

Specifies the URL to the social provider’s endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework (RFC 6749).

Example: https://accounts.google.com/o/oauth2/v2/auth

Access Token Endpoint URL (required)

Specifies the URL to the endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Example: https://www.googleapis.com/oauth2/v4/token

User Profile Service URL (required)

Specifies the user profile URL that returns profile information.

Example: https://www.googleapis.com/oauth2/v3/userinfo

OAuth Scope (required)

Specifies a list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749).

Ensure you use the correct scope delimiter required by the identity provider, including commas or spaces.

The list depends on the permissions that the resource owner, such as the end user, grants to the client application.

Scope Delimiter (required)

Specifies the delimiter used to separate scope values.

Some authorization servers use non-standard separators for scopes, for example commas.

Redirect URL (required)

Specifies the URL the user is redirected to by the social identity provider after authenticating.

For authentication trees in AM, set this property to the URL of the UI. For example, https://openam.example.com:8443/openam/XUI/.

Social Provider (required)

Specifies the name of the social provider for which this module is being set up.

Example: Google

Auth ID Key (required)

Specifies the attribute the social identity provider uses to identify an authenticated individual.

Example: id

Use Basic Auth

Specifies that the client uses HTTP Basic authentication when authenticating to the social provider.

Default: true

Account Provider (required)

Specifies the name of the class that implements the account provider.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

Account Mapper (required)

Specifies the name of the class that implements the method of locating local accounts based on the attributes returned from the social identity provider.

Provided implementations are:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper

The Account Mapper classes can take two constructor parameters:

  1. A comma-separated list of attributes

  2. A prefix to apply to their values.

For example, to prefix all received property values with facebook- before searching, specify:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|facebook-

Attribute Mapper (required)

Specifies the list of fully qualified class names for implementations that map attributes from the OAuth 2.0 authorization server to AM profile attributes.

Provided implementations are:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper

The Attribute Mapper classes can take two constructor parameters to help differentiate between the providers:

  1. A comma-separated list of attributes

  2. A prefix to apply to their values.

For example, to prefix all incoming values with facebook-, specify:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|facebook-

To prefix all incoming values use an asterisk (*) as the attribute list. This prefixes all values, including email addresses, postal addresses, and so on.

Account Mapper Configuration

Specifies the attribute configuration used to map the account of the user authenticated in the OAuth 2.0 provider to the local data store in AM.

Valid values are in the form provider-attr=local-attr.

Examples:

email=mail
id=facebook-id

When using the org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper class, you can parse JSON objects in mappings using dot notation.

For example, given a JSON payload of:

{
  "sub" : "12345",
  "name" : {
    "first_name" : "Demo",
    "last_name" : "User"
  }
}

You can create a mapper, such as name.first_name=cn.

Attribute Mapper Configuration

Map of OAuth 2.0 provider user account attributes to local user profile attributes, with values in the form provider-attr=local-attr.

Examples:

first_name=givenname
last_name=sn
name=cn
email=mail
id=facebook-id
first_name=facebook-fname
last_name=facebook-lname
email=facebook-email

When using the org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper class, you can parse JSON objects in mappings using dot notation.

For example, given a JSON payload of:

{
  "sub" : "12345",
  "name" : {
    "first_name" : "Demo",
    "last_name" : "User"
  }
}

You can create a mapper, such as name.first_name=cn.

Save attributes in the session

When enabled, saves the attributes in the Attribute Mapper Configuration field to the AM session.

OAuth 2.0 Mix-Up Mitigation Enabled

Controls whether the OAuth 2.0 authentication node carries out additional verification steps when it receives the authorization code from the authorization server.

Specifies that the client must compare the issuer identifier of the authorization server upon registration with the issuer value returned as the iss response parameter. If they do not match, the client must abort the authorization process. The client must also confirm that the authorization server’s response is intended for the client by comparing the client’s client identifier to the value of the client_id response parameter.

When this is enabled, set the Token Issuer property so that the validation can succeed. The authorization code response contains an issuer value (iss) for the client to validate.

Refer to the authorization server’s documentation for the value it uses for the issuer field.

For more information, refer to section 4 of OAuth 2.0 Mix-Up Mitigation Draft.

Token Issuer

Corresponds to the expected issuer identifier value in the iss field of the ID token.

Example: https://accounts.google.com