Introducing the Adaptive Authentication Service

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

Create DefaultDomain with customAttrs as described below:
Authorization Header Basic = UserName and Password for Admin User like weblogic

POST /oam/services/rest/ssa/api/v1/oauthpolicyadmin/oauthidentitydomain HTTP/1.1

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

Authorization: Basic d2VibG9naWM6d2VsY29tZTE= Content-Type: application/json

{"name":"DefaultDomain","identityProvider":"UserIdentityStore1","description":"Secret Key Test Domain","tokenSettings":[{"refreshTokenEnabled":false,"refreshTokenLifeCycleEnabled":false,"refreshTokenExpiry":0,"lifeCycleEnabled":false,"tokenType":"ACCESS_TOKEN","tokenExpiry":0},{"refreshTokenEnabled":false,"refreshTokenLifeCycleEnabled":true,"refreshTokenExpiry":3600,"lifeCycleEnabled":false,"tokenType":"AUTHZ_CODE","tokenExpiry":0}],"errorPageURL":"http://<HOST>:<PORT>/oam/pages/error.jsp", "consentPageURL":"http://<HOST>:<PORT>/oam/pages/consent.jsp", "customAttrs":"{\"keyAttributeName\":\"title\"}"

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

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:
POST /oauth2/rest/resources/secretkey HTTP/1.1

<HOST>:<PORT>

Authorization: Basic ZGhhcm0xOndlbGNvbWUx

X-OAUTH-IDENTITY-DOMAIN-NAME: DefaultDomain

Cache-Control: no-cache

Postman-Token: e85ec697-cee1-71e9-8ba5-a106907de0c8

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

Sample Response: { "secret_key": "XHPA7HBVI5KR2F73" }

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:

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

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

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.

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

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:

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.