A Beginner's HowTo on Social Federation with OAM Mobile & Social

Introduction

Social Federation: a somewhat fancy name for a simple concept. We want to leverage identities in Social Network providers in our own applications. For example, granting access to either cloud or on-premise applications to end users using their Google identities. In this post we're going to take a close look at the necessary configuration in OAM M&S (Oracle Access Manager Mobile & Social) server to have Java Web applications leveraging Google and LinkedIn identities.

Conceptually, this is very similar to SAML-based federation model indeed. The difference is that we are now dealing with different protocols, like OpenID and OAuth. And the main appeal for federation keeps being the acceptance of third party identities by a service provider (a.k.a. relying party) without the need of having end user passwords stored locally.


For SAML-based federation, just search for SAML in our blog. I've posted quite some articles on the topic.

OAM M&S works both as an identity provider or as a service provider. In the former case, it works as the entity providing authenticated tokens to interested parties. In the later, it is the entity consuming authenticated tokens generated by some other identity provider. In the use case we have in mind for this post, OAM M&S is the service provider. At the end of the day, we want to provide access to a java servlet hosted in Weblogic server accessed through OHS (Oracle HTTP Server).
Leaving federation out for a moment, in the typical OAM use case, OAM generates a token based on username/password entered by the end user. The user credentials are validated against OAM backend user store.

With federation, the user is authenticated by the remote identity provider. Following that, OAM generates a token based on the token sent by the remote identity provider.
That means, from the viewpoints of the servlet application and Weblogic server hosting the servlet, with federation, there are no extra requirements than those already known for the typical OAM use case: CLIENT-CERT authentication method in web.xml and OAM Identity Asserter in the Weblogic security realm.

The following is the step-by-step configuration to implement the same use case you see here in the M&S documentation.

For your convenience, here's the sequence diagram:

Authentication Flow Sequence Diagram

OAM M&S Configuration

 

1 - OICScheme Authentication Scheme

In the Application Policy Domain, define OICScheme as the Authentication Policy authentication scheme for the protected resource.

OICScheme in Authentication Policy

OICScheme

Special mention to MatchLDAPAttribute=uid Challenge Parameter. It means the LDAP uid attribute is used for finding the user in OAM's user store. Yes, in the case where M&S is integrated with Access Manager, a shadow user entry is created for every federated user (password attribute is optional). Therefore, watch the populated attributes once user attributes are mapped. More on this later when we talk about the necessary mappings for each identity provider.

2 - M&S Application Profile Definition

Under Social Identity, create an Application Profile with the same name as your Application Policy Domain (HQ_Apps, in my case). Use the OOTB OAMApplication profile as a template.

Social Identity Main Screen

The Application Profile screen defines attribute mappings between the Application User and the Registration Service as well as between the Application User and the Identity Provider. It also defines, among other things, the properties controlling how the login screen is presented and whether user registration should be skipped (not applicable when M&S is integrated with Access Manager).

With regarding to profile properties, observe the screen shot below:

HQ_Apps Application Profile Properties

Notice the UserID Attribute. It's used by M&S to uniquely identify users and must be defined in the Application User Attribute list.

As for the mappings, observe the 3 sections in my sample HQ_Apps Application Profile below:

HQ_Apps Application Profile Mappings

Application User Attribute section lists the attributes to be handled by the profile. You can list any attribute, as long as it gets properly mapped in the subsequent sections. These attributes are the link between the Social Identity provider and the local backend user store.

Registration Service Detail with Application User Attribute Mapping section defines the fields that are going to show up in the Registration form once the authentication flow gets back to M&S after successful authentication by the Identity Provider.

Notice the uid attribute in the Registration Service Details. This is how we populate it in local backend identity store for further lookup by OAM's OICScheme.

An important and related aspect for integrating with Java web applications running on Weblogic server is how we configure the LDAP authenticator. Remember: the OAM Identity Asserter in Weblogic makes use of an authenticator when asserting the user identity for the container. Specifically, special attention to the User Name Attribute. The value pointed by it must match whatever value is propagated to Weblogic (usually done via OAM_REMOTE_USER or OAM_IDENTITY ASSERTION HTTP headers).

OID Authenticator in Weblogic

Application User Attribute and Internet Identity Provider User Attributes Mapping is self-describing and it is done per Identity Provider. The displayed mapping is for Google_OAuth2 provider. The Internet Identity Provider User Attributes need to first be defined in the provider. Check section 3.1 below.

