1. Developing Applications with Oracle Access Management
  2. Developing with Access Manager
  3. Customizing Oracle Mobile Authenticator

7 Customizing Oracle Mobile Authenticator

The Oracle Mobile Authenticator (OMA) is a mobile device application that uses One Time Password (OTP) and push notifications to authenticate users without incurring the cost of hardware tokens or SMS charges. This application provides password less authentication. The supported platforms are iOS, Android and Windows universal app.

This chapter contains procedures that you can use to brand the Oracle Mobile Authenticator to represent your company's logo and colors. It contains the following sections.

7.1 About Oracle Mobile Authenticator and Customization

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 Managing the Adaptive Authentication Service and Oracle Mobile Authenticator in Fusion Middleware Administering Oracle Access Management.

As the Administrator, you can customize the following features in the OMA application and distribute the application for internal use.

  • Application logo and images

  • String resources

  • End User License Agreement (EULA), Private Policy and Help of the app

  • Name, Identity and Version information of the app

7.2 Customizing Oracle Mobile Authenticator on iOS

The Oracle Mobile Authenticator (OMA) is distributed as a ZIP of xcarchive which can be used to customize the application. Xcode is used to sign the xcarchive and generate the IPA(App which can be installed on devices).

Note:

To get the Oracle Mobile Authenticator (OMA) customizing app, contact Oracle support to get access to an unsigned mobile archive.

Before you Begin

The following resources are required to customize OMA:

  • MAC with Xcode installed

Customize iOS OMA app

The iOS OMA app can be customized in 3 steps.

1. Extract/unpack xcarchive

2. Customize xcarchive

3. Sign xcarchive from Xcode using the certificates generated by your company. This action is required to install the app on the devices, to setup the notification services and to upload the app to the app store.

Extract/Unpack xcarchive

OracleAuthenticator.xcarchive is provided to the user.

  1. Right click on OracleAuthenticator.xcarchive and navigate to open package contents --> Products --> Applications -->Authenticator

  2. Right click on Authenticator, and select open package contents.

Customize xcarchive

  1. Splash Screen

    This screen is visible for small amount of time while launching the app.

    • There are 8 images starting with LaunchImage... . Create customized images using the image sizes provided. Sizes are mentioned as a part of the image name.

  2. App Icon

    This is the image shown in the Home screen or Spring board.

    • There are 12 images starting with AppIcon... Create customized images using the image sizes provided. Sizes are mentioned as a part of the image name.

    • Replace the image with the same name.

  3. OMA logo

    These images are shown as the default icons of the account.

    • There are two images with different foreground colors with transparent background.

      Image 1. oma_blue.png with size 96*96 pixels.

      Image 2. oma_white.png with size 205*270 pixels.

    • Replace the customized files with the same name and png format.

      . Note that changing the Image size aspect ratio may at times cause the user interface to look distorted. Verify that the image size/aspect ratio looks as required, before it is finalized.

  4. Other company icons.

    Each account has an image associated with it. The account image can be selected among the available images while adding the account during the manual entry of shared secret or, the existing account images can be changed in the edit screen.

    • others.png with 140*140 pixels.

  5. App display name.

    This is the name of the App which is shown in the home screen.

    • Open Info.plist file

    • Edit the value of the field Bundle display name. The default value is Authenticator.

  6. EULA, Private Policy and Help.

    • Inside en.lproj there are files for each file(eula.txt, help.html and privacy.html). These files can be edited. The eula.txt is not localized.

      Note:

      Files have to be updated in all the Localized languages. Localized language folder will have ".lproj" as extension.

  7. 3rd party company list with images.

    These are the 3rd party companies which could be used to configure the account through OMA. This page can be viewed while creating a new account through a manual entry of Key or Editing the account information. The company name and image would be shown in the same order.

    • Open CompanyList.json file, The company name and image is shown in the same order. Any Item can be deleted. Available image name can be updated in IconName.

  8. If EULA needs to be displayed on first launch.

    • Open CustomizableFlags.plist, change the value of shouldEULAShownOnFirstLaunch to YES or NO. Default is YES.

  9. App version can be changed from (Bundle versions string, short) in info.plist.

  10. Application name is shown inside the OMA in various places. Only the application name can be customized and localization is not supported. The default application name is Oracle Mobile Authenticator. This can be customized by changing the field CompanyName in info.plist file.

