Introducing the Adaptive Authentication Service

35 Introducing the Adaptive Authentication Service

The Adaptive Authentication Service offers stronger multifactor (also referred to as second factor) authentication for sensitive applications that require additional security in addition to the standard user name and password type authentication.

Multifactor authentication involves more than one stage when verifying the identity of an entity attempting to access services from a server or on a network. For example, when multifactor authentication is enabled and configured, the traditional user name and password is the first factor. Additional security is enforced by adding a One Time Pin (OTP) step, or an Access Request (Push) Notification step as a second factor in the authentication process.

The following topics describe how the Adaptive Authentication Service and Access Manager Second Factor Authentication:

35.1 About Adaptive Authentication Service

The Adaptive Authentication Service offers the ability to add multiple steps to the authentication process.

Additional security may be enforced by adding a OTP step, or an Access Request (Push) Notification step after initial user authentication. This may or may not involve the use of the Oracle Mobile Authenticator, a mobile device app that uses Time-based One Time Password and push notifications to authenticate users within the second factor authentication scheme.

Note:

Installing Oracle Adaptive Access Manager is not required since the Adaptive Authentication Service uses a set of libraries that makes a OTP step feasible using the Oracle Mobile Authenticator.

The Adaptive Authentication Service has to be licensed and explicitly enabled in order to use it. Once the proper product license is procured you can enable the Adaptive Authentication Service using the Oracle Access Management Console. From the Oracle Access Management Console, the Adaptive Authentication Service can be enabled or disabled from the Available Services link on the Configuration Launch Pad.

35.2 Working with the Adaptive Authentication Service

The Adaptive Authentication Service offers second factor authentication. The second factor can be a One Time Pin (OTP) or an Access Request (or push) Notification. After an initial successful user/password authentication, a Second Factor Authentication page is displayed from which the user selects the preferred method of second factor authentication.

The following options are available:

OTP from Oracle Mobile Authenticator
OTP through SMS
OTP through Email
Access Request Notification from Oracle Mobile Authenticator

Figure 35-1 shows the Second Factor Authentication page in which the user has selected the OTP Through Email option.

In this case, the user receives the OTP via a configured Email address.

Figure 35-1 Second Factor Authentication Preferred Method Page

Description of "Figure 35-1 Second Factor Authentication Preferred Method Page"

If the selected option is either OTP From Oracle Mobile Authenticator or Access Request Notification from Oracle Mobile Authenticator, the Adaptive Authentication Service works in tandem with the Oracle Mobile Authenticator (OMA), a mobile device app that uses Time-based One Time Password and push notifications to authenticate users within the second factor authentication scheme.

In advance of using the OTP from OMA or Access Request Notification from OMA options, a user must download a supported authenticator app to a mobile device (for example, Oracle Mobile Authenticator to an Apple iPhone) and configure it by clicking a link provided by the Access Manager administrator. (The OMA app is not needed if using the OTP through Email or OTP through SMS options.)

Note:

You must configure the Oracle Mobile Authenticator mobile device app to retrieve a secret key required to generate a OTP.

See Generating a Secret Key for the Oracle Mobile Authenticator for information about the secret key.

See Understanding Oracle Mobile Authenticator Configuration for information on how to configure the OMA.

The following topics describe each option and how the Oracle Mobile Authenticator works:

35.2.1 Understanding the One Time Password Option

After the successful authentication of initial credentials, the user needs to choose one of the OTP options as a second-factor authentication. Access to the protected resource is provided when the OTP received by the user is entered in the OTP login page.

Let's assume the Adaptive Authentication Service is enabled and configured for second factor authentication. When the user accesses a resource protected by Access Manager, a page is displayed that requests a user name and password. If these initial credentials are authenticated successfully, a Second Factor Authentication Preferred Method Page page is displayed and the user selects from one of the options. In this use case, the user selects one of the OTP options and receives a OTP through SMS/Email or generated and displayed by the OMA app. The user enters the OTP in the OTP login page.

Figure 35-2 shows the OTP login page.

Figure 35-2 One Time Password Login Page

Description of "Figure 35-2 One Time Password Login Page"

Once the OTP is successfully validated by Access Manager, the user is directed to the protected resource. On failure of any of the OTP options, an error message will be displayed, and the user will be returned to the same OTP page.

Note:

Access Manager validates the OTP using the Time-based One Time Password (TOTP) algorithm. TOTP is a two-factor authentication scheme specified by the Internet Engineering Task Force (IETF) under RFC 6238 and used by the Adaptive Authentication Service. TOTP is an extension of the HMAC-based One Time Password algorithm and supports a time-based moving factor (a value that must be changed each time a new password is generated).

The following topics describe how the user may receive the OTP:

35.2.1.1 About using OTP through Email or SMS

The user receives the OTP through an email or SMS and enters it in the OTP login page.

In cases where OTP through email or SMS is chosen, Access Manager will send a OTP to the configured email address or phone number respectively. The user then enters the received OTP and Access Manager will validate it. On a successful validation, the user will be directed to the protected resource.

The Adaptive Authentication Service expects that the required email address or phone number is configured in the appropriate field.

See Configuring the Adaptive Authentication Plug-in in the Oracle Access Management Console.

When you use the OTP with Email or SMS option, the OTP is accessible from any device on which the email address can be accessed or from the SMS app that is associated with the specified phone number, respectively.

Note:

The OMA mobile app is not used for the OTP through Email or OTP through SMS options.

35.2.1.2 About using OTP from Oracle Mobile Authenticator

