13 Customizing Oracle Mobile Authenticator

The Oracle Mobile Authenticator is a mobile device app that uses Time-based One Time Password (TOTP) and push notifications to authenticate users. The Oracle Mobile Authenticator mobile device app is customer-facing and thus can be customized to represent your company.

This chapter describes procedures that can be used to brand the Oracle Mobile Authenticator with your company's logo and colors. It contains the following sections.

13.1 Understanding the Oracle Mobile Authenticator

The Oracle Access Management Adaptive Authentication Service offers the ability to add multiple steps to the user authentication process. This additional security may be enforced by adding a OTP step, or an Access Request (Push) Notification step after initial user authentication. In certain cases, the enforcement involves the use of the Oracle Mobile Authenticator (OMA), a mobile device app that uses Time-based One Time Password and push notifications to authenticate users within the additional second factor authentication scheme. For more details on the Adaptive Authentication Service and how it works with the OMA, see the Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

13.2 Customizing Oracle Mobile Authenticator on iOS

The Oracle Mobile Authenticator (OMA) is distributed as a ZIP archive which contains OMA (as a framework), OMA resources bundle and strings files. Developers can use Xcode IDE to customize the OMA. This section contain information on how to do this. The following resources are required to customize OMA.

  • oamms_sdk_for_ios.zip is the Identity Management Mobile SDK for iOS. It contains:

    • libIDMMobileSDK.a

    • Public Headers

    • Public Resources

  • OMACustomizable-11_1_2_3_0.zip contains the following customizable OMA files:

    • OMALibrary.framework

    • OMAResources.bundle

    • Localization files

    Note:

    The ofm_oma_clients_11.1.2.3.0.zip contains the OMACustomizable-11_1_2_3_0.zip and OracleMobileAuthenticator-11_1_2_3_0.apk files. The latter is used in Section 13.3.1, "Using apktool."

The following sections contain more information.

13.2.1 Using Xcode

The minimum version required is Xcode 6 with iOS SDK 8.0.

  1. Open Xcode.

  2. Click on Create a new Xcode Project.

  3. Under iOS select Application.

  4. Choose Single View Application and click Next.

  5. Enter values for the following fields.

    • Product Name: Acme Authenticator, for example

    • Organization Name: Acme, for example

    • Organization Identifier: This value is the same as the identifier defined in Apple Developer.

    • Language: Objective-C

    • Devices: Choose Universal/iPhone/iPad depending on the devices on which this customized version of OMA will execute.

  6. Click Next and then Create.

    This will open a new window where the Acme Authenticator project will be displayed.

  7. In the Project Navigator menu click on Acme Authenticator project.

    The Acme Authenticator.xcodeproj tab will show the Project and Targets.

  8. Under Targets click Acme Authenticator.

  9. Click Build Settings.

  10. Under Linking find Other Linker Flags and add -ObjC -all_load as its value.

  11. Under Acme Authenticator.xcodeproj tab click General.

  12. Add the following frameworks and libraries

    • Security.framework

    • SystemConfiguration.framework

    • CoreLocation.framework

    • libsqlite3.dylib

  13. Under Project Navigator click Acme Authenticator and choose Add files to Acme Authenticator.

  14. Add libIDMMobileSDK.a, Public Headers, Public Resources, OMALibrary.framework, OMAResources.bundle, Localization files and directories.

  15. Click on AppDelegate.h file

  16. Import OMALibrary app delegate by using #import <OMALibrary/OAAppDelegate.h>

  17. Replace @interface AppDelegate : UIResponder <UIApplicationDelegate> with

    @interface AppDelegate : OAAppDelegate

  18. Click on AppDelegate.m file and remove all the UIApplicationDelegate methods.

  19. Under Supporting Files right click on Info.plist file and choose Open As Source Code

  20. Under the dict tag add the following tags.

    <key>CFBundleDisplayName</key>
<string>Acme Authenticator</string>

  21. Distribute the customized app.

    The customized Xcode project can be used for distributing the Acme Authenticator by following the guideleines in the Apple App Distribution Guide available at https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/Introduction/Introduction.html

13.2.2 Customizing Oracle Mobile Authenticator

The following sections contain information about what can be customized.

13.2.2.1 Changing the Application Art

Artwork used inside OMA is located in the OMAResources.bundle folder. These art files can be replaced with files of the same name. Table 13-1 contains a listing of the files. An app icon can be chosen by following the Technical Q&A QA1686 : App Icons on iPad and iPhone available at https://developer.apple.com/library/ios/qa/qa1686/_index.html

Table 13-1 Customizable Artwork

File Name File Size Description

check_57.fw.png

57x57 png file

Notification history screen when a notification is accepted

copy.png

57x57 png file

One-time password screen for copying OTP

cross_57.fw.png

57x57 png file

Notification history screen when a notification was rejected

delete.png

57x57 png file

One-time password screen for deleting OTP account

edit.png

57x57 png file

One-time password screen for editing OTP account

gears_60.png

60x60 png file

Current configurations screen header

keyboard.png

57x57 png file

Add account screen and Offline configuration screen for offline account creation

notifications_57.png

57x57 png file

Notification prompt and history screen header

keyboard.png

57x57 png file

Add account screen and Online configuration screen for online account creation

13.2.2.2 Modifying the Application Name and Text