Sign xcarchive

  • Get the App Bundle Identifier of the certificate which is generated in apple.developer.com. Certificates related to this bundle Identifier is used to sign the application. For an example the Bundle Identifier looks like com.acme.authenticator.

    • The customer generates the certificates which is used to sign the application.

    • They use their apple developer's account to generate the certificates.

    • The certificates have a unique string which is used to distinguish between the apps.

    • The unique string is called as Bundle Identifier that is used here.

    For more information , See https://developer.apple.com/library/content/documentation/IDEs/Conceptual/AppDistributionGuide/MaintainingCertificates/MaintainingCertificates.html

  • Open info.plist file, Update the field Bundle identifier with the App Bundle Identifier.

Save all changes, double click on the xcarchive folder. This will launch Xcode.

To sign the app, Follow the instruction given in https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/Introduction/Introduction.html. 

To sign and export iPA from Xcarchive, follow the steps given in https://developer.apple.com/library/content/documentation/IDEs/Conceptual/AppDistributionGuide/TestingYouriOSApp/TestingYouriOSApp.html

7.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.

7.3.1 Using apktool to Customize Oracle Mobile Authenticator

The apktool installation and usage guide can be accessed from the apktool project home at https://ibotpeaches.github.io/Apktool/. The following sample command is used to decompile an Android app package. 

apktool d OracleMobileAuthenticator-android-release_branch_21_03_2017-170403.181503.apk

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 OracleMobileAuthenticator-android-release_branch_21_03_2017-170403.181503

7.3.2 Customizing Options for Oracle Mobile Authenticator Android app

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

7.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.

The icon must be replaced in all the following folders:

  • res\drawable-mdpi-v4

  • res\drawable-hdpi-v4

  • res\drawable-xhdpi-v4

  • res\drawable-xxhdpi-v4

  • res\drawable-xxxhdpi-v4

The following icons can be replaced with your customized icons with same size and name as that of original icons:

  1. Launcher Icon: res\mipmap-mdpi-v4\ic_launcher.png

  2. OMA logo There are two Images with different foreground colours with transparent background.

    Image 1. res\drawable-mdpi-v4\oma_logo.png

    Image 2. res\drawable-mdpi-v4\mfa_icon.png

  3. Other company icons

    Other company icon is a default company icon shown for 3rd party companies. It can be changed in companylist.json

    res\drawable-mdpi-v4\others.png

7.3.2.2 Modifying the Application Name and Text

The name 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">Authenticator</string>

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

<string name="app_name">Acme 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

    Help is localized. To customize help, the help file needs to be changed in the localization folders.

Note:

When app name and strings are changed, Do make sure to change the corresponding translated strings. For example, res\values-ar, res\raw-ar
7.3.2.3 Editing 3rd party company list with images

Open res\raw\companylist.json file. The company name and image would be shown in the same order. Any item can be deleted. Available image name can be updated in "IconName".

7.3.2.4 Modifying EULA to be shown on first launch

Open res\raw\prop.txt. Change the value of showEula to yes . The values are treated as case-insensitive. Default value is yes.

7.3.2.5 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 to Customize Oracle Mobile Authenticator) 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 7-1. In this example, the version name has been changed to test.xx.x.x from the default value 11.1.2.3.0.

Example 7-1 Changing the Android Version and Code Number

versionInfo:versionCode: '3'versionName: 'test.xx.x.x'
7.3.2.6 Modifying the Package Name
To modify the package name

  1. Open AndroidManifest.xml present in the decompiled apk folder in Notepad++. "Find All" <package name> and replace with the new package name and set Directory as the location of the decompiled apk folder and filter as "*.*".

    Example: Find what: oracle.idm.mobile.authenticator Replace what : example.idm.mobile.authenticator

  2. Similarly, Find All and Replace package name appended with 'L' and '.' replaced with '/'

    Example : Find what :Loracle/idm/mobile/authenticator Replace what :Lexample/idm/mobile/authenticator

  3. Go to smali folder in the decompiled apk folder and rename the folder names according to new package name.

  4. Build the folder using apk tool. For example:

    apktool b OracleMobileAuthenticator-androidrelease_branch_21_03_2017-170403.181503
