11.12.1 Configuring Oracle Mobile Authenticator Push Notification for Android

The Oracle Mobile Authenticator (OMA) is a mobile device application that uses Time-Based One-Time Passcode (TOTP) or push notifications to authenticate users with a two-factor authentication scheme. OAA allows you to configure push notifications for the OMA application.

When you are asked to authenticate using a push notification for OMA, then a push notification is delivered to an Android device where you have to either allow or deny the login attempt. The push notification is delivered to the OMA application, which then communicates with the OAA server to grant or deny you access to the protected resource.

Note:

Push notifications require factor verification to be configured as a prerequisite. Make sure factor verification is configured before proceeding. See Configuring Factor Verification.

Topics

The following topics describe how to configure push notification on Android:

11.12.1.1 Installing the Oracle Mobile Authenticator Application

You can download the Oracle Mobile Authenticator (OMA) application for Android devices from the Google Play Store.

Any end user who is to use OMA Push Notifications must install the application on their Android device.

11.12.1.2 Configuring Firebase and OAA

The following configuration steps show how to configure push notifications for Android devices with OAA.

Note:

Administrators should be aware of the following:
  • Google is deprecating Legacy FCM API's in June 2024 and migrating to HTTP v1 API's. For all new configurations it is recommended to use HTTP v1 API's. The steps in this section configure push notifications using HTTP v1 API's.
  • In order to use HTTPv1 API's you must be using the OAA June 24 refresh release or later.
  • If you have configured push notifications for Android in releases prior to OAA June 24 refresh, you will be using Legacy FCM API's. Administrators should migrate to HTTP v1 API's by upgrading to OAA June 24 refresh or later. The steps to upgrade and migrate to HTTP v1 API's can be found in Upgrading OAA, OARM, and OUA.
  • For reference purposes, the configuration steps using Legacy FCM API's have been moved to Configuring OMA Push Notifications Using Legacy FCM API's.

Topics:

11.12.1.2.1 Creating a Google Firebase Project Enabled for Google Cloud Messaging

To send push notifications to Android devices, you must ensure a project is enabled with an Android push notification service. The push notification service that you can use for Android is Google Cloud Messaging (GCM), which requires you to create a Google Firebase project.

Perform the following steps to create a Google Firebase project:
  1. Login to Google Firebase console at https://console.firebase.google.com/.
  2. Click Add project.
  3. In the Project name field, enter a name for your project. For example, OAAAndroidPUSH.
  4. On the Google Analytics for your Firebase project page, deselect Enable Google Analytics for this project, and then click Create project.
  5. Click Continue when your new project is ready.
  6. In the left navigation pane of the project window, click the Settings icon, and then select Project settings.
  7. On the Project settings page, click Cloud Messaging.
  8. Under Firebase Cloud Messaging API (V1), click on the ellipsis and select Manage the API in Google Cloud Console.
  9. In the new tab that appears, under Cloud Messaging click ENABLE if not already enabled.
  10. Return to the original tab where you clicked Firebase Cloud Messaging API (V1) and refresh the page.
  11. Note the value present in the Sender ID field. This value is required later in Configuring OAA Properties for Android Push Notification.
  12. Go to the Service Accounts tab and click Generate new private key. In the Generate new private key window, click Generate key. This will generate a service account json file. Download and save the file, for example service-account.json. Keep the file secure as it is required later in Copying the Service Account JSON File to OAA.

11.12.1.2.2 Configuring OAA Properties for Android Push Notification

You must set up some OAA properties that are required for configuring push notifications for Android devices.

The following table lists the OAA properties that you can configure for push notification for Android.

Table 11-2 OAA Properties

