Configuring Oracle Mobile Authenticator Push Notification for iOS

11.12.2 Configuring Oracle Mobile Authenticator Push Notification for iOS

OAA now allows you to configure push notification for the OMA app for iOS.

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

Push notifications are sent to the iOS device through Apple's Push Notification service (APNS). This requires an Apple Push notification certificate, which is only generated from the Apple Developer's Console.

The standard OMA application installed directly from the Apple App Store do not support push notifications for OAA login attempts. The push notification certificate generated from the Apple Developer Console is tied directly to the OMA application. Therefore, a custom OMA application must be built and signed by the same certificate to receive push notifications.

When you register the iOS device with OAA, a device ID is stored for the user (visible from Self-Service Portal) and this is used to identify the desired recipient.

Apple push notification certificates are built/signed by Apple specifically for their production or development servers. A development certificate cannot be used to send push notifications to the production APNS server and vice-versa. If using an APNS production certificate, you must request this from Apple and use it in the APNSCertificate.jks. This certificate is then used to sign the custom built OMA application. Likewise, if you are using an APNS development certificate, then you must request this from Apple and use it in the APNsCertificate.jks, which is then used to sign the custom built OMA application.

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 iOS:

11.12.2.1 Creating an Apple iOS Certificate, App ID, Bundle Identifier, and Keystore

Learn to create an Apple iOS Certificate, App ID, Bundle Identifier, and Keystore.

See document ID 2319759.1 in My Oracle Support for instructions to create an Apple iOS Certificate, App ID, Bundle Identifier, and Keystore.

After completing the steps mentioned in document ID 2319759.1, you must return to this documentation for further instructions.

11.12.2.2 Copying the APNS Java Key Store to OAA

After creating the APNSCertificate.jks file, you must copy this file 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:

Create a directory in the NFS volume <NFS_VAULT_PATH>:

$ cd <NFS_VAULT_PATH>
$ mkdir -p ChallengeOMAPUSH/apns
$ cp APNSCertificate.jks <NFS_PATH>/ChallengeOMAPUSH/apns
$ sudo chmod 444 <NFS_VAULT_PATH>/ChallengeOMAPUSH/apns/APNSCertificate.jks

Note:

You can copy the APNSCertificate.jks to any location inside the <NFS_VAULT_PATH>, however you must change the property bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.apns.keystorePath to point to the directory where the file is copied to. See Configuring OAA Properties for iOS Push Notification.

11.12.2.3 Configuring OAA Properties for iOS Push Notification

You must set up some OAA properties that are required for configuring push notification for iOS devices.

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

Table 11-7 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.apns.keystorePath	The location of the APNSCertificate.jks keystore.	/u01/oracle/service/store/oaa/ChallengeOMAPUSH/apns/APNSCertificate.jks
bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.apns.keystorePass	The keystore password.	<password>
bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.apns.h2Topic	The APNS App ID created on the Apple Developer console.	com.example.MyApp

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.apns.keystorePath",
"value": "/u01/oracle/service/store/oaa/ChallengeOMAPUSH/apns/APNsCertificate.jks"
},
{
"name": "bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.apns.keystorePass",
"value": "<password>"
},
{"name": "bharosa.uio.default.challenge.type.enum.ChallengeOMAPUSH.apns.h2Topic",
"value": "com.example.MyApp"}
]'

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

11.12.2.4 Registering the User Account with Oracle Mobile Authenticator for iOS

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

Perform the following steps:

Log in to the Self-Service Portal at https://<SpuiUrl>.
Under Authentication Factors, select Add Authentication Factor, and then OMA Push Notification Challenge.
The Add Mobile Device screen appears.
Open the signed OMA app on the iOS device.
Click Add Account +.
This will launch the camera on your iOS device.
Use the camera to scan the QR code on the screen.
The Login Required screen appears.
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.
Click Sign in and accept the certificate if prompted.
The account is successfully added in OMA.
On the Self-Service Portal screen, click Done.

The OMA Push Notification Challenge for the registered device appears in the Self-Service Portal.

11.12.2.5 Installing the Oracle Mobile Authenticator

The standard OMA application installed directly from the Apple App Store does not support push notifications for OAA login attempts.

The push notification certificate generated from the Apple Developer Console is tied directly to the OMA application. Therefore, you must build a custom OMA application and get it signed by the same certificate to receive push notifications.

See document ID 2319759.1 in My Oracle Support for instructions on how to create this custom OMA application.

11.12.2.6 Accessing a Protected Application Using iOS Push Notification

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

Perform the following steps to access a protected application:

Access the protected application. For example, https://www.example.com/application.
The OAA challenge choice screen appears.
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 iOS device.
Select Allow on the device to login.

If authentication is successful, you are redirected to the protected page.