In the use case where a OTP will be generated and displayed by the OMA app on a mobile device, the app must be configured with the Access Manager server details.

Following this configuration, the user authenticates with Access Manager using the proper credentials and Access Manager will return a secret key. This secret key is unique to each user and known only to Access Manager and the OMA. The secret key is used to generate the OTP.

See Generating a Secret Key for the Oracle Mobile Authenticator on how to populate the secret key with the required data.

After Access Manager generates a OTP for the user using the secret key, the OTP is pushed to the OMA. The user then enters the OTP in the One Time Pin Login Page. If the OTP generated by Access Manager matches the OTP entered by the user, access to the protected resource is allowed. If the OTP entries do not match, access is not allowed.

See Using the Oracle Mobile Authenticator with OTP And Access Request.

Note:

The OMA refreshes the OTP every 30 seconds so the OTP entered by a user is valid only for that period of time.

35.2.2 Understanding the Access Request (Push) Notification Option

The Access Manager sends an Access Request Notification to the notification server which is then pushed to the user’s configured device.

Let's assume the Adaptive Authentication Service is enabled and configured for second factor authentication. When the user accesses a resource protected by Access Manager, a page is displayed that requests a user name and password. If these initial credentials are authenticated successfully, a Second Factor Authentication Preferred Method page is displayed and the user selects from one of the options. In this use case, the user selects Access Request Notification from Oracle Mobile Authenticator.

Note:

This is a push notification option which works in tandem with the OMA.

See Using the Oracle Mobile Authenticator with OTP And Access Request.

Figure 35-3 shows the Second Factor Authentication Preferred Method Page with Access Request Notification that has been selected.

Figure 35-3 Access Request Notification Preferred Method Page

Description of "Figure 35-3 Access Request Notification Preferred Method Page"

When the user selects Access Request Notification from the Second Factor Authentication Preferred Method Page, Access Manager sends an Access Request Notification to either the Apple Push Notification Server or the Google Notification Server depending upon the user's configured device. The notification server then pushes a notification to the mobile device and the user will approve or deny it. Based on a successful response, the user will be directed to the protected resource. On failure, an error message will be displayed and the user will be returned to the same OTP page.

Figure 35-4 shows the Access Request Notification message that is displayed during this process.

Figure 35-4 Access Request Notification Wait Screen

Description of "Figure 35-4 Access Request Notification Wait Screen"

35.2.3 Using the Oracle Mobile Authenticator with OTP And Access Request

The user downloads the OMA app to the mobile device and configures it to receive the access request notification.

Depending on the selected option, the Adaptive Authentication Service will need to work in tandem with the Oracle Mobile Authenticator (OMA), a mobile device app that uses Time-based One Time Password and push notifications to authenticate users with the second factor authentication scheme. To receive the OTP or Access Request Notification using the OMA, a user downloads it to an Apple or Android mobile device and configures it by clicking a link provided by the Access Manager administrator. Access Manager and OMA must share a secret key.

See Generating a Secret Key for the Oracle Mobile Authenticator about the secret key.

See Understanding Oracle Mobile Authenticator Configuration on how to configure OMA.

Note:

The OMA app is not needed if using the OTP through Email or OTP through SMS options.

See About using OTP through Email or SMS.

35.3 Understanding Adaptive Authentication Service and OMA Configurations

You need to configure the Adaptive Authentication Service and, depending on the option, the OMA.

To configure the Adaptive Authentication Service, perform the following procedures:

35.4 Configuring an Adaptive Authentication Service

You can configure an Adaptive Authentication Service if you have already installed Access Manager, a WebGate, and Oracle HTTP Server (OHS).

Some of these configurations are specific to one or the other Adaptive Authentication Service options.

This section describes the following topics:

35.4.1 Generating a Secret Key for the Oracle Mobile Authenticator

A secret key needs to be shared between Access Manager and the OMA app. Businesses can generate secret keys in different ways so the means in which the secret key is generated is not important.

The following RESTful endpoint is used to generate the secret key for a user in the Oracle Access Management identity store.

http://<HOST>:<PORT>/oauth2/rest/resources/secretkey HTTP/1.1

Where, <HOST> and <PORT> are those of the OAM server.

