Tuesday, November 24, 2015

Most of my customers build their own User Self-Service module. That includes Change Password and Forget Password. And most of the times, they interact with the backend data source (e.g OpenDJ or Active Directory) directly.

I seldom have to worry about enabling the Forget Password feature in OpenAM. Well, good time is up for me. :) I have a customer that wants to utilize the Forget Password in OpenAM 12.

Well, so based on my past exploration with OpenAM Password Reset feature, our discussion revolved around Challenge Questions & Answers and how the flow will be. Note that this customer only wanted the new XUI. No way to use legacy UI as discovery and customization times have been invested into rebranding the XUI.

Today, I had a shock when I started to read more about the Forget Password feature in OpenAM 12. The more I read, the more confused I become. The documentation keeps talking about Resetting Forgotten Passwords (legacy).

OpenAM can provide self-service password reset for forgotten passwords when end user pages are served by the classic UI. To enable self-service password reset, you must configure the password reset service itself, which consists mainly of setting up secret questions, and configuring an SMTP mail server to send reset passwords to the users of the service.

But Mr Customer wants nothing, but the new XUI.

Now, during XUI rebranding, I did come across the following scripts in one of the template files.

There is definitely something to configure via the OpenAM Administration console to make the Forget Password hyperlink appears in XUI.

So I searched around and reached Configuration > Global > User Self Service. There you are! The Forgot Password for Users is disabled by default.

So I went ahead to enable the feature. Another great feature out there is the Forgot Password Token LifeTime (seconds). This expires the hyperlink which is sent to users. (Will talk about this in a while ...)

Nice, the Forgot password hyperlink finally appears!

The next screen is what you'll see when the Forgot password hyperlink is clicked.

When a correct username (default is to match with UID) is entered, an email will be sent.

The user will receive an email like the following:

This is where the Forgot Password Token LifeTime (seconds) kicks in. I suppose the hyperlink in the email will expires in the configured time. (I'll need to fully test this function. Still at high-level investigation now)

Once the hyperlink is clicked, the user will be redirected to the Change forgotten password page.

Pretty cool right? Initially I thought Mr Customer would reject it because the long-discussed Challenge Questions & Answers feature is no longer available in the new XUI. But, to my surprise, he prefers this new feature, especially the Forgot Password Token LifeTime.

And what surprised me more?

This new feature is not mentioned at all in OpenAM documentation, not in stable release. And I just searched the draft documentation for OpenAM 13, it's not mentioned as well. Maybe it's hidden somewhere, but it's really not obvious to customers and integrators like us.

SLF4J: Class path contains multiple SLF4J bindings.SLF4J: Found binding in [jar:file:/data/opt/apache-tomcat-8.0.26/webapps/auth/WEB-INF/lib/openam-slf4j-12.0.2.jar!/org/slf4j/impl/StaticLoggerBinder.class]SLF4J: Found binding in [jar:file:/data/opt/apache-tomcat-8.0.26/webapps/auth/WEB-INF/lib/logback-classic-1.1.3.jar!/org/slf4j/impl/StaticLoggerBinder.class]SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an explanation.SLF4J: Actual binding is of type [org.forgerock.openam.slf4j.AMLoggerFactory]

So, there are a few ways to integrate mobile applications with OpenAM - OAuth2, OpenID Connect or REST. All methods are language independent, which is good.

The most common integration will be OAuth2. With OAuth2 in mind, one has to differentiate that there are in fact 2 types of tokens - Access Token & Refresh Token. The lifetime of a refresh token is long. So, a refresh token is used to exchange for a new access token (which is short-lived). This is important concept. Otherwise, users will need to keep logging in.

A real life example would be your Facebook application on your mobile phone. Are you prompted to log in every day? I don't even recall when did I last logged in. Technically, it's the "refresh token exchanging for an access token" in play.

In order for OpenAM to behave like Facebook (ok, this is very layman), the OAuth2 Provider feature in OpenAM has to be enabled. Once enabled, OpenAM can now provide the same functionalities as Facebook. It is now able to issue access and refresh token to mobile applications. It is now OAuth2-aware.

Some customers will then want to know more about what's going on behind the scene. Well, Victor's slides have it all. I just need to highlight a bit to make it complete.

The very 1st time a user access a mobile application (OAUTH2 Demo), he will be prompted with a consent page.

OpenAM will display the same to user. Depending on which OpenAM version you are using, you might get this:

Yes, so UI customization is required. :) Or if you might get this:

I have not tested the latest UI yet. (Currently on a OpenAM 12 project, OAuth2 is in next phase)

So, after user has given his consent (highlighted in RED), an attribute in the user's LDAP entry is updated to "remember" user has in fact given his consent. This will prevent the Consent Page to be displayed again.

Once that's done, the mobile application will request for an Access Token and this will be stored in the Key Chain on the handphone (highlighted in BLUE). At the same time, the Refresh Token is stored.

The next time the user fires up the mobile application, it will retrieve the Access Token. If it has not expired, it will be used to request token information from OpenAM.

If the Access Token is expired, then the Refresh Token will be used to exchange for a new Access Token. The new Access Token will be stored in the Key Chain.

The extreme case will be the Refresh Token has also expired. Then users will be forced to re-login again.

That explains why some sites have their Refresh Token set to be months or even year. Just long enough for you to change handphone. :)