1. Administering Oracle Access Management
  2. Managing the Oracle Access Management OAuth Service and OpenIDConnect
  3. OIDC Client Integrations with Social Identity Providers

41 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 aiaag_oidc_authentication_flow.png follows
Description of the illustration aiaag_oidc_authentication_flow.png

41.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 mandatory parameters for plugin configuration include oauth_client_id, oauth_client_secret, and provider.

Table 41-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

 attributes=profile,email;protocol=http;namespace=oidc Optional
Specify the following additional attributes and values. Use semicolon (;) to delimit the attributes and comma (,) to delimt the values.
  • attributes = profile, email
  • protocol=http
  • namespace=oidc

Note:

By default, https is used if the protocol is not specified.

userinfo_end_point

http://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” : “John.Doe@gmail.com”}

IDCS

sub

Sends the email of the user via “sub” attribute.

E.g.: {“sub” : “John.Doe@oracle.com”}

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.

41.2 Authentication Module and Scheme and Policy Changes

Create a new authentication module that consists of two steps:

  • OpenIDConnectPlugin

  • UserIdentificationPlugin

Description of aiaag_oidc_authmod_steps.png follows
Description of the illustration aiaag_oidc_authmod_steps.pngDescription of aiaag_oidc_authmod_stepsorch.png follows
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 aiaag_oidc_authmod_stepdetails.png follows
Description of the illustration aiaag_oidc_authmod_stepdetails.png

Table 41-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})

41.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 aiaag_oidc_authscheme_fbscheme.png follows
Description of the illustration aiaag_oidc_authscheme_fbscheme.png

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

41.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 aiaag_oidc_integr_idcs_1.png follows
    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 aiaag_oidc_integr_idcs_2.png follows
    Description of the illustration aiaag_oidc_integr_idcs_2.png
  4. Set the following configuration parameters for OpenIDConnectPlugin: Description of aiaag_oidc_integr_idcs_3.png follows
    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 aiaag_oidc_integr_idcs_4.png follows
    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.

41.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 aiaag_oidc_integr_google_1.png follows
    Description of the illustration aiaag_oidc_integr_google_1.png
  4. Set the following configuration parameters for OpenIDConnectPlugin:Description of aiaag_oidc_integr_google_2.png follows
    Description of the illustration aiaag_oidc_integr_google_2.png
  5. Verify that the user exists in the IDStore in OAM. Description of aiaag_oidc_integr_google_3.png follows
    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.

41.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 ms_oamathn_sp.gif follows
    Description of the illustration ms_oamathn_sp.gif
  2. Make a note of the client_id and client_secret.Description of aiaag_oidc_integr_fb_2.png follows
    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 aiaag_oidc_integr_fb_3.png follows
    Description of the illustration aiaag_oidc_integr_fb_3.png
  4. Set the following configuration parameters for OpenIDConnectPlugin:Description of aiaag_oidc_integr_fb_4.png follows
    Description of the illustration aiaag_oidc_integr_fb_4.png
  5. Verify that the user exists in the IDStore in OAM. Description of aiaag_oidc_integr_fb_5.png follows
    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.