7.3.2.7 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

7.3.2.8 Customizing Copyright Details
Follow the steps mentioned below to customize copyright details:
  1. Decompile the OMA.apk.
  2. Navigate to OracleMobileAuthenticator/res/values/strings.xml.
  3. Update the copyright text written between the <string> tag as needed:
    <string name=“copyright”>Copyright © 2013–2022, Oracle and/or its affiliates. All rights reserved.</string>
7.3.2.9 Customizing Notifications and Enrollment Types

You can now enable or disable Push and Pull notifications and manage enrollment types.

After decompiling the OMA.apk navigate to the file location OracleMobileAuthenticator/src/main/res/raw/prop.txt and update following properties based on the requirement.
Property Description

isEnablePushAndPullNotification

You can enable or disable Push and Pull notifications by setting the value of isEnablePushAndPullNotification to true/false.

Set the value to false to disable the Push/Pull notification.

The default value is true.

enrollmentType

You can set the enrollmentType value to qr_and_manual to utilize both the QR code scanner and manual enrollment methods, or can skip the QR Scanner activity and add an account manually by setting the value to manual.

The default value is qr_and_manual.

hideFooter

You can set the hideFooter value to true to prevent the footer from appearing at the bottom of the Manual Add Account screen.

The default value is false, which displays the footer.

7.4 Customizing Oracle Mobile Authenticator on Windows

The Oracle Mobile Authenticator (OMA) is distributed as a ZIP package which can be used to customize the application.

Note:

To get the Oracle Mobile Authenticator (OMA) customizing app, contact Oracle support to get access to an unsigned mobile archive.

Before you Begin

The following resources are required to customize OMA:

  • Windows 10 onwards

  • VIsual Studio 2015 onwards

Customize Windows OMA app

The Windows OMA app can be customized in 3 steps.

1. Extract/unpack package

2. Customize package

3. Create/pack package

Extract/Unpack Package

Open Developer Command Prompt for VS2015 and run the following commands:

  1. MakeAppx unbundle /o /p / <full path of appxbundle > /d <full folder path where appxbundle will be extracted >

    For example, MakeAppx unbundle /o /p F:\OMA\OMA.10_1.9.2.0_x86_x64_arm_Release_UWP10.appxbundle /d F:\OMA\unbundle

  2. MakeAppx unpack /o /l /p <full path of appx file> /d <full folder path where appx file will be extracted>

    For example, MakeAppx unpack /o /l /p F:\OMA\unbundle\OMA.10_1.9.2.0_x64_Release_UWP10.appx /d F:\OMA\unpack

Customize Package

Once you extract the package under the OMA folder, the folder structure will look similar to the sample as shown in the below figure.

Description of oma_windows_fstructure.png follows
Description of the illustration oma_windows_fstructure.png

