2.2.16. Hints For the OAuth 2.0 Authentication Module

The OAuth 2.0 authentication module lets OpenAM authenticate clients of OAuth resource servers. References in this section are to RFC 6749, The OAuth 2.0 Authorization Framework.

[Note] Note

The default settings are for Facebook.

ssoadm service name: sunAMAuthOAuthService

Client ID

OAuth client_id as described in section 2.2 of RFC 6749.

ssoadm attribute: iplanet-am-auth-oauth-client-id

Client Secret

OAuth client_secret as described in section 2.3 of RFC 6749.

ssoadm attribute: iplanet-am-auth-oauth-client-secret

Authentication Endpoint URL

URL to the end point handling OAuth authentication as described in section 3.1 of RFC 6749. The default value is https://www.facebook.com/dialog/oauth.

ssoadm attribute: iplanet-am-auth-oauth-auth-service

Access Token Endpoint URL

URL to the end point handling access tokens as described in section 3.2 of RFC 6749. The default value is https://graph.facebook.com/oauth/access_token.

ssoadm attribute: iplanet-am-auth-oauth-token-service

User Profile Service URL

User profile URL that returns profile information in JSON format. The default value is https://graph.facebook.com/me.

ssoadm attribute: iplanet-am-auth-oauth-user-profile-service

Scope

Comma separated list of user profile attributes that the application requires. The default value is email,read_stream.

ssoadm attribute: iplanet-am-auth-oauth-scope

Proxy URL

URL to the /oauth2c/OAuthProxy.jsp file, part of OpenAM.

ssoadm attribute: iplanet-am-auth-oauth-sso-proxy-url

Account Mapper

Class implementing account mapping. The default value is org.forgerock.openam.authentication.modules.oauth2.DefaultAccountMapper.

ssoadm attribute: org-forgerock-auth-oauth-account-mapper

Account Mapper Configuration

Map of OAuth Provider user account attributes used to find the local profile of the authenticated user, with values in the form provider-attr=local-attr. Default values email=mail and id=facebook-id.

ssoadm attribute: org-forgerock-auth-oauth-account-mapper-configuration

Attribute Mapper

Class implementing attribute mapping. Default: org.forgerock.openam.authentication.modules.oauth2.DefaultAttributeMapper

ssoadm attribute: org-forgerock-auth-oauth-attribute-mapper

Attribute Mapper Configuration

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

ssoadm attribute: org-forgerock-auth-oauth-attribute-mapper-configuration

Save attributes in the session

When enabled, add the mapped attributes to the session saved. The default mode is Enabled.

ssoadm attribute: org-forgerock-auth-oauth-save-attributes-to-session-flag

Email attribute in OAuth2 Response

Specifies the attribute identifying email address in the response from the profile service in the OAuth provider. This setting is used to send an email address with an activation code for accounts created dynamically.

ssoadm attribute: org-forgerock-auth-oauth-mail-attribute

Create account if it does not exist

When enabled, if the user profile does not exist, optionally retrieve a password and activation code from the user, and then create the profile. The default mode is Enabled.

When the OAuth 2.0 client is configured to create new accounts, the SMTP settings must also be valid. As part of account creation, the OAuth 2.0 client authentication module sends the resource owner an email with an account activation code. To send the mail, OpenAM uses the SMTP settings you provide here in the OAuth 2.0 client configuration.

ssoadm attribute: org-forgerock-auth-oauth-createaccount-flag

Prompt for password setting and activation code

When enabled, the user sets a password, receives an activation code by email. The user must correctly set both in order for the account to be created. The default mode is Enabled.

ssoadm attribute: org-forgerock-auth-oauth-prompt-password-flag

Map to anonymous user

When enabled, map the OAuth authenticated user to the anonymous user you specify. No account is created, even if Create account if it does not exist is enabled.

ssoadm attribute: org-forgerock-auth-oauth-map-to-anonymous-flag

Anonymous User

Specifies an anonymous user that exists in the current realm. The default is anonymous.

ssoadm attribute: org-forgerock-auth-oauth-anonymous-user

OAuth 2.0 Provider logout service