Property Name Description Sample Value
bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.proxyProtocol The protocol of the proxy server. http or https
bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.proxyHost The host name or IP address of the proxy server. proxy.example.com
bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.proxyPort The port of the proxy server. 80
bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.pushPreferencesEndpoint The host and port used for push factor registration. This host and port should be accessible from the device. This corresponds to the host and port referenced in the SpuiUrl (SpuiUrl=https://<host:port>/oaa/rui) in Printing Deployment Details. https://oaainstall
bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.challengeAnswerEndpoint The host and port used for push factor runtime. This host and port should be accessible from the device. This corresponds to the host and port referenced in the Push URL (Push=https://<host:port>/oaa-push-factor) in Printing Deployment Details. https://oaainstall
bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.retrycount Maximum number of unsuccessful retries of the challenge. Beyond this count the challenge is locked. The default value is 10. If you are using push notifications with Oracle Universal Authenticator you must set this value to 50. 50
bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.google.firebase.senderId The Firebase Sender ID. See Creating a Google Firebase Project Enabled for Google Cloud Messaging. 58213467743

Note:

The proxyProtocol, proxyHost, and proxyPort properties are only required if internet access is available through a proxy server. If OAA has direct access to the internet these properties do not need to be set.

You can configure the OAA properties using the following REST API: 

PUT  <PolicyUrl>/policy/config/property/v1

Note:

In this case remove /oaa-policy from the <PolicyUrl>, for example use https://<host>:<port>/policy/config/property/v1 not https://<host>:<port>/oaa-policy/policy/config/property/v1

Consider the following example of configuring an OAA property using the CURL command. The example below assumes OAA accesses the internet through a proxy server:

curl --location -g --request PUT 'https://<PolicyUrl>/policy/config/property/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \
--data '[
{
"name": "bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.proxyProtocol",
"value": "https"
},
{
"name": "bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.proxyHost",
"value": "proxy.example.com"
},
{
"name": "bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.proxyPort",
"value": "80"
},
{
"name": "bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.pushPreferencesEndpoint",
"value": "https://oaainstall"
},
{
"name": "bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.challengeAnswerEndpoint",
"value": "https://oaainstall"
},
{
"name": "bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.retrycount",
"value": "50"
},
{
"name": "bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.google.firebase.senderId",
"value": "58213467743"
}
]'

For details about finding the PolicyUrl and authenticating, see OAA Admin API.

For details about the REST API, see Configuration Properties REST Endpoints.

11.12.1.2.3 Copying the Service Account JSON File to OAA

This section provides information on how to store the service account json file in OAA.

The service account json file downloaded in Creating a Google Firebase Project Enabled for Google Cloud Messaging must be copied to the <NFS_VAULT_PATH> which maps to /u01/oracle/service/store/oaa.

To copy the file to a file based vault, perform the following steps:
  1. Create a directory in the NFS volume <NFS_VAULT_PATH>:
    cd <NFS_VAULT_PATH>
$ mkdir -p ChallengeOMAPUSH/gcm
$ cp service-account.json <NFS_VAULT_PATH>/ChallengeOMAPUSH/gcm
$ sudo chmod 444 <NFS_VAULT_PATH>/ChallengeOMAPUSH/gcm/service-account.json
  2. Edit the <NFS_CONFIG_PATH>/installOAA.properties file and update the common.deployment.push.gcmjsonfile as follows and save the file:
    common.deployment.push.gcmjsonfile=/u01/oracle/service/store/oaa/ChallengeOMAPUSH/gcm/service-account.json

    Note:

    /u01/oracle/service/store/oaa/ChallengeOMAPUSH/gcm/service-account.json is the internal mapping to <NFS_VAULT_PATH>/ChallengeOMAPUSH/gcm/service-account.json.
  3. Edit the <NFS_LOG_PATH>/status.info and set the following vault parameters to false and save the file:
    VAULTINSTALL=false
VAULTCHECK=false
  4. Enter the OAA management container, for example:
    kubectl exec -n oaans -ti oaamgmt-oaa-mgmt-7dfccb7cb7-lj6sv9 --
    /bin/bash
    This will take you into a bash shell inside the OAA management pod:
    oracle@oaamgmt-oaa-mgmt-7dfccb7cb7-lj6sv /]$
  5. Inside the OAA management pod bash shell, run the OAA.sh script to pick up the common.deployment.push.gcmjsonfile configuration:
    cd ~
./OAA.sh -f installOAA.properties
  6. Once the update to the deployment is successful, see Registering the User Account with Oracle Mobile Authenticator for Android.

11.12.1.3 Registering the User Account with Oracle Mobile Authenticator for Android

This section provides information about how to register the user account within the OMA application.

Perform the following steps:

Note:

The steps below can also be found in Configuring Push Notification Challenge with Oracle Mobile Authenticator in the Oracle Advanced Authentication Self-Service Portal.
  1. Log in to the Self-Service Portal at https://<SpuiUrl>.
  2. Under Authentication Factors, select Add Authentication Factor, and then OMA Push Notification Challenge.
    The Add Mobile Device screen appears.
  3. Open the signed OMA app on the Android device.
  4. Click Add Account +.
    This will launch the camera on your Android device.
  5. Use the camera to scan the QR code on the screen.
    The Login Required screen appears.
  6. Do the following:
    1. In the Username field, enter the user name displayed on the Self-Service Portal screen as the user name is case sensitive.
    2. In the PIN code field, enter the PIN code displayed on the Self-Service Portal screen.
  7. Click Sign in and accept the certificate if prompted.
    The account is successfully added in OMA.
  8. On the Self-Service Portal screen, click Done.
The OMA Push Notification Challenge for the registered device appears in the Self-Service Portal.

Next Steps: Accessing a Protected Application Using Android Push Notification.

11.12.1.4 Accessing a Protected Application Using Android Push Notification

To test the push notification you must access a protected application.

Perform the following steps to access a protected application:
  1. Access the protected application. For example, https://www.example.com/application.
    The OAA challenge choice screen appears.
  2. Under OMA Push Notification Challenge, select Approve login on device <DeviceID>.
    You are redirected to the PUSH screen where a notification should appear on your Android device.
  3. Select Allow on the device to login.
If authentication is successful, you are redirected to the protected page.