The app name can be changed by updating the value of the CFBundleDisplayName tag in the Info.plist file. The other text used in the app is pulled from the following files available under the Localization folder. This text can also be modified.

  • help.html: Help file text

  • privacy.html: Privacy policy text

  • eula.txt: End user license agreement

  • OALocalizable.strings: Messages shown in the app

13.2.2.3 Toggling Online and Offline Mode

The OMA supports both online and offline mode. This feature can be enabled or disabled by modifying the OMAResources.bundle/OAProperties.plist file.

13.2.2.4 Changing the Application Version

The Application Version can be changed by updating the CFBundleShortVersionString value in Info.plist file.

13.2.2.5 Signing the Application

App can be signed by following the instructions in the Apple App Distribution Guide available at https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/Introduction/Introduction.html

13.3 Customizing Oracle Mobile Authenticator on Android

The Oracle Mobile Authenticator is shipped to customers as an Android application package (.apk). The apktool is a tool that allows you to decompile an Android application, modify it and then rebuild it with the modifications. See the following sections for information on using the apktool.

13.3.1 Using apktool

The apktool installation and usage guide can be accessed from the apktool project home at https://code.google.com/p/android-apktool/. The following sample command is used to decompile an Android app package.

apktool d "..\bin\OracleMobileAuthenticator-11_1_2_3_0.apk" -o d:\oma_smali_out

This next sample command is used to recompile the updated contents of Android app package. It will create a signed version of the customized app.

apktool b -f -a "..\Android_SDK\build-tools\20.0.0\aapt.exe" 
  ..\oma_smali_out -o ..\oma_recompiled\temp.apk

Note:

The ofm_oma_clients_11.1.2.3.0.zip contains the OMACustomizable-11_1_2_3_0.zip and OracleMobileAuthenticator-11_1_2_3_0.apk files. The former is used in Section 13.2, "Customizing Oracle Mobile Authenticator on iOS."

13.3.2 Customizing Options

The following sections document the customizing options for the Oracle Mobile Authenticator Android app.

13.3.2.1 Changing Application Icons

For better UX control and multiple screen support, Android provides separate folders to better organize drawables for each screen type. (As an example the drawable-hdpi is for high pixel density devices.) Android application icons are located in the res/ folder.

Based on the requirement the OMA application icons can also be updated in the corresponding drawable folder. In order to customize the application icons replace the old icons with the new icons without changing the icon name. Table 13-2 describes the application icons that can be customized. Again, be sure not to change the Icon name.

Table 13-2 Customizable Application Icons

Application Icon and Description Icon Name (Do Not Modify)

App Launcher / Oracle name with padlock

ic_launcher.png

Icon to add more accounts / plus sign

add.png

Icon to initiate bar code scanning / generic barcode

barcode.png

Icon for showing notification as accepted / check mark

check.png

Icon for showing notification as canceled / x mark

cross.png

Icon for delete account / trash can

delete.png

Icon for showing error alert messages / exclamation mark

error_alert.png

Icon for copy OTP (in action bar) / two paper images

ic_action_copy.png

Icon for edit account / pencil image

ic_action_edit.png

Icon to show keyboard / keyboard image

keyboard.png

Icon to show notification / globe with text balloon

notification.png

Icon for settings / generic gears image

setting.png

Icone for sign-in / generic person image

signin.png

13.3.2.2 Modifying the Application Name and Text

The name Oracle Mobile Authenticator can be customized by modifying the existing value of the string app_name in the /res/values/strings.xml file. Find the default value in the file as:

<string name="app_name">Oracle Mobile Authenticator</string>

Change this value to the preferred name and save; for example, Acme Mobile Authenticator. No special characters can be used.

<string name="app_name">Acme Mobile Authenticator</string>

The End-user License Agreement, Privacy and Help text can also be customized. To change the text, replace the original version of the file(s) with the new file(s) in the directory structure as specified below. Do not change the file name.

  • End-user License Agreement: /res/raw/eula.txt

  • Privacy: /res/raw/privacy.html

  • Help: /res/raw/help.html

13.3.2.3 Toggling Online and Offline Mode

The Oracle Mobile Authenticator supports both online and offline mode. This feature can be enabled or disabled by modifying the /res/raw/prop.txt file. For example, to support only offline mode the content of the prop.txt file is defined as in Example 13-1.

Example 13-1 Customizing Oracle Mobile Authenticator Mode

{
"configuration":
{
"online":"no",
"offline":"yes"
}
}

13.3.2.4 Modifying the Version and Code Number

Modify the version and code number of the application by changing details in the apktool.yml located in the directory where the .apk file content has been de-compiled. (See "Using apktool.") The apktool.yml file can be viewed and modified in any text editor. The versionCode and versionName parameters are located under the versionInfo property as illustrated in Example 13-2. In this example, the version name has been changed to test.xx.x.x from the default value 11.1.2.3.0.

Example 13-2 Changing the Android Version and Code Number

versionInfo:versionCode: '3'versionName: 'test.xx.x.x'

13.3.2.5 Signing the Application

Android requires that all apps be digitally signed before they can be installed. Android uses the certificate to identify the author of the app. The certificate does not need to be signed by a certificate authority so Android apps often use self-signed certificates. Additional details on this Android requirement and its process, including the procedure you can use to sign your apps, are described at http://developer.android.com/tools/publishing/app-signing.html#signing-manually