Note:

  • Customize every package present in appxbundle (or appx files present in output location of MakeAppx unbundle command.). the steps given here help you customize one package.

  • When you update an image file, make sure that the image file name and dimension remain the same.

  • When you update the Help file or EULA file, make sure that the file name remains the same.

  • When you update any string resource, make sure that the string key name remains the same and only the value is updated.

 

  1. Splash Screen

    This screen is visible for a small amount of time while launching the app.

    • The screen image files start with SplashScreen... under OMA\Assets. Create customized images using the image sizes provided. Sizes are mentioned as a part of the image name.

      for example, SplashScreen.scale-200.png

  2. App Icon

    This is the image shown in the Home screen or Spring board.

    • The following app icon images are under OMA\Assets. Create customized images using the image sizes provided. Sizes are mentioned as a part of the image name. Replace the image with the same name.

      • LockScreenLogo.scale-200.png

      • Square44x44Logo.scale-200.png

      • Square44x44Logo.targetsize-24_altform-unplated.png

      • Square71x71Logo.scale-200.png

      • Square150x150Logo.scale-200.png

      • Square310x310Logo.scale-200.png

      • StoreLogo.png

      • Wide310x150Logo.scale-200.png

  3. OMA Logo

    These images are shown as the default icons of the account.

    • There are two images that you can update under OMA\Assets.

      Image 1. MFA_Icon.png.

      Image 2. OMA_Logo_70.png

    • Replace the customized files with the same name and png format.

      . Note that changing the Image size aspect ratio may at times cause the user interface to look distorted. Verify that the image size/aspect ratio looks as required, before it is finalized.

  4. Other Company Icons.

    Each account has an image associated with it. The account image can be selected among the available images while adding the account during the manual entry of shared secret or, the existing account images can be changed in the edit screen.

    • Others.png

  5. App Display Name.

    This is the name of the App which is shown in the home screen.

    • Open AppxManifest.xml under OMA folder and update following information.

      • Package → Identity → Name

      • Package → Identity → Publisher

      • Package → Properties → DisplayName

      • Package → Properties → PublisherDisplayName

      • Package → Applications → Application Id="App" → uap:visualElements → DispalyName

      • Package → Applications → Application Id="App" → uap:visualElements → Description

      • Open Config.json file under OMA\Config folder and update following string resource

        • appConfig.json → appName

        • appConfig.json → companyName

  6. EULA.

    Update the following file under OMA\Assets.

    • eula.html

  7. Private Policy.

    Open Config.json file under OMA\Config folder and update the following string resource.

    • appConfig.json → privacyPolicyUrl

  8. Help.

    Update the following file under OMA\Strings\en.

    • help.html

  9. 3rd Party Company List with Images.

    These are the 3rd party companies which could be used to configure the account through OMA. This page can be viewed while creating a new account through a manual entry of Key or Editing the account information.

    • Open companylist.json file under OMA\Assets folder and update as many entries as needed, The company name and image is shown in the same order as present in file. Any Item can be deleted. Available image name can be updated in IconName. The image mentioned in IconName key must be present in OMA\Assets folder.

  10. If EULA needs to be displayed on first launch.

    • Open Config.json under OMA\Config folder and update following information with value as true or false. True is for show at first launch and false is for not showing.

      • appConfig.json → showEULA

  11. App Version Number.

    Open AppxManifest.xml under OMA folder and update the following information.

    • Package → Identity → Version

Create/Pack Package

Open Developer Command Prompt for VS2015 and run the following commands:

Note:

In the following commands, appx and appxbundle file name and full path must be same.

  1. MakeAppx pack /o /l /d <full path of customized folder> /p <full path of customized appx file>

    For example, MakeAppx pack /o /l /d F:\OMA\unpack /p F:\OMA\unbundle\OMA.10_1.9.2.0_x64_Release_UWP10.appx

    Note:

    The step mentioned above helps you to customize one package. Use the step to customize every package and then run the following commands to generate the appxbundle and signing it.

  2. MakeAppx bundle /o /d <full path of customized unbundle folder> /p <full path of customized appxbundle file>

    For example, MakeAppx bundle /o /d F:\OMA\unbundle /p F:\OMA\OMA.10_1.9.2.0_x86_x64_arm_Release_UWP10.appxbundle

  3. SignTool sign /fd SHA256 /a /f <full path of pfx certificate file> /p <password of pfx file> <full path of customized appxbundle file>

    For example, SignTool sign /fd SHA256 /a /f F:\OMA\OMA.10_TemporaryKey.pfx F:\OMA\OMA.10_1.9.2.0_x86_x64_arm_Release_UWP10.appxbundle

Note:

/p <password> parameter in the above command is optional, if pfx file is not protected by password then ignore this parameter. https://msdn.microsoft.com/en-us/library/windows/desktop/jj835832(v=vs.85).aspx describes how to create a signed certificate used in SignTool command.

For more information about MakeAppx utility, See https://msdn.microsoft.com/en-us/library/windows/desktop/hh446767(v=vs.85).aspx.