New Features in OAM Oracle Mobile Authenticator

Until recently, 2-factor strong authentication has usually had extra cost and complexity associated with it. In OAM 11g R2 PS2, Oracle has sought to eliminate a lot of this with the introduction of Oracle Mobile Authenticator (OMA).

Support for OMA ships out of the box with PS2 and setup is fairly straightforward. This blog post will walk you through configuring OMA from start to finish, and we’ll also share some of the tips and tricks we learned along the way.

At a high level, OMA requires that you configure the OAuth Service in OAM for secret key generation. Next, you will be required to configure the TOTPMobile Authentication Module and Plugin, as well as creating an associated authentication scheme. You will also need to update your existing Authentication Policy for your specific use cases using Advanced Rules (another new feature in OAM 11g R2 PS2). Finally, we will walk through configuring the OMA application in an iOS device.


Configure OAuth Service

From the Launch Pad, click OAuth Service under Mobile and Social. If Mobile and Social is not yet enabled, go ahead and enable it by first choosing Available Services.

Choose the DefaultDomain. Under the Resource Servers tab, click UserProfile under User Profile Services. Click Resource URIs then /secretkey. Expand Attributes to add (or update if it already exists) an attribute called basicauth.allowed with value true.

You will also see a keyAttributeName in this attribute list. By default, it is description and this is what we’ll be using in this demo. This will need to match other configuration parameters later (such as the TOTPModule Authentication Module), so be sure to note this.

Configure OAuth Service

Important: If you intend to use OUD as your data store, then you must also disable proxyAuth. To do so, expand the Attributes list for the UserProfile service (above Resource URIs), and add the attribute called proxyAuth with value false. 

Finally, make sure the Identity Store name is correctly selected for your back end data store.

Configure Shared Components

The shared components utilized by OMA are:

  • The TOTPModule Authenticator Module
  • The TOTP Plugin
  • A TOTP Authentication Scheme

From the Launch Pad, choose Authentication Modules. An instance of TOTPModule ships out of the box with the product. Select it and click on the Steps tab. 

You will need to specify the KEY_IDENTITY_STORE_REF and KEY_OTP_SECRETKEY_ATTRIBUTE parameters. Enter the name of the OAM Identity Store, which will store the users along with the secret key attributes. Recall that in the previous step we used description, so be sure to specify whichever attribute you used in the OAuth configuration.  Click Save, then Apply.

Step Details

Next, from the Launch Pad, choose Plug-ins. Select the TOTPPlugIn from the list and fill in the same KEY_IDENTITY_STORE_REF and KEY_OTP_SECRETKEY_ATTRIBUTE parameters (obviously with the same values you used in the Authentication Module). Click Save. 

Finally you will need to create an Authentication Scheme. The documentation recommends opening the LDAPScheme and clicking Duplicate as an easy way to prepopulate the form. Give the Authentication Scheme a name such as TOTPScheme. For Challenge URL, enter /pages/getOTP.jsp and select the TOTPModule from the list of Authentication Modules. Here’s what the finished Scheme should look like:

Authentication Scheme


Create Advanced Rule for Authentication Policy

One of the new features in OAM 11g R2 PS2 is the ability to create Advanced Rules for Authentication Policies. When working with OMA, you will use a Post-Authentication Rule to tell the Authentication Policy to use the TOTPScheme if certain conditions are met (for example, a certain browser or IP range).

To do this, load the Authentication Policy you wish to customize and click on the Advanced Rules tab, then click Post-Authentication. Click Add (the green plus sign). You can specify any rule name and description. 

For the condition, you can use the Jython scripting syntax documented here As an example, we wanted all users who are using Firefox to use a OTP, so we used this condition: request.userAgent.lower().find(‘firefox’) > 0

Finally, choose Switch Authentication Scheme to TOTPScheme. This will happen if the condition defined above is met. In other words, after the user logs in, if they are using Firefox, require an additional OTP be provided before they are allowed to access the resource.


Configuring the Oracle Mobile Authenticator app on iOS

The OMA app is available for free in the iOS and Android app stores. When you download it to your device and launch it, you will be presented with options for Online and Offline configuration. Online configuration is simple but requires that you first provide the url for the secretkey service. To do this, you must create a web page with the following hyperlink:


In a real world scenario, one would direct users to this page so they could tap this link. The OMA app will then open automatically and you will be prompted to “Accept the Configuration Update”. Tap Accept, and then tap OK when you see the Success message.

Configuration Update


The OMA app is now configured with the proper REST endpoint for secretkey retrieval. Next, tap Sign In. Provide your LDAP credentials and then tap Submit. If your credentials are correct, you will see your username and 6 digit OTP code displayed on the screen. 

OTP Setup



Lessons Learned

We learned a couple important things about this process that aren’t clear in the documentation.

If you use Simple Mode, you will have to configure copy PASSPHRASE, KEYSTORE, and TRUSTSTORE parameters from the Mobile Social MobielOAMAuthentication Service Provider and add them to the OAuthServiceProvider configuration. Don’t forget to copy the oam.ENCRYPTED_PASSWORD parameter as well.

Also if you want to use the Mobile Authenticator app with more than one OAM instance or domain, you absolutely can. This is especially useful to testing several environments (dev, test, QA, production, etc). Just keep in mind that you will be prompted to provide a unique name if you use the same username across more than one instance.

And finally, one last point: There appears to be a bug that allows users with invalid credentials through to the OTP page. Once here, every OTP attempt will fail and an error message displayed. Be aware that if you’re going to implement this, you will want to check with Oracle for the latest on this issue.