37 OIDC Client Integrations with Social Identity Providers

OAM ships an out-of-the box OIDC Client Authentication Plugin, OpenIDConnectPlugin that enables integration with Social Identity providers such as IDCS, Google and Facebook.

Apart from being an OAuth/OpenIDConnect2.0 Server, Oracle Access Manager (OAM) can also delegate authentication to OpenIDConnect-Social Identity Providers such as IDCS, Google, Facebook or even OAM itself, thus behaving like a relying party (service provider). After authenticating the user, the IDP redirects back to OAM where the user is asserted by OAM and an OAM Session is created.

The authentication process is described as follows:

1. The OpenIDConnectPlugin redirects the authentication request to any third-party Identity Provider using OIDC protocol.

2. The third-party Identity Provider (IDP) authenticates the user.

3. The IDP redirects the authentication request back to OAM.

4. The OAM asserts the user.

5. The OAM creates a session.

Description of the illustration aiaag_oidc_authentication_flow.png

37.1 About the OpenIDConnectPlugin

OpenIDConnectPlugin is a generic plugin that you can integrate with any OpenId2.0 providers. This plugin redirects requests to the IDP it is integrated with. After authenticating the user at the IDP, the control is submitted back to the OAM server

The following figure shows all the configuration parameters and expected values:

Description of the illustration aiaag_oidc_openidconnectplugin.png

The mandatory parameters for plugin configuration include oauth_client_id, oauth_client_secret, and provider.

Table 37-1 OpenIDConnectPlugin: Parameters for plugin configuration

Field	Sample Value	Mandatory / Optional	Description
id_domain		Optional	Enter the Identity domain. It is required for integration with OAM as an IDP since all the artifacts (client) are created under the Identity Domain in OAM.
oauth_client_secret	12312312312asdasdasd1231231sdsadasd	Mandatory	Enter OAuth client secret.
token_end_point	https://graph.facebook.com/v2.11/oauth/access_token	Optional	Enter the access token endpoint, it is required ONLY if the IDP does not support Discovery URL.
authz_end_point	https://www.facebook.com/v2.11/dialog/oauth	Optional	Enter the authorization endpoint, (required ONLY if the IDP does not support Discovery URL)
require_proxy		Optional	Set it to false, if the plugin does not use the proxy configuration and redirects directly to the IDP. Note: If proxy is required to connect to the IDP, add this setting before starting the server: Dhttp.proxy.Host=www-proxy.example.com -Dhttp.proxy.Port=80
provider	Facebook or oam or idcs	Mandatory	For this patch release, use only Facebook or oam or idcs as provider values for the following reasons: Facebook does not comply to OpenID2.0 specifications For OAM and IDCS, the default email attribute is not supported, must read the sub from the token for this provider. Note: For other OpenID2.0 compliant providers such as google, you can use any key.
scope		Optional	The default “scope” sent to the IDP is openid email. If this has to be overwritten, we can set the new scope via this plugin parameter.
additional_parameters			This is not used as of now. It can be left blank
userinfo_end_point	https://graph.facebook.com/me	Optional	Enter the userinfo token endpoint, it is required ONLY if the IDP does not support Discovery URL.
discovery_url	https://accounts.google.com	Mandatory	Enter the discovery URL at the IDP-end with the format, http(s)://URL host. It provides authorization, token, and userinfo endpoints information. The base URL, /.well-known/openid-configuration is appended to the discover URL for building the expected format of http(s)://URL host/.well-known/openid-configuration. The plugin fetches authorization, token and userinfo endpoints from this discovery URL and redirects to the same.
username_attr			This parameter indicates, which attribute should be read from the Identity Token. provider Username_attr value Reason Facebook name Sends the display name of the user via “name” attribute. E.g.: {“name” : “John Doe”} Google email Sends the email of the user via “email” attribute. E.g.: {“email” : “[e-mail]”} IDCS sub Sends the email of the user via “sub” attribute. E.g.: {“sub” : “[e-mail]”}
oauth_client_id	asdad11sdfasda131231asdas	Mandatory	Enter OAuth client id.

There is no dependency between the provider and the expected key value. The new plugin parameter, username_attr indicates the attribute to be read from the Identity Token.

Note:

Add DUseSunHttpHandler=true before starting the server. When it is set to true, the plugin connects to the external IDP through the backchannel and fetches token and userinfo details.

37.2 Authentication Module and Scheme and Policy Changes

Create a new authentication module that consists of two steps:

• OpenIDConnectPlugin

• UserIdentificationPlugin

Description of the illustration aiaag_oidc_authmod_steps.png
Description of the illustration aiaag_oidc_authmod_stepsorch.png

UserIdentificationPlugin is required as the second Step. Before the OAM session creation, the user authenticated by the IDP needs to be asserted by OAM. The User Attribute returned in the Identity Token varies for providers. The user attribute could be subject which is the uid or displayname or email attribute.

In OAM, assert this user in the IDStore by modifying the KEY_LDAP_FILTER as described in the following table:

Assumption: The user authenticated at IDP must exist in the OAM–ID Store.

Description of the illustration aiaag_oidc_authmod_stepdetails.png

Table 37-2 UserIdentificationPlugin: Parameters to modify filters