3 - Social Identity Providers Configuration

Google supports OpenID (Google has deprecated OpenID 2.0 and is now supporting OpenID Connect)  while LinkedIn uses OAuth.

3.1 - Configuring Google OpenID Connect

OpenID Connect is an identity layer on top of OAuth 2.0. It's an API friendly protocol for verifying end user identity and obtaining basic profile information about the end user.

As of M&S 11.1.2.2, there's no OOTB (Out Of The Box) Provider for Google with OpenID Connect. So we need to create one from scratch. The screenshot below shows my sample setup. All fields except Name, Description, Icon Path, Consumer Key and Consumer Secret must be informed as is. Notice the Protocol is OAuth.

Google OpenID Connect Configuration

Couple of important observations:

1 - Consumer Key and Consumer Secret are obtained from Google's Developer Console.

Follow this document for creating the necessary OAuth 2.0 footprint in Google.

When creating the Client ID and Client Secret in Google's Developers Console, make sure the Authorized Redirect Endpoint gets set to http://<oam-server>:<oam-port>/oic_rp/return, like in the following screenshot. It is used to send the OAuth token back to M&S server.

Client ID Creation in Google Developers Console

When configuring Google's Consent Screen in Google's Developers Console, make sure the PRODUCT NAME matches the Application Profile name in M&S:

Google Consent Screen

2 - Notice Google URLs. They are all HTTPS.

Take a look at the SSL Advanced properties in OAM managed server. The OOTB Hostname Verifier (BEA Hostname Verifier) doesn't support wildcards in the certificate CN it receives from the other end, which is what Google may send back during the handshake. This will get you an error like the one below and will prevent the federation flow to complete.

####<Oct 13, 2014 1:09:23 PM PDT> <Warning> <Security> <slc05ylp.us.oracle.com> <oam_server1> <[ACTIVE] ExecuteThread: '0' for queue: 'weblogic.kernel.Default (self-tuning)'> <<anonymous>> <> <6af0f0aa917fd32e:-103bce24:1490b1effb4:-8000-00000000000000f1> <1413230963819> <BEA-090504> <Certificate chain received from www-proxy.us.oracle.com - 148.87.19.20 --> www.googleapis.com failed hostname verification check. Certificate contained *.googleapis.com but check expected www.googleapis.com>

Fortunately, Weblogic ships a Custom Hostname Verifier that supports wildcards, named weblogic.security.utils.SSLWLSWildcardHostnameVerifier.

Change the OAM server SSL Advanced settings using values below and restart the server.
Hostname Verification: "Custom Hostname Verifier"

Custom Hostname Verifier: weblogic.security.utils.SSLWLSWildcardHostnameVerifier

WLS SSL Settings

 Following our Google_OAuth2 provider configuration in OAM Console, the attributes to be returned by the provider are defined as:

Google OAuth Attributes

3.2 - Configuring LinkedIn OAuth

For LinkedIn (as for Google and any OAuth provider), it is necessary to first register our client in LinkedIn for obtaining a consumer key and secret. The steps are described here.

Upon successful registration, LinkedIn outputs something like:

Client Registration in LinkedIn

 Copy API Key and Secret Key values above and paste them into LinkedIn's Consumer Key and Consumer Secret fields in the M&S LinkedIn provider, as shown below:

LinkedIn Profile in M&S

In my experience, LinkedIn doesn't use wildcards in their certificate. At least, Weblogic doesn't complain.

Testing

With this configuration in place, we're now ready for testing. When accessing the protected resource, OAM Web Gate would present us a login screen like:

Social Login Screen

Upon choosing any of the Identity Providers links, the browser gets redirected and the user is prompted for authentication by the Social Network identity provider. In the case of LinkedIn, for instance:

LinkedIn OAuth Authentication

If this is the first time access, a registration form is presented and it must be filled in, or login fails. Notice how the form mirrors the attribute mappings in the Registration Service Details with Application User Attribute Mappings showed previously.

LinkedIn User Registration in M&S

Upon successful registration, the user entry is created in the backend local user store, a session is created in OAM and the browser is redirected to the originally requested resource.

In subsequent accesses, the user registration step is skipped.

Here's OAM session entry based on LInkedIn's federated identity displayed in OAM Console:

OAM User Session

I hope this is useful for people out there starting with Social Federation with OAM M&S. Time allowing, I will come back with more advanced use cases on the topic.