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

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

32.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 32-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 32-1 Second Factor Authentication Preferred Method Page

Description of Figure 32-1 follows
Description of "Figure 32-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:

32.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 32-2 shows the OTP login page.

Figure 32-2 One Time Password Login Page

Description of Figure 32-2 follows
Description of "Figure 32-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:

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

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

32.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 32-3 shows the Second Factor Authentication Preferred Method Page with Access Request Notification that has been selected.

Figure 32-3 Access Request Notification Preferred Method Page

Description of Figure 32-3 follows
Description of "Figure 32-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 32-4 shows the Access Request Notification message that is displayed during this process.

Figure 32-4 Access Request Notification Wait Screen

Description of Figure 32-4 follows
Description of "Figure 32-4 Access Request Notification Wait Screen"

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

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

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

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

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

  1. Create DefaultDomain with customAttrs as described:
    1. 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.
    2. 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

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

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

  1. Log into the Oracle Access Management Console as System Administrator.
  2. From the Application Security Launch Pad, click Authentication Plug-ins in the Plug-ins panel.
  3. 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.

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

    Table 32-1 describes the Adaptive Authentication Plugin properties.

    Table 32-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

     

    Note:

    In addition to the properties (related to OTP generation in Adaptive Autentication plugin) specified in Table 32-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.

  5. Click Save.
  6. 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 32-1 does not list all available Adaptive Authentication Service properties.

32.4.4 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 32-2 lists information that you need to complete the procedure.

Table 32-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:

  1. cd <MW_HOME>/oracle_common/common/bin
  2. ./wlst.sh
  3. connect()
  4. Enter the WebLogic user name and password when prompted.
  5. Press Enter to accept the default URL or modify the host and port as necessary and press Enter.
  6. 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")
      
  7. 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.

32.4.5 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

32.4.6 Configuring Push Notifications on Mobile Device

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

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

  1. Navigate to base_domain -> Summary of Environment -> Summary of Servers -> oam_server1.
  2. Click the SSL tab.
  3. Expand Advanced and select the Hostname verification entry to configure the Hostname Verifier.
  4. Enter weblogic.security.utils.SSLWLSWildcardHostnameVerifier as the Custom Hostname Verifier.
  5. Click Save.
  6. Restart the oam_server1.
32.4.6.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.

  1. Export the oam-config.xml file from the database. See Updating OAM Configuration for details.
  2. 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>
  3. Import the oam-config.xml. See Updating OAM Configuration for details.
  4. Restart admin and managed servers.
32.4.6.3 Verifying Push Notification Settings

Verify the push notification settings in the AdaptiveAuthenticationModule and AdaptiveAuthenticationPlugin

  1. 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.
  2. 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.
32.4.6.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.

32.4.6.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.
  1. Login to the Google firebase console at https://console.firebase.google.com/u/0/.
  2. 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.
  3. Navaigate to the project settings by clicking the gears icon next to the project name in the upper left-hand part of the browser.
  4. 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.
32.4.6.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:
  1. Navigate to the $MW_HOME/oracle_common/common/bin directory and run wlst.sh command to connect to the AdminServer.
  2. 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
32.4.6.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.
  1. 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
  2. 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
  3. Verify the presence of all of the certificates by running the following command
    -keystore DemoTrust.jks -storepass DemoTrustKeyStorePassPhrase -storetype
    jks'
  4. 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.
32.4.6.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.

  1. 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>
  2. 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.
  3. 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.

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

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

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

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

    The Application Domain tab is displayed.

  3. Click Search to display all available Application Domains.
  4. Click the Application Domain name that contains the resource being protected.

    The Application Domain opens in a new tab.

  5. Click Authentication Policies in the Application Domain tab.
  6. 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.

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

    The Add Rule dialog is displayed.

  9. Enter a Rule Name and the following jython script.

    location.clientIP.startswith('10.')

    See Context Data for Advanced Rules.

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

  11. Click Add and then Apply to complete the procedure.