Provider	User Attribute returned by OpenIDConnectPlugin	Filter
Facebook	Sub returns displayname	&(objectclass=inetorgperson)(DISPLAYNAME={KEY_USERNAME}) It indicates that the LDAP search needs to be performed for a user with the given displayname.
OAM	Sub which returns uid, the default attribute configured	Default email attribute is not supported.
IDCS	Sub returns email	&(objectclass=inetorgperson)(MAIL={KEY_USERNAME})
Google	Email returns email	&(objectclass=inetorgperson)(MAIL={KEY_USERNAME})

37.3 Authentication Scheme Changes

Create a new Authentication scheme that uses the module created in the previous section

For this new Authentication scheme, set the challenge parameter initial_command=NONE so that the control is passed to the plugin

Description of the illustration aiaag_oidc_authscheme_fbscheme.png

37.4 Policy Changes

Modify the authentication policy in the application domain of the protected resource to use the scheme created in Authentication Scheme Changes. When you access a protected-resource, the control is given to this module. The OpenIDConnectPlugin redirects to the IDP endpoint. After authenticating at the IDP, when control is submitted back to the server, the UserIdentificationplugin asserts the user and the session are created in OAM.

37.5 Integration with IDCS

OAM ships an out-of-the box OIDC Client Authentication Plugin, OpenIDConnectPlugin that enables integration with Social Identity providers such as IDCS, Google and Facebook. Apart from being an OAuth/OpenIDConnect2.0 Server, Oracle Access Manager (OAM) can also delegate authentication to OpenIDConnect-Social Identity Providers such as IDCS, Google, Facebook or even OAM itself, thus behaving like a relying party (service provider). After authenticating the user, the IDP redirects back to OAM where the user is asserted by OAM and an OAM Session is created.

1. Create a client on the IDCS site.
   Description of the illustration aiaag_oidc_integr_idcs_1.png

   Note:

   While creating the client, ensure to check Authorization Code grant type. The redirect_uri for the client needs to be the end point on the OAM server where credentials are submitted eg: http(s)://OAMServer LBR Host:port/oam/server/auth_cred_submit.
2. Create a new application under Applications.
3. Make a note of the client_id and client_secret.
   Description of the illustration aiaag_oidc_integr_idcs_2.png
4. Set the following configuration parameters for OpenIDConnectPlugin:
   Description of the illustration aiaag_oidc_integr_idcs_3.png

   Note:

   The discovery URL needs to be provided only with the host and port information. The plug-in takes care of appending /.well-known/openid-configuration to form the complete URL.
5. Verify that the user exists in the IDStore in OAM.
   Description of the illustration aiaag_oidc_integr_idcs_4.png
6. Access the protected-resource.
7. Get redirected to the IDCS login page for authentication.

37.6 Integration with Google

OAM ships an out-of-the box OIDC Client Authentication Plugin, OpenIDConnectPlugin that enables integration with Social Identity providers such as IDCS, Google and Facebook. Apart from being an OAuth/OpenIDConnect2.0 Server, Oracle Access Manager (OAM) can also delegate authentication to OpenIDConnect-Social Identity Providers such as IDCS, Google, Facebook or even OAM itself, thus behaving like a relying party (service provider). After authenticating the user, the IDP redirects back to OAM where the user is asserted by OAM and an OAM Session is created.

1. Create a client on console.developers.google.com as shown in the following figure:
2. Make a note of the client_id and client_secret.
3. Provide endpoint on the OAM server as redirect_uri for the client. Credentials are submitted at this endpoint, for example http(s)://OAM Host:port/oam/server/auth_cred_submit.
   Description of the illustration aiaag_oidc_integr_google_1.png
4. Set the following configuration parameters for OpenIDConnectPlugin:
   Description of the illustration aiaag_oidc_integr_google_2.png
5. Verify that the user exists in the IDStore in OAM.
   Description of the illustration aiaag_oidc_integr_google_3.png
6. Access the protected-resource.
7. Get redirected to the Google login page for authentication.

37.7 Integration with Facebook

OAM ships an out-of-the box OIDC Client Authentication Plugin, OpenIDConnectPlugin that enables integration with Social Identity providers such as IDCS, Google and Facebook. Apart from being an OAuth/OpenIDConnect2.0 Server, Oracle Access Manager (OAM) can also delegate authentication to OpenIDConnect-Social Identity Providers such as IDCS, Google, Facebook or even OAM itself, thus behaving like a relying party (service provider). After authenticating the user, the IDP redirects back to OAM where the user is asserted by OAM and an OAM Session is created.

1. Create a client on developers.facebook.com as shown in the following figure:
   Description of the illustration ms_oamathn_sp.gif
2. Make a note of the client_id and client_secret.
   Description of the illustration aiaag_oidc_integr_fb_2.png
3. Provide endpoint on the OAM server as redirect_uri for the client. Credentials are submitted at this endpoint, for example http(s)://OAM Host:port/oam/server/auth_cred_submit.
   Description of the illustration aiaag_oidc_integr_fb_3.png
4. Set the following configuration parameters for OpenIDConnectPlugin:
   Description of the illustration aiaag_oidc_integr_fb_4.png
5. Verify that the user exists in the IDStore in OAM.
   Description of the illustration aiaag_oidc_integr_fb_5.png
6. Access the protected-resource.
7. Get redirected to the Facebook login page for authentication.