This chapter covers the integration of native mobile applications with OAAM. This does not include mobile Web applications that are based on browsers or that use Web views.
This chapter contains the following sections;
Develop/Enhance Client Server Interfaces to Handle OAAM-Specific Data
Review Out-of-the-Box Security Policies and Develop Custom Policies If Required
The mobile application integration with OAAM is limited primarily to the server-side integration. The integration developer is responsible for the data exchange between the native mobile application and the business application.
OAAM currently does not provide any software development kit (SDK) that is specific to mobile applications.
Note:
If Oracle Access Management Mobile and Social (Mobile and Social) is used, then you do not have to separately integrate the native mobile application with OAAM. Mobile and Social is already integrated with OAAM. For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.Table 17-1 lists the high-level steps required to integrate native mobile applications with OAAM.
Table 17-1 Overview of Mobile Application Integration
| No. | Step |
|---|---|
|
1 |
Determine how the mobile device has to be identified. Prepare a list of device specific attributes that can uniquely identify a device. The chapter will refer to this information as mobile device fingerprint. |
|
2 |
Design and develop client-server interfaces that can send and receive OAAM specific data in addition to the business application data. Typical OAAM specific data includes device identification-related information and session/request ID during the scope of a user session. If transactions are used, then transaction specific data should also be passed accordingly. |
|
3 |
Write code in the business application to call OAAM APIs to pass the data from the mobile device and also send necessary data from the OAAM API to the mobile device. |
|
4 |
Test the integration and make sure it is working end-to-end. |
The next sections describe the integration tasks in detail.
Out of the box OAAM provides a default mobile device fingerprint consisting of the following attributes:
Operating System Type
Hardware IMEI Number
Hardware Mac Address
These are specified through the enum element named vcrypt.fingerprint.type.enum.native_mobile. You can use the Properties editor option of OAAM Admin Console to view the attributes of this enum element.
To modify the mobile fingerprint:
Log in to the OAAM Admin Console.
In the Navigation pane, double-click Properties under the Environment node. The Properties Search page is displayed.
Enter vcrypt.fingerprint.type.enum.native_mobile in the Name field and click Search.
You should see the attributes of the property in the Search Results section.
If you must add more attributes that identify your mobile device, enter vcrypt.fingerprint.type.enum.native_mobile.header_list in the Name field and click Search.
Click to select the property in the Search Results section, add the list of attributes and click Save.
To provide the mapping of attributes to their display value, enter vcrypt.fingerprint.type.enum.native_mobile.header_name_nv in the Name field and click Search.
Click to select the property in the Search Results section, add the mapping attributes, and click Save.
To provide the mapping of actual value to the display value, enter vcrypt.fingerprint.type.enum.native_mobile.header_value_nv in the Name field and click Search.
Click to select the property in the Search Results section, add the actual value to display, and click Save.
Note: Do not add attributes that are very dynamic in nature like IP Address, and so on, as mobile device fingerprint attributes. Add only those that can uniquely identify the device.
The following example shows a mobile fingerprint enum:
vcrypt.fingerprint.type.enum.native_mobile=900
vcrypt.fingerprint.type.enum.native_mobile.name=Native Mobile
vcrypt.fingerprint.type.enum.native_mobile.description=
Native Mobile implementation using Mobile and Social
vcrypt.fingerprint.type.enum.native_mobile.processor=
com.bharosa.uio.processor.device.NativeMobileDeviceIdentificationProcessor
vcrypt.fingerprint.type.enum.native_mobile.header_list=
os.type,os.version,hw.imei,hw.mac_addr
vcrypt.fingerprint.type.enum.native_mobile.header_name_nv=
os.type,Operating System Type,os.version,Operating System Version,
hw.imei,Hardware IMEI Number,hw.mac_addr,Hardware Mac Address
vcrypt.fingerprint.type.enum.native_mobile.header_value_nv=t,true,f,false
Certain OAAM-specific data must be passed from the native mobile application (client) to OAAM and vice versa. To achieve this, you will need to design, develop, and enhance the client server interfaces so that they can handle OAAM-specific data.
The following are the typical OAAM data that must be handled:
Client (native mobile application)
Send all the device identification related data to the server.
Server
Parse the device identification related data and format device fingerprint.
Use the device fingerprint data while OAAM Session creation API Calls.
Client (native mobile application)
Pass existing OAAM cookies to the server
Persist new OAAM cookies that server returns
Store cookies so that they are secure. (They cannot be stolen)
Server
Get existing cookies from the native mobile application (client) and use them in the OAAM Session creation APIs
Pass the new device cookies to client
Pass Client Application Id/Name
Client should send the mobile application name
Server should use the mobile application name as Client Application when calling OAAM Session Creation API
Client (native mobile application)
Generate new or use existing OAAM Session/Request Id based on whether it is a new session or an existing session. Care must be taken to dispose the OAAM Session ID as soon as the session ends/expires.
Server
Use the Session/Request Id from the client appropriately in the calls to OAAM API
Client (native mobile application)
Send the data required to identify the type of transaction and related data
Server
Determine the transaction definition key and transaction context data based on the data from client
Use the transaction definition key and transaction context data and call OAAM Transaction APIs
Call the transaction related checkpoints/rules and send the result to client
This section describes how the out-of-the-box mobile device identification policy works.
Mobile Cookie identifies the device if the following conditions are satisfied:
Mobile cookie is valid
There is no mismatch with known headers
In this case the score would be zero (0)
Device is treated as New Device if any of the following conditions are satisfied:
Mobile cookie is valid but the known headers do not match
Mobile cookie is invalid (or stale)
If both the first two are not true then a background check is performed to see if the device can be identified using the mobile device fingerprint
Review the following rules in OAAM Post Authentication Security policy that are specific to mobile devices:
Detects if the current device is reported as lost or stolen
| Rule | Rule Condition and Parameter Values | Results |
|---|---|---|
| Lost or Stolen Device | Device: Check if device is of given type
Device Type = Mobile Device Return Value = True Device: Device in group Is in group = True Device in group = OAAM Lost or stolen Device |
Action = OAAM Lost Device
Alert = OAAM Lost or Stolen Device Score = 1000 |
Detects if the current device is jail broken based on the context data from mobile device.
| Rule | Rule Condition and Parameter Values | Results |
|---|---|---|
| Jail broken Mobile Device | Device: Check if device is of given type
Device Type = Mobile Device Return Value = True Session: Check string parameter value Parameter Key = isJailBroken Value = true |
Action = OAAM Challenge
Alert = OAAM Jailbroken Device Score = 500 |
Detects if the user is logging in from too many unregistered mobile devices
| Rule | Rule Condition and Parameter Values | Results |
|---|---|---|
| Too many mobile devices | Device: Check if device is of given type
Device Type = Mobile Device Return Value = True DEVICE: Is registered Is Registered then return = False User: Check Number of Registered Devices of a Given Type Number Of Devices = More than Number Of Devices to compare = 4 Device Of Type = Mobile Device |
Action = OAAM Too Many Mobile Devices
Alert = OAAM More Mobile devices used than allowed Score = 1000 |
Detects if the current login is from a black-listed device
Hardware Identifier same but Operating System mismatch
Detects if the HW Identifier is same as hardware identifier of a previously identified device but the Operating System is not matching.
| Rule | Rule Condition and Parameter Values | Results |
|---|---|---|
| Hardware Identifier same but Operating System mismatch | Precondition: Device Risk Score between 599 and 601
Device: Check if device is of given type Device Type = Mobile Device Return Value = True Device: Browser Header Substring Substring = "OIC" |
Action = OAAM Mobile Device OS Mismatch
Alert = OAAM Mobile Device with Different OS Score = 1000 |
For any additional/custom requirements the recommendation is to create another Policy and add the required rules to that policy.
To detect lost or stolen devices, the related lists have to be populated with the device IDs that are reported as lost or stolen.
The following is the recommended approach:
Log in to OAAM Admin Console
Identify the Device ID of the device that is reported as lost or stolen.
This can be done searching for the user sessions and then narrowing down to sessions that can be confirmed where the device was used
Note the Device ID of the related device
Search for Groups of type Devices.
Select the OAAM Lost or Stolen Devices group
Add the Device ID to the group.
The process is very similar to the process to manage "Lost or Stolen" Devices. The difference is adding the Device Id to the OAAM Black listed mobile devices group.
Out of the box OAAM Post Authentication Policy could return the following outcomes that are specific to mobile devices. These should be appropriately handled for the integration code to take business specific actions:
OAAM Lost Device
OAAM Too Many Mobile Devices
OAAM Black listed Mobile Device
OAAM Mobile Device OS mismatch
The OAAM Server can be customized to be mobile friendly. A base mobile CSS (external stylesheet) file has been provided to enable users to view the Web pages on mobile devices. Because significant differences exist between the browsers found on devices supported by OAAM and the native look-and-feel of each device varies greatly, OAAM Server supports a custom override to the mobile CSS. Device-specific CSS can be defined in addition to generic mobile CSS to allow for more fine grade customizations. Mobile devices include iPhone, iPad, Android, Windows Phone, and Blackberry.
To implement a device specific CSS file:
Make the external CSS file.
For example, customAndroid.css, customIPhone.css, customBlackBerry.css, customWindows7phone.css, and so on.
Define all the style rules within this CSS text file. For example, add a style that makes all body text italic:
body{
font-style:italic
}
Add the following reference to the custom file in oaam_custom.properties:
bharosa.uio.default.custom.mobile.css=/css/customMobile.css
Add custom mobile CSS per mobile device type by including the name of the device in the property, so that
bharosa.uio.default.custom.mobile.<device>.css=/css/custom<device>.css
<device> can be any defined device, such as iPhone, Blackberry, Android, and Windows Phone.
bharosa.uio.default.custom.mobile.android.css=/css/customAndroid.css bharosa.uio.default.custom.mobile.iphone.css=/css/customIPhone.css bharosa.uio.default.custom.mobile.blackberry.css=/css/customBlackBerry.css bharosa.uio.default.custom.mobile.windowsphone7.css= /css/customWindowsPhone7.css
Add the CSS file in the OAAM Extensions library.
Custom mobile CSS file inclusion depends on definition of the property and inclusion of the CSS file in the OAAM Extensions library.
The default inclusion order is as follows:
Product CSS
Custom CSS (if defined)
Product right to left CSS (if right to left locale)
Custom right to left CSS (if right to left locale and defined)
Product mobile CSS (if mobile device)
Custom mobile CSS (if mobile device and defined)
Product mobile device specific CSS (if defined for device)
Custom mobile device specific CSS (if defined for device)
If files define the same attribute, the file that comes later overrides the earlier one.
In additional to the custom CSS file, the OAAM out of the box policies provide for an the HTML version of the question registration page for a user on a mobile device.
The Authentication pad policy returns the HTML action when a user is required to register new security questions and the user is accessing the application from a mobile device web browser.
The Authentication pad policy returns the Question Pad action when user is required to register a new security questions and the user is accessing the application from a non-mobile device web browser.