In the case of OMA online configuration (which is Oracle's recommended method of configuration), OMA uses the RESTful endpoint to store the key for a user in the identity store. In the cases of OMA manual configuration or Google Authenticator, the administrator sets up a web application which allows the user to generate a secret key also using above mentioned RESTful endpoint. The secret key is stored as a String in an LDAP attribute in the identity store and the name of this attribute must is passed to the business in the RESTful endpoint configuration before they generate the secret key.

See Understanding Oracle Mobile Authenticator Configuration.

35.4.2 Configuring Oauth Services to enable the Secret Key API

There are three parts to enabling the Secret Key API.

The first part is to enable the secret key endpoint. The second part deals with enabling OAM configuration to enable the use of Time-based One-Time Password (TOTP). The third part deals with setting up OAM to produce a TOTP for a particular user Account.

To enable the Secret Key API:

Create DefaultDomain with customAttrs as described:

Ensure the following point to the same LDAP.
- Authentication module. For example, LDAPScheme in the application domain
- AdaptiveAuthenticationModule. For details, seeCreating an Authentication Policy
- AdaptiveAuthenticationPlugin
- Default store. For example, User Identity Store under configuration in the OAM console.

Create DefaultDomain with customAttrs as shown. The following example shows OID as the identity store.

curl -u username:password -X POST
http://<Host>:<Port>/oam/services/rest/ssa/api/v1/oauthpolicyadmin/oauthidentitydomain -H 'content-type: application/json' -d
'{"name":"DefaultDomain","identityProvider":"OID","enableMultipleResourceServe
r":false,"description":" Test
Domain","tokenSettings":[{"refreshTokenEnabled":true,"refreshTokenLifeCycleEna
bled":true,"refreshTokenExpiry":5400,"lifeCycleEnabled":true,"tokenType":"ACCE
SS_TOKEN","tokenExpiry":1800},{"refreshTokenEnabled":true,"refreshTokenLifeCyc
leEnabled":true,"refreshTokenExpiry":10800,"lifeCycleEnabled":true,"tokenType"
:"AUTHZ_CODE","tokenExpiry":240}],
"customAttrs":"{\"keyAttributeName\":\"description\"}"}'
Sucessfully created entity - OAuthIdentityDomain, detail - OAuth Identity
Domain :: Name - DefaultDomain, Id - 5c75aeece3154fdc9af691e21b70b1b9,
Description - Test Domain, TrustStore Identifiers -
[DefaultDomain], Identity Provider - OID, TokenSettings -
[{"tokenType":"SSO_LINK_TOKEN","tokenExpiry":3600,"lifeCycleEnabled":false,"re
freshTokenEnabled":false,"refreshTokenExpiry":86400,"refreshTokenLifeCycleEnab
led":false},
{"tokenType":"ACCESS_TOKEN","tokenExpiry":1800,"lifeCycleEnabled":true,"refres
hTokenEnabled":true,"refreshTokenExpiry":5400,"refreshTokenLifeCycleEnabled":t
rue},
{"tokenType":"AUTHZ_CODE","tokenExpiry":240,"lifeCycleEnabled":true,"refreshTo
kenEnabled":true,"refreshTokenExpiry":10800,"refreshTokenLifeCycleEnabled":tru
e}], ConsentPageURL - /oam/pages/consent.jsp, ErrorPageURL -
/oam/pages/servererror.jsp, CustomAttrs -
{"keyAttributeName":"description"}

Note:

Ensure that the attribute Name used is not used for other purposes

To delete a domain, use the following command:

curl -u username:password -X DELETE
http://<Host>:<Port>/oam/services/rest/ssa/api/v1/oauthpolicyadmin/oauthidentitydomain?name=DefaultDomain

For information on parameters used in the command to create an identity domain , See Creating an Identity Domain

Test with Sample User that you are able to generate Secret Key. For example:
Method 1
1. Create the following HTML file:
```
<html>
    <head>
        <title>Oracle Mobile Authenticator</title>
    </head>
    <body>
        <a href="oraclemobileauthenticator://settings?LoginURL::=http://<Host>:<ManagedServerPort>/oauth2/rest/resources/secretkey">
          Click Here
        </a>
    </body>
</html>
```
2. Open this HTML page on your mobile device, on which you have the OMA app installed.
3. Click on Click Here
4. Enter the username and password of the user to access the protected resource
5. The user is automatically added to the OMA app and the secret key is created. You will now start seeing OTP messages on OMA app on the mobile device.
Method 2
1. Irrespective of whether the user is in OID or Useridentitystore1, create a secret key and then manually enter it in the OMA app on the mobile device.
```
curl -u username:password  -X POST http://<Host>:<Port>/oauth2/rest/resources/secretkey 
-H 'cache-control: no-cache' -H 'content-type:application/x-www-form-urlencoded' 
-H 'x-oauth-identity-domain-name:DefaultDomain' 
{"secret_key": "PTBHAITFH25W3BOD"}
```
2. Open the OMA app on your mobile device
3. Click the + sign to add an account
4. Click Enter key manually
5. Type the key manually.

35.4.3 Configuring the Adaptive Authentication Plug-in in the Oracle Access Management Console

Access Manager provides the Adaptive Authentication Plug-in that you can use for two-factor authentication.

To configure the Adaptive Authentication plugin in the Oracle Access Management Console:

Log into the Oracle Access Management Console as System Administrator.
From the Application Security Launch Pad, click Authentication Plug-ins in the Plug-ins panel.
From the Authentication Plug-in tab, type Adaptive in the quick search box above the Plug-in Name column and hit Enter.

The AdaptiveAuthenticationPlugin is displayed.

Change the properties displayed under Plug-in Details: AdaptiveAuthenticationPlugin as applicable to your environment.

Table 35-1 describes the Adaptive Authentication Plugin properties.

Table 35-1 Adaptive Authentication Plugin Properties

Property	Description	Default Value	Required for Challenge Method
IdentityStoreRef	Identity store name	Default_Store	All
TotpSecretKeyAttribute	Name of the user attribute in which the secret key is stored.	Attribute description	OTP using OMA, Time based OTP
TotpTimeWindow	The number of OTP codes generated by the mobile device that Access Manager will accept for validation. Since the mobile device generates a new OTP every 30 seconds, if the value is 3, Access Manager will accept the current and last three OTPs generated by the mobile device.	3	OTP using OMA, Time based OTP
PushAPNsProdServer	If set to true, the APNS production server will be used to send notifications.	false	Access Request Notifications (iOS)
PushProxyHost	Name of the proxy host if notifications are to sent to the server using a proxy.		Access Request Notifications
PushProxyPort	Proxy port if notifications are to sent to the server using a proxy.	80	Access Request Notifications
PushProxyProtocol	Proxy protocol	https://	Access Request Notifications
UmsAvailable	When Adaptive Authentication Service requires UMS to send Email and SMS, set to true.	false	SMS, Email
UmsClientUrl	URL of UMS web service		SMS, Email
PhoneField	Attribute in the identity store where the user phone number is stored	mobile	SMS
EmailField	Attribute in the identity store where the user email address is stored	mail	Email
Totp_Enabled Email_Enabled Sms_Enabled Push_Enabled	Controls the options displayed in the UI. If enabled and user is not registered for Push, not setup for TOTP, or doesn't have email/phone populated in id store, those options won't be displayed. For example if user has not registered for TOTP and Push but has email populated then Email will be the only option shown.	true NOTE: Properties should be set to false only when the Administrator wants to disable a particular feature for all users.
OTP REST Configuration Options
ValidateAnyPin	If `true`, user can submit any pin that has been generated for that user, if it is still valid. Pin is valid if it has not been successfully used and has not expired. If `false`, user can submit only the pin that matches the `correlationId` being submitted in order to validate the pin.	false
MaxAttempts	Maximum attempts for a user to validate the pin. If `MaxAttempts` is exceeded, user must be reset. Value of 0, means no limit.	0
MaxPins	Maximum number of pins to store for a single user. If more pins are requested after the maximum is reached, the oldest pin is replaced.	5
VerboseOutput	If `true`, the REST output includes detailed information about errors. If `false`, the REST output includes minimal information about errors.	true
pinExpiry	Availability of One Time Pin (OTP). The unit of measurement is a millisecond. The `pinExpiry` field in the `AdaptiveAuthenticationPlugin` governs the expiry of the Email/SMS OTP codes.	300000	SMS, Email

Note:

In addition to the properties (related to OTP generation in Adaptive Autentication plugin) specified in Table 35-1, you can override settings in oam-config.xml by adding them to the ConfigParams section of the OAMMFAOTP definition.

This also allows for app-specific configuration by adding app as a prefix to the property name. For example, "app1.ValidateAnyPin" sets and validates any pin setting specifically for app1 without affecting the configurations for other applications.

Click Save.
Update the same properties as applicable in the AdaptiveAuthenticationModule by clicking Authentication Modules under Plug-ins in the Access Manager Launch Pad.

From the Authentication Modules tab, search for AdaptiveAuthenticationModule.

Table 35-1 does not list all available Adaptive Authentication Service properties.

35.4.4 Enabling User Lockout During the Multi Factor Authentication Flow

You can lock the user after a fixed number of invalid attempts to login using incorrect PIN, during Second Factor Authentication.

The number of invalid attempts, is based on the value specified in MaxAttempts configured in Adaptive Authentication plugin on the OAM Console.

When user provides incorrect PIN for more than configured MaxAttempts, user account is locked using OAM password schema attributes.

To enable user lock out:

Add the lockoutEnabled property in the oam-config.xml file under the section for AdaptiveAuthenticationPlugin.

For example:


<Setting Name="28" Type="htf:map">
<Setting Name="globalUIOverride" Type="xsd:boolean">false</Setting>
 <Setting Name="instanceOverride" Type="xsd:boolean">false</Setting>
<Setting Name="value" Type="xsd:string">true</Setting>
<Setting Name="name" Type="xsd:string">LockoutEnabled</Setting>
 <Setting Name="length" Type="xsd:integer">100</Setting>
 <Setting Name="mandatory" Type="xsd:boolean">false</Setting>
 <Setting Name="type" Type="xsd:string">string</Setting>
</Setting

For more information about editing the oam-config.xml file, see Updating OAM Configuration

Configure OAM password policy:
1. In the user identity store configuration in the console, enable Password Management
2. Configure the other attributes as required for OAM password policy. For details, see Accessing Password Policy Configuration Page
3. Ensure to extend the schema, as required, if it has already not been imported in the environment:$OAM_HOME/idm/oam/server/pswdservice/ldif/OID_PWDPersonSchema.ldif
4. Ensure that the Authentication module includes PasswordManagementPlugin to evaluate the OAM schema attributes used for locking the user after authentication.

35.4.5 Limiting PIN Generation During the Second Factor Authentication

The number of OTP pins that can be generated before validating one of them is based on the value of the MaxSendAttempts and MaxSendAttemptsLockoutEnabled properties in the Adaptive Authentication plugin on the OAM Console. If the pins generated is more than or equal to the configured MaxSendAttempts, the user account is locked if MaxSendAttemptsLockoutEnabled is set true.

If using LDAP storage, the PinGenerationCountField property should be set to the name of the LDAP attribute used to store the pin generation counter.

To add the new parameters to the Adaptive Authentication plugin:

Export the oam-config.xml file.

Check the index of the latest parameter of the AdaptiveAuthenticationPlugin, for example 43. Then add the following entries:

<Setting Name="44" Type="htf:map">
                      <Setting Name="globalUIOverride" Type="xsd:boolean">false</Setting>
                      <Setting Name="instanceOverride" Type="xsd:boolean">false</Setting>
                      <Setting Name="value" Type="xsd:string">3</Setting>
                      <Setting Name="name" Type="xsd:string">MaxSendAttempts</Setting>
                      <Setting Name="length" Type="xsd:integer">100</Setting>
                      <Setting Name="mandatory" Type="xsd:boolean">false</Setting>
                      <Setting Name="type" Type="xsd:string">string</Setting>
                    </Setting>
                    <Setting Name="45" Type="htf:map">
                      <Setting Name="globalUIOverride" Type="xsd:boolean">false</Setting>
                      <Setting Name="instanceOverride" Type="xsd:boolean">false</Setting>
                      <Setting Name="value" Type="xsd:string">true</Setting>
                      <Setting Name="name" Type="xsd:string">MaxSendAttemptsLockoutEnabled</Setting>
                      <Setting Name="length" Type="xsd:integer">100</Setting>
                      <Setting Name="mandatory" Type="xsd:boolean">false</Setting>
                      <Setting Name="type" Type="xsd:string">string</Setting>
                    </Setting>
                    <Setting Name="46" Type="htf:map">
                      <Setting Name="globalUIOverride" Type="xsd:boolean">false</Setting>
                      <Setting Name="instanceOverride" Type="xsd:boolean">false</Setting>
                      <Setting Name="value" Type="xsd:string">true</Setting>
                      <Setting Name="name" Type="xsd:string">UseUdmStore</Setting>
                      <Setting Name="length" Type="xsd:integer">100</Setting>
                      <Setting Name="mandatory" Type="xsd:boolean">false</Setting>
                      <Setting Name="type" Type="xsd:string">string</Setting>
                    </Setting>                      
                    <Setting Name="47" Type="htf:map">
                      <Setting Name="globalUIOverride" Type="xsd:boolean">false</Setting>
                      <Setting Name="instanceOverride" Type="xsd:boolean">false</Setting>
                      <Setting Name="value" Type="xsd:string">description</Setting>
                      <Setting Name="name" Type="xsd:string">PinGenerationCountField</Setting>
                      <Setting Name="length" Type="xsd:integer">100</Setting>
                      <Setting Name="mandatory" Type="xsd:boolean">false</Setting>
                      <Setting Name="type" Type="xsd:string">string</Setting>
                    </Setting>

Import the oam-config.xml file and restart the admin and managed servers.

35.4.6 Setting Credentials for UMS, iOS, and Android

Use the WLST command line script to set the credentials for the Oracle User Messaging Service (UMS), the iOS certificate or the Android API key.

These credentials are used by the OAM Server in the process of sending SMS/Email and push notifications. Table 35-2 lists information that you need to complete the procedure.

Table 35-2 Server Side Configuration for Adaptive Authentication Service

Configuration	Information	Challenge Method
iOS Certificate/Password	`https://developer.apple.com/library/mac/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html`	Access Request (Push) notification using iOS
API Key	`https://developers.google.com/web/updates/2015/03/push-notificatons-on-the-open-web?hl=en`	Access Request (Push) notification using Android
UMS Credential	UMS credentials that OAM will use to establish the connection to UMS Web service.	Email/SMS

To set credentials for UMS, iOS, and AndroidT:

cd <MW_HOME>/oracle_common/common/bin
./wlst.sh
connect()
Enter the WebLogic user name and password when prompted.
Press Enter to accept the default URL or modify the host and port as necessary and press Enter.
Run one or more of the following commands to set credentials for the UMS server, iOS or Android depending on your deployment.
Note:

Replace <UMS SERVER USER NAME>, <UMS SERVER PASSWORD>, <CERTIFICATE STORE PASSWORD> and <API KEY VALUE> with values specific to your environment. Do not change the values for any parameters in these commands but those listed and marked as variables.
- For OTP for email/SMS only:
```
createCred(map="OAM_CONFIG", key="umsKey", user="<UMS SERVER USER NAME>", 
  password="<UMS SERVER PASSWORD>")
```
  For example:
```
createCred(map="OAM_CONFIG", key="umsKey", user="weblogic", 
  password="password")
```
- For Access Request (Push) Notifications on iOS only:
```
createCred(map="OAM_CONFIG", key="pushApnsCertKey", user="apnskey", 
  password="<CERTIFICATE STORE PASSWORD>") 
```
  For example:
```
createCred(map="OAM_CONFIG", key="pushApnsCertKey", user="apnskey", 
  password="password")
```
  See Creating a Java KeyStore for iOS Access Request (Push) Notifications when using iOS.
- For Access Request (Push) Notifications on Android only:
```
createCred(map="OAM_CONFIG", key="omaApiKey", user="omaApiKey", 
  password="<API KEY VALUE>")
```
  For example:
```
createCred(map="OAM_CONFIG", key="omaApiKey", user="omaApiKey", 
  password="ADDGFDGDFGRTERSDFSDFSDFTYERTERTASDASDASD")
```
Verify the keys by logging into Fusion Middleware Control, navigating to Domain > Security > Credentials, and checking the OAM_CONFIG map for the keys input using the commands.

Note:

For information on how to update, delete or otherwise manage credentials using Fusion Middleware Control, see Securing Applications with Oracle Platform Security Services.

35.4.7 Creating a Java KeyStore for iOS Access Request (Push) Notifications

When using Access Request Notifications on iOS, create a Java KeyStore (JKS) by using the cert file and key file.

Once the JKS is created, rename it as APNsCertificate.jks and put it in the <domain>/config/fmwconfig directory of the Oracle Access Management installation. The JKS should contain the user's locally generated private key and the Apple Push Notification service (APNs) certificate downloaded from the Apple Developer Center.

The following sample commands generate and import the certificate:

openssl x509 -in aps_production.cer -inform DER -out aps_production.pem 
 -outform PEM

openssl pkcs12 -nocerts -in OMAKey.p12 -out OMAKey.pem

openssl pkcs12 -export -inkey OMAKey.pem -in aps_production.pem 
 -out iOS_prod.p12

keytool -import -keystore APNsCertificate.jks -file aps_production.cer 
 -alias PushCert

keytool -importkeystore -destkeystore APNsCertificate.jks 
 -deststoretype JKS -srcstoretype PKCS12 -srckeystore iOS_prod.p12

These commands assume:

aps_production.cer to be the name of the APNs certificate downloaded from the Apple Developer Center.
OMAKey.p12 is the user's locally generated private key.

Also see Setting Credentials for UMS, iOS, and Android.

Note:

The section Maintain Your Certificates, Identifiers, and Profiles at the following Apple URL provides relevant information about app distribution certificates and APNs. https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/Introduction/Introduction.html

35.4.8 Configuring Push Notifications on Mobile Device

This section provides steps to configure push notifications on a mobile device

35.4.8.1 Configuring Host Name Verifier for Android Access Request (Push) Notifications

If you are setting up Android for Access Request notification, use the WebLogic console to update the WebLogic Managed Server for host name verification.

This step is required for Access Request notification configuration on Android only. It allows the verification of host names represented using wildcards; for example, *.googleapis.com.

To configure host name verifier for Android access requests (push) notifications:

Navigate to base_domain -> Summary of Environment -> Summary of Servers -> oam_server1.
Click the SSL tab.
Expand Advanced and select the Hostname verification entry to configure the Hostname Verifier.
Enter weblogic.security.utils.SSLWLSWildcardHostnameVerifier as the Custom Hostname Verifier.
Click Save.
Restart the oam_server1.

35.4.8.2 Creating OTPRestUserGroup and Modifying OAMMFAOTP

Create a group with the name OTPRestUserGroup and add the user member of this group to the LDAP used.

Export the oam-config.xml file from the database. See Updating OAM Configuration for details.
Change the LDAP store to the current LDAP store. That is, change the value of UserIdentityStore1 from the following setting to the same LDAP name as provided in User Identity Store section in the oamconsole.
```
<Setting Name="OAMMFAOTP" Type="htf:map">
...
...
  <Setting Name="UserStore" Type="xsd:string">UserIdentityStore1</Setting>
```
Import the oam-config.xml. See Updating OAM Configuration for details.
Restart admin and managed servers.

35.4.8.3 Verifying Push Notification Settings

Verify the push notification settings in the AdaptiveAuthenticationModule and AdaptiveAuthenticationPlugin

Login to the OAM console and navigate to the authentication modules section. Search for the AdaptiveAuthenticationModule and edit the following parameters in the Steps tab:
- Ensure that the SFATypes includes Push.
- Ensure that Push_Enabled is set to true.
- Set the IdentityStoreRef to the name of the IDS profile that was created.
  
  Note:
  This needs to include IDSPROFILE- as a prefix. For example, if the IDS profile created is called OUD then enter the value as IDSPROFILE-OUD.
- Ensure that the PushProxyHost, PushProxyPort, and PushProxyProtocol are set correctly, if the OAM managed server needs to make a proxy server connection to reach the Google servers.
In the OAM console, navigate to the authentication plugins section. Search for the AdaptiveAuthenticationPlugin and make sure the same parameters and values from the previous step are reflected in the plugin too.

Note:
In some cases OAM uses the authentication module and in some cases uses the plugin, so setting the same values in both ensures that the correct settings are used.

35.4.8.4 Creating an Authentication Policy

Create an authentication policy to protect the resource that contains the post-authentication rule to switch to the AdaptiveAuthentication scheme.

The adaptive authentication scheme needs to piggy-back on top of the existing LDAPScheme. The end-user will authenticate with a username/password and then a post-authentication rule will engage to "switch" to the AdaptiveAuthenticationScheme. Create the protected resource to use the authentication scheme LDAPScheme and then define a post-authentication rule to "switch" to the AdaptiveAuthenticationScheme. For example the below condition "3>2" is always true so all resources protected by this authentication policy will display the above SFA page.

35.4.8.5 Connecting with Messaging Server

Create a Google firebase project enabled for Google Cloud Messaging (GCM).

To send a push notification to the mobile device, OAM connects to the Google cloud messaging servers and delivers the notification to Google, which then delivers the notification to the mobile device. Google cloud messaging requires that a Google firebase project be created. The following informtaion details how to create a Google project.

Note:

The steps to create a firebase project are specific to Google and may change over time.

Login to the Google firebase console at https://console.firebase.google.com/u/0/.
Click the Add Project button and specify a name for the project. The name can be any text as it is not used by OAM. For example, OMA-OAM.
Navaigate to the project settings by clicking the gears icon next to the project name in the upper left-hand part of the browser.
Click on the Cloud Messaging option in the blue bar and make note of the Sender ID and Server Key, which is required in the later steps.

Note:
Note that Google indicates that the legacy server key will work for some period of time. However, it is recommended that you use the longer server key.

35.4.8.6 Setting the GCM API key within the OAM Credential Store

The server key from the Google project needs to be saved within the OAM credential store so that OAM can use it along with the sender ID to make a connection to the GCM servers.

Create a new key using WLST as described:

Navigate to the $MW_HOME/oracle_common/common/bin directory and run wlst.sh command to connect to the AdminServer.
Run the following command to create a new key called omaApiKey, where the password value is the server key from the Google project created.
```
createCred(map="OAM_CONFIG", key="omaApiKey", user="omaApiKey",
password="<API KEY VALUE>")
```
Note:
If the omaApiKey credential already exists then you can edited the key from within the EM console.
1. Navigate to Farm_base_domain/WebLogic Domain/<domain name>
2. Right-click and select Security/Credentials.
3. Expand the OAM_CONFIG key and click on the omaApiKey to edit it with a new value

35.4.8.7 Installing the Google CA Files into the OAM Keystore

Google uses the GlobalSign certificate authority, therefore, the CA root certificates must be loaded into the trust keystore used by the OAM managed server.

The OAM server makes an SSL connection to the GCM server to send push notifications.

By default, OAM uses the MW_HOME/wlserver_10.3/server/lib/DemoTrust.jks keystore.

Collect the root certificates needed by running the following command. This returns the certificate chain that can be used to build files to load into the OAM keystore.
```
openssl s_client -connect android.googleapis.com:443 -showcerts
```

Once the certificate files are available load them into the MW_HOME/wlserver_10.3/server/lib/DemoTrust.jks keystore using the following command:

cd MW_HOME/wlserver_10.3/server/lib
keytool -importkeystore -srckeystore trust.jks -destkeystore DemoTrust.jks
-srcstorepass <password> -deststorepassDemoTrustKeyStorePassPhrase

Verify the presence of all of the certificates by running the following command
```
-keystore DemoTrust.jks -storepass DemoTrustKeyStorePassPhrase -storetype
jks'
```
Restart the OAM server to re-read the keystore files.

Note:

Google maintains a webpage related to their CA certificates. See https://pki.google.com for details.

35.4.8.8 Creating a Webpage to Deliver the OMA Application Profile to the Mobile Device

By default, the OMA application has no connections to an OAM server. A user-profile must be generated to connect the OMA application to an OAM server.

To connect the OMA application to an OAM server, load a configuration settings file into OMA.

Create an HTML file that contains a link to the configuration settings. This way the mobile device can access the web page in its browser and this will launch the OMA application automatically to configure the profile. For push notifications, the configuration settings need to include the following parameters:
- ServiceName - Defines the name of the profile as it will be shown in the OMA application on the mobile device.
- ServiceType - Defined whether to enable OTP or push notification or both. For push notifications, the type needs to be Notification
- PushPreferencesEndpoint - Where push notification preferences must be sent, for example, to save the mobile device identification information.
- ChallengeAnswerEndpoint - Where push notification responses must be sent, for example, to relay the allow/deny action by the user.
- SenderID - The sender ID retrieved from the Google firebase project that was created. Note that the sender ID is different than the server key. The sender ID is used here in the configuration file while the server key is set as the omaApiKey in the credential store.
- NotificationAuthServerType - The only supported value is HTTPBasicAuthentication
```
<html>
  <head>
    <title>OMA Configuration</title>
  </head>
  <body>
    <a href="oraclemobileauthenticator://settings?ServiceName
::=Google-OMA-Push&ServiceType::=Notification&PushPreferencesEndpoint
::=http://hostname:14100/oam/services/rest/11.1.2.0.0/oma/Preferences&ChallengeAnswerEndpoint
::=http://hostname:14100/oam/services/rest/11.1.2.0.0/oma/ChallengeResponse&NotificationAuthServerType
::=HTTPBasicAuthentication&SenderID::=xxxx">Google OMA Push</a>
  </body>
</html>
```
Place this HTML file on a webserver that is accessible to the mobile device

Note:
This URL is typically NOT protected by OAM. Since this is a registration link that users will need to register their device for use with second factor authentication, they need to be able to access this device before SFA is setup. The resource can be protected by a webgate, in that case, select an authentication scheme that does not engage the AdaptiveAuthenticationScheme, since the user will not have SFA yet configured for their account.
Install the OMA application onto the mobile device
The Oracle Mobile Authenticator application must to be installed on the device where the push notification are shown. The OMA application is available in both the Google Play Store and the Apple App Store as a free application.
Register the user account within the OMA application
The user must open a browser on the mobile device and access the specified OMA configuration settings web page. Since this is a configuration settings for OMA (as identified by oraclemobileauthenticator://settings) the OMA application must open up and ask the end-use to supply the LDAP credentials for OAM login. Once the credentials are validated by OAM the managed server OMA creates an OMA application profile.

Note:
On the mobile device, navigate to Setting > sound & notification > App notifications > Select OMA. Turn on the treat as priority option.

35.4.8.9 Testing SFA through Push Notification

Test the push notification flow by accessing the protected resource and use the step-up authentication scheme to select the type of SFA required.

The user must see the name of the mobile device they are using.

Selecting the Access Request Notification option causes the OAM server to generate a push notification and deliver it to the GCM servers. That must show up on the users mobile device, where the user is asked to allow or deny the access.

By default, the OAM server checks for a user response every eight seconds. The browser briefly flashes as it waits until either the timeout period has passed and the browser displays an error message, or a user response is detected and the browser is redirected appropriately.

35.4.8.10 Troubleshooting Push Notifications

This section provides various errors, fixes, workarounds for troubleshooting the push notifications

Enable Logging

There are several things that can go wrong with this configuration as it relies on communication between the OAM server, Google servers, and a mobile device.

To debug issues the following logging modules must be enabled on the OAM managed server to get detailed output.


oracle.oam.plugin - TRACE:32
oracle.oam.admin.service.config - TRACE:32

Note:

The messages between OAM and GCM are logged only at TRACE:32.

401 Not Authorized Error

If you get a 401 not authorized error, while running the following command:

curl -u username:password -X POST
http://<Host>:<Port>/oam/services/rest/auth/api/v1/mfa/createOTP -H 'content-type: application/json' -d
'{"userId":"user1","appName":"asasas","deliveryChannel":"none"}'
{"correlationId":"1ad7b4bd-4ac9-4960-9da8-a28cc2c8f856","resultCode":"0",
"validTime":"1544092972705","minorCode":"6571511656"}

Check if the directory server is used as the system store (by default, the WebLogic Server embedded directory used by UserIdentityStore1), the group OTPRestUserGroup is created and the user1 is added in this group.

Push Notification is Never Received on the Mobile Device

Check the following:

Ensure the mobile device is not connected to the VPN software.
If the OMA application is not able to connect to the OMA server for an extended period of time.
If the LDAP user account is used for both one-time passwords and push notifications.

Push Notification has Worked Before, but is Not Working Now

Delete the OMA application profile and re-register the user from the OMA application again.

To delete the existing profile long-click the profile name and then once it is highlighted, click the trash can option.

Note:

This only works if push notifications have worked in the past. If the device has never successfully received a push notification then re-registration does not fix the problem and the OAM diagnostic logs must be reviewed.

Note that

User not found in the LDAP directory

During registration of the mobile device, the user is prompted to enter credentials to login. If the user is not found, the following error is seen in the OAM diagnostic log:


<Error> <oracle.oam.user.identity.provider>
<OAMSSA-20142> <Authentication Failure for user user1, user not found in
idstore UserIdentityStore1 with exception
oracle.igf.ids.EntityNotFoundException: Entity not found for the search
filter (&(objectclass=person)(uid=usr1)).>

Note that the idstore listed is UserIdentityStore1. By default, OAM looks for users in the embedded WebLogic LDAP. If the error shows UserIdentityStore1, review the steps in Creating OTPRestUserGroup and Modifying OAMMFAOTP. If the idstore listed is a custom store then check the ldapsearch that is generated to see why the user is not found. Once the push notification is received on the device the end-user needs to choose to allow or deny the login request.

If the user selects the allow option then the OMA application shows the confirmation screen and at the same time communicates back to the OAM managed server to indicate that the user has been permitted access

Once the OAM server receives the approval for login it then redirects to the requested URL.

35.4.9 Configuring Access Manager for VPN in a Use Case

You can configure Access Manager when a user needs to have access to a protected resource with VPN software.

To configure Access Manager for VPN in a use case:

Log into the Oracle Access Management Console as System Administrator.
From the Application Security Launch Pad, click Application Domains in the Access Manager panel.

The Application Domain tab is displayed.
Click Search to display all available Application Domains.
Click the Application Domain name that contains the resource being protected.

The Application Domain opens in a new tab.
Click Authentication Policies in the Application Domain tab.
Click the name of the Authentication Policy that is being used to protect the particular resource for which two factor authentication is being configured.

The appropriate Authentication Policy opens in a new tab.
Click Advanced Rules in the Authentication Policy tab.
Add a new rule by clicking the plus sign (+) under Post Authentication.

The Add Rule dialog is displayed.
Enter a Rule Name and the following jython script.

location.clientIP.startswith('10.')

See Context Data for Advanced Rules.
Select the AdaptiveAuthenticationScheme Authentication Scheme from the If Condition is True drop-down list.

This Authentication Scheme will be used when the defined condition is true.
Click Add and then Apply to complete the procedure.

35.4.10 Administering a Secret Key

Enabling Secret Key Lifecycle

By default OAM only allows to create an OAuth secret key using the user name and password with the BASIC authorization header. It is possible to administer a secret key using an access token with the BEARER authorization header by enabling the Secret Key Lifecycle feature. This is done by using the updateConfigProperty WLST command in ONLINE mode.

The syntax to enable this feature is:

updateConfigProperty(propertyIdentifier="EnableSecretKeyLifecycle",propertyValue="true")

The syntax to disable this feature is:

updateConfigProperty(propertyIdentifier="EnableSecretKeyLifecycle",propertyValue="false")

Creating a Secret Key

To create a secret key use the following REST API:

curl -X POST http://<ManagedServerHost>:<ManagedServerPort>/oauth2/rest/resources/secretkey -H 'Content-Type: application/x-www-form-urlencoded' -H'x-oauth-identity-domain-name: <OAuthIdentityDomain>' -H 'Authorization:Bearer <AccessToken>'

Getting a Secret Key

To retrieve a secret key use the following REST API:

curl -X GET http://<ManagedServerHost>:<ManagedServerPort>/oauth2/rest/resources/secretkey -H 'Content-Type: application/x-www-form-urlencoded' -H'x-oauth-identity-domain-name: <OAuthIdentityDomain>' -H 'Authorization:Bearer <AccessToken>'

Updating a Secret Key

To update a secret key use the following REST API:

curl -X PUT http://<ManagedServerHost>:<ManagedServerPort>/oauth2/rest/resources/secretkey -H 'Content-Type: application/x-www-form-urlencoded' -H 'x-oauth-identity-domain-name: <OAuthIdentityDomain>' -H 'Authorization:Bearer <AccessToken>'

Deleting a Secret Key

To delete a secret key use the following REST API:

curl -X DELETE http://<ManagedServerHost>:<ManagedServerPort>/oauth2/rest/resources/secretkey -H 'Content-Type: application/x-www-form-urlencoded' -H 'x-oauth-identity-domain-name: <OAuthIdentityDomain>' -H 'Authorization:Bearer <AccessToken>'

Creating a Secret Key Using Basic Authentication

To create a secret key using Basic Authentication, use the following REST API:

curl -X POST http://<ManagedServerHost>:<ManagedServerPort>/oauth2/rest/resources/secretkey -H 'Content-Type: application/x-www-form-urlencoded' -H 'authorization:Basic <Base64EncodedUsernamePassword>' -H 'x-oauth-identity-domain-name:<OAuthIdentityDomain>'