Specifies the optional URL of the OAuth Provider.

ssoadm attribute: org-forgerock-auth-oauth-logout-service-url

Logout options

Specifies whether not to log the user out without prompting from the OAuth Provider on logout, to log the user out without prompting, or to prompt the user regarding whether to logout from the OAuth provider.

ssoadm attribute: org-forgerock-auth-oauth-logout-behaviour

Mail Server Gateway implementation class

Class to interact with the mail server. Default: org.forgerock. openam.authentication.modules.oauth2.DefaultEmailGatewayImpl

ssoadm attribute: org-forgerock-auth-oauth-email-gwy-impl

SMTP host

Host name of the mail server. The default is localhost.

ssoadm attribute: org-forgerock-auth-oauth-smtp-hostname

SMTP port

SMTP port number for the mail server. The default value is 25.

ssoadm attribute: org-forgerock-auth-oauth-smtp-port

SMTP User Name

If the mail server requires authentication to send mail, specifies the user name.

ssoadm attribute: org-forgerock-auth-oauth-smtp-username

SMTP User Password

If the mail server requires authentication to send mail, specifies the password.

ssoadm attribute: org-forgerock-auth-oauth-smtp-password

SMTP SSL Enabled

When enabled, connect to the mail server over SSL. OpenAM must be able to trust the SMTP server certificate.

ssoadm attribute: org-forgerock-auth-oauth-smtp-ssl_enabled

SMTP From address

Specifies the message sender address, such as no-reply@example.com. The default value is info@forgerock.com.

ssoadm attribute: org-forgerock-auth-oauth-smtp-email-from

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: iplanet-am-auth-oauth-auth-level

The following tables show endpoint URLs for OpenAM when configured as an OAuth 2.0 provider, and also URLs for large OAuth 2.0 providers. The default endpoints are for Facebook as the OAuth 2.0 provider.

In addition to the endpoint URLs you can set other fields, like scope and attribute mapping, depending on the provider you use.

Table 2.1. Endpoint URLs for OpenAM

OpenAM Field Details
Authentication Endpoint URL

/oauth2/authorize under the deployment URL.[a]

Example: https://openam.example.com:8443/openam/oauth2/authorize.

Access Token Endpoint URL

/oauth2/access_token under the deployment URL.[a]

Example: https://openam.example.com:8443/openam/oauth2/access_token.

User Profile Service URL

/oauth2/tokeninfo under the deployment URL.

Example: https://openam.example.com:8443/openam/oauth2/tokeninfo.

[a] This OpenAM endpoint can take additional parameters. In particular you must specify the realm if the OpenAM OAuth 2.0 provider is configured for a subrealm rather than / (Top-Level Realm).

For example, if the OAuth 2.0 provider is configured for the realm /customers, then the authentication endpoint URL is as follows: https://openam.example.com:8443/openam/oauth2/authorize?realm=/customers

The /oauth2/authorize endpoint can also take module and service parameters. Use either as described in Authenticating To OpenAM, where module specifies the authentication module instance to use or service specifies the authentication chain to use when authenticating the resource owner.


Table 2.2. Endpoint URLs for Facebook

OpenAM Field Details
Authentication Endpoint URL https://www.facebook.com/dialog/oauth
Access Token Endpoint URL https://graph.facebook.com/oauth/access_token
User Profile Service URL https://graph.facebook.com/me
OAuth 2.0 Provider logout service http://www.facebook.com/logout.php

Table 2.3. Endpoint URLs for Google

OpenAM Field Details
Authentication Endpoint URL https://accounts.google.com/o/oauth2/auth
Access Token Endpoint URL https://accounts.google.com/o/oauth2/token
User Profile Service URL https://www.googleapis.com/oauth2/v1/userinfo
OAuth 2.0 Provider logout service https://mail.google.com/mail/?logout

Table 2.4. Endpoint URLs for MSN

OpenAM Field Details
Authentication Endpoint URL https://oauth.live.com/authorize
Access Token Endpoint URL https://oauth.live.com/token
User Profile Service URL https://apis.live.net/v5.0/me
OAuth 2.0 Provider logout service http://oauth.live.com/logout