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.

Multiple Identity Providers with Oracle Identity Federation and Access Manager as Service Provider

Whew, that’s a mouthful for a title, but IdP N..1 SP [OIF+OAM] was probably too cryptic. Let me describe the use-case in a little more detail. Imagine if you will an education application that the state wants to surface to the various school districts. The districts want to manage user accounts and federate into the state’s application. In order to consolidate policy enforcement for both internal and external users, the state needs a single point of entry controlled by an access control system.

The documentation for Oracle Access Manager (OAM) and Oracle Identity Federation (OIF) integration on the service provider (SP) (http://docs.oracle.com/cd/E21764_01/doc.1111/e15740/oif.htm#CACJDDGE) implies that this can only be done with a single identity provider (IdP). By setting OIFScheme as the authentication scheme for the application, OAM can redirect to the service provider on OIF, which will trigger an SP-initiated Single Sign-On (SSO). There is no way to declare which IdP to use in this scenario, however. Thus, a different trigger mechanism is required for the multiple IdP scenario, plus we need to account for internal state users as well. One approach is to leverage OAM form authentication with hyperlinks to an IdP discovery page, or static links to each campus trigger for SP-initiated SSO. The format in OIF for this is http(s)://<oif>: <oif_port>/fed/sp/initiatesso?providerid=CAMPUS1&returnurl=<URL of destination app>. Once the IdP sends its SAML Response to the OIF service provider, OIF will make authentication & authorization request to OAM Policy Decision Point (PDP) based on the returnurl parameter. If successful, OIF will redirect client to the destination application with a token that the OAM Policy Enforcement Point (PEP) will honor.

One gotcha here is that the returnurl must be protected by the OIFScheme, not the form-based scheme used for internal users. That creates a challenge in that you essentially need two protected URLs for entry into the app, one to trigger the initial form authentication and one to map the external/federated users. If having all external users end up at the same portal site after authentication is acceptable, one can map the OIFScheme to a pseudoURL. You can then configure an OnAuthenticationSuccess redirect to the landing page. This pattern is only suitable if all external users come to the same page upon successful federation. I tried basing the federation policy on a query parameter, i.e. returnurl=/mysite?external=true, but OAM did not seem evaluate the query parameter, only the application context.

Another hitch is that I don’t think a 10g WebGate can consume the identity token set by the service provider. I haven’t tested to validate, but I suspect that only the 11g WebGate can consume the OAM_ID cookie. Thus, if you have a mixed environment, you will need an OHS 11g instance to handle external user traffic, while redirecting to other web servers only after an authentication cookie has been set.

Provisioning Users to Google Apps in Five Minutes

One exciting development (at least to me) in OIM 11.1.1.5 is the introduction of the Google Apps connector. Combine this with our existing SSO via Federation, it gives Oracle a nice lifecycle with Google Apps. Here is a quick primer on setting this up and a couple of gotchas on the docs. I wrote this a couple of months ago before the official announcement of the connector, so please correct me if there are any changes since.

There are a few 3^rd party libraries from Google required for the connector. It appears that Google has updated its libraries already from what we’ve published in the doc. If you hit the problem described in http://code.google.com/p/googleappengine/issues/detail?id=3008, you probably have a “too current” version of the Google jars.

Here’s the documentation gotcha: In section 2.2.2, there is a note that states:

“Before you run the Connector Installer, you must ensure that all third party jars must be in targetsystems-lib/googleapps-11.1.1.5.0.”

The point that is intended here is that the folder structure must match the structure of the connector that is deployed. The distribution is “Google_Apps_11.1.1.5.0”, so if you take the docs literally and don’t change the name, things won’t line up. What is happening is that OIM is packaging the necessary 3^rd party jars and importing them into the database. It’s important to get this right before installing the connector, or you get to go through a process of removing the jar from the database with scripts, repackaging, and re-importing.

Another confusing point is that the doc references the Java Connector Server. This might be a forthcoming solution, but for the time being, you can just substitute the OIM server anywhere it references the JCS. (This article didn’t have enough three letter acronyms (TLAs)).

Bottom line, what I think the packaging should be before the connector is deployed :

/Oracle_IAM1/server/ConnectorDefaultDirectory/Google_Apps_11.1.1.5.0/

/Oracle_IAM1/server/ConnectorDefaultDirectory/targetsystems-lib/Google_Apps_11.1.1.5.0/<3^rd party jars>

/Oracle_IAM1/server/lib/<3^rd party jars>

Deploying the connector from that point is standard fare. Here’s how I configured my IT Resource:

Once I assigned a resource and provisioned it, the user appeared in Google apps and I was able to SSO with that user via OIF immediately. I was also able to de-provision the user from Google by removing the resource entitlement from the user.

Virtual Users in OIF, Weblogic and OWSM

One of the main strengths of SAML is the ability to communicate identity information across security domains that do not necessarily share the same user base. In other words, the authenticated user in one security domain does not necessarily exist in the target security domain providing the service.

Such concept is supported in all major Oracle products that consume SAML tokens: OIF, Weblogic Server and OWSM. The sole purpose of this post is to show how to configure it in these products. Setting up SAML services as a whole involves more than what’s showed here and I recommend the official product documentation for detailed steps.

I hope this can be helpful to someone out there.

OIF (Oracle Identity Federation)

OIF enables federated single sign on for users behind a web browser.

It calls the aforementioned concept “Transient Federation” and enables it via a checkbox (that should be unchecked) in Enterprise Manager OIF’s Console. Notice it also supports the concept of a "Mapped Federation", where the incoming identity is mapped to some generic user in the local identity store. But here I am talking about the case where there's no mapping. The user in the SAML assertion is simply trusted.

In order to enable a Transient Federation in OIF, simply make sure “Map Assertion to User Account” checkbox is unchecked in the Service Provider Common tab.

Weblogic Server

Weblogic server provides SAML services that can be leveraged by Web SSO as well web services.
Weblogic calls the concept Virtual Users and implements it in its SAML2IdentityAsserter along with the SAMLAuthenticator.

First, you need to enable your server as a SAML Service Provider. Notice this is done at the server level. Go to Environment –> servers –> <Pick server from list> to get into the screen below:



Then add a SAML2IdentityAsserter to the authentication providers list and add an Identity Provider (who does not need to be another Weblogic server) Partner to SAML2IdentityAsserter. Notice that you can add either a Web SSO partner provider or a Web service partner provider. In the case of Web SSO, Weblogic Console will ask you for the partner metadata file.