1. Administering Oracle Advanced Authentication and Oracle Adaptive Risk Management
  2. Managing Oracle Advanced Authentication
  3. Configuring Oracle Advanced Authentication

11 Configuring Oracle Advanced Authentication

Topics

11.1 Creating Integration Agents in OAA

You must create an integration agent to integrate client applications with OAA. You can create OAM integration Agents and Oracle RADIUS Integration Agents. You can also create Other Integration Agents for use with your own REST API client applications.

You can create integration agents either using REST APIs or OAA Administration UI console. For details about creating integration agents using REST APIs, see REST API for Administration in Oracle Advanced Authentication.

To create an Oracle RADIUS Integration Agent, see: Use Oracle RADIUS Agent with Oracle Advanced Authentication for Multi-Factor Authentication

To create an OAM integration agent in the OAA Administration UI console:

Note:

For full details on integrating OAM with OAA, see Integrate Oracle Access Management with Oracle Advanced Authentication
  1. Login to the OAA Administration console https://<AdminUrl>. You are redirected to the OAM login page as the console is protected by OAM OAuth. Specify your credentials and login.
  2. Under Quick Actions select Create OAM Integration Agent.
  3. In the Create Integration Agent window, specify the following:
    1. Name: For OAM integration, the value must be the same as the partner name created while registering OAA as TAP partner. For more information, see Register OAA as a TAP Partner in OAM
    2. Description: Add a description about the integration agent.
    3. Integration Agent Type: Oracle Access Management is selected by default.
    4. Client ID: Click Re-Generate to create a Client ID and then click Copy to copy the generated Client ID.

      Note:

      The Client ID needs to be provided when configuring OAM for integration with OAA using the OAAAuthnPlugin. For more information, see Install and configure the OAA Plugin in OAM
    5. Client Secret: Click Re-Generate to create a Client Secret and then Click Copy to copy the generated Client Secret.

      Note:

      The Client Secret needs to be provided when configuring OAM for integration with OAA using the OAAAuthnPlugin
    6. Private Key File: Drag and Drop the Java KeyStore file (.jks) that was created after registering OAM as a TAP partner of OAA. For example, OAMOAAKeyStore.jks.
    7. Private key Password: Specify the password that you had provided while registering OAM as a TAP partner of OAA.
  4. Click Save

To create an integration agent for use with your own REST API client applications:

  1. Login to the OAA Administration console https://<AdminUrl>. You are redirected to the OAM login page as the console is protected by OAM OAuth. Specify your credentials and login.
  2. Under Quick Actions select Create Other Integration Agent.
  3. In the Create Integration Agent window, specify the following:
    1. Name: Enter a name for your integration agent.
    2. Description: Add a description about the integration agent.
    3. Integration Agent Type: API is selected by default.
    4. Client ID: Click Re-Generate to create a Client ID and then click Copy to copy the generated Client ID.

      Note:

      The Client ID needs to be provided when configuring your application.
    5. Client Secret: Click Re-Generate to create a Client Secret and then Click Copy to copy the generated Client Secret.

      Note:

      The Client Secret needs to be provided when configuring your application.
  4. Click Save.

11.2 Creating Assurance Levels in OAA

You can create assurance levels for an integration agent either using REST APIs or the OAA Administration UI console. For more details about using REST APIs, see Create an Assurance Level.

The following steps provide instructions to create an assurance level for an integration agent on the OAA Administration UI console:
  1. Login to the OAA Administration console https://<AdminUrl>. You are redirected to the OAM login page as the console is protected by OAM OAuth. Specify your credentials and login.
  2. If the integration agent has been recently created, it is shown under Recent Activity. However, if the integration agent does not appear under Recent Activity, do one of the following:
    • Click Show more agents
    • Click the Application Navigation icon on the top-left of the page and select Manage Integration Agents
  3. In the Integration Agents window, select the integration agent for which you need to create the assurance level.
  4. Under the Assurance Levels tab, click Create.
  5. Specify the required details:
    • Name: Specify the name for this assurance level
    • Description: Provide the description for the assurance level.
  6. Click Create.

11.3 Configuring Rules for an Assurance Level in OAA

You can manage rules for an assurance level using the OAA Administration UI console or REST APIs. If you create rules for an assurance level in the OAA Administration UI console, a policy for those rules is automatically created for you. If using REST API's to create rules then you must create the policy first using the REST API. For more details about using REST APIs to create a policy and associated rules, see Create Policy.

The following steps provide instructions to create rules for an assurance level on the OAA Administration UI console:

  1. Login to the OAA Administration console https://<AdminUrl>. You are redirected to the OAM login page as the console is protected by OAM OAuth. Specify your credentials and login.
  2. If the integration agent has been recently created, it is shown under Recent Activity. However, if the integration agent does not appear under Recent Activity, do one of the following:
    • Click Show more agents
    • Click the Application Navigation icon on the top-left of the page and select Manage Integration Agents
  3. In the Integration Agents window, select the required integration agent.
  4. Under the Assurance Levels tab, select the required assurance level for which you are required to define rules
  5. Under Uses select the required factors to assign to the assurance level. For example, select Oracle Mobile Authenticator, Email Challenge and SMS Challenge.
  6. Under If the following condition(s) are met, select the Attribute Name, Operator, and Values to create rules. Based on the Attribute Name selected, corresponding options appear in the Operator drop-down and Values fields. For example, for User In Group with operator Contains Any specify the value in the Values field. For User In Group with operator In Group, the values field changes to Group, and you can select a group name from the drop-down.
    The following options are supported in Attribute Name:
    • User in Group
    • User's Group
    • User Login
    • User Attributes
    • Current Authentication Level
    • IP Address
    • Application ID
    • Parameter
    • Resource URL
    • New Authentication Level
    • Agent
    • IP Address X-Forwarded-For
  7. Click Validate Rule.
  8. Click Save.
  9. Create additional rules, if necessary, by clicking the + icon.

11.4 Creating Groups in OAA

You can create groups for an integration agent in OAA either using REST APIs or OAA Administration UI console. For more details about using REST APIs, see Create Groups.

The following steps provide instructions to create a group for an integration agent in the OAA Administration UI console:
  1. Login to the OAA Administration console https://<AdminUrl>. You are redirected to the OAM login page as the console is protected by OAM OAuth. Specify your credentials and login.
  2. If the integration agent has been recently created, it is shown under Recent Activity. However, if the integration agent does not appear under Recent Activity, do one of the following:
    • Click Show more agents
    • Click the Application Navigation icon on the top-left of the page and select Manage Integration Agents
  3. In the Integration Agents window, select the integration agent, for which you are required to create a group.
  4. Under the Groups tab, click Create.
  5. Specify the required details:
    1. Name: Specify the name of the group.
    2. Description: Specify a description for the group.
    3. Type: From the drop-down, select the required type.
    4. Click Create .
    5. Under Values tab, click Add. Add the corresponding value for the type selected in the previous step. See the following table for details.
  6. Click Save.

Table 11-1 Type Value Reference for Groups

Type Description and Values
User ID

Select this to create a group based on the user id.

Specify the user ID in the values field.
IP Address

Select this to create a group based on the IP address.

Specify the IP address in the values field.
IP Address Range Select this to create a group based on the value lying between the specified IP Range:
  1. Name: Specify a name.
  2. Description: Specify a description.
  3. From: Specify the starting IP address of the range.
  4. To: Specify the ending IP address of the range.
String

Select this to create a group based on any specify value required.

Specify the string in the values field.

11.5 Registering Users with Challenge Factors in OAA

OAA provides REST APIs for registering users with specific challenge factors.

Use the <OAAService>/preferences/v1 REST API to register the necessary challenge factors for users.

For details about finding the <OAAService> URL and authenticating, see OAA Runtime API.

For details about the Preferences REST Endpoint, see REST API for OAA Runtime. These factors can be further managed by users in the User Preferences UI. For more information, see Managing User Preferences UI.

Example 1: Sample Request to Register User with Oracle Mobile Authenticator (OMA)

The following sample request shows how to register a user testuser1 with groupID UserGroup1 with OMA: 

curl --location -g --request POST '<OAAService>/preferences/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \
--data '{
    "userId": "testUser1",
    "groupId": "UserGroup1",
  "factorsRegistered": [            
            {
              "factorAttributes": [
                {
                  "factorAttributeValue": [
                    {
                      "value": "omasecretvalue1",
                      "name": "Device1",
                      "isEnabled": true
                    }
                  ],
                  "factorAttributeName": "omatotpsecretkey"
                }
              ],
              "factorKey": "ChallengeOMATOTP",
              "isPreferred": false,
              "isValidated": true
            }
          ]
        }'

Note:

The value for factorAttribueValue supports alphanumerics only.

Example 2: Sample Request to Register User with Email

The following sample request shows how to register a user testuser1 with groupID UserGroup1 with Email: 

curl --location -g --request POST '<OAAService>/preferences/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \
--data '{
    "userId": "testUser1",
    "groupId": "UserGroup1",
  "factorsRegistered": [
            {
              "factorAttributes": [
                {
                  "factorAttributeValue": [
                    {
                      "value": "test.user@example.com",
                      "name": "Device1",
                      "isEnabled": true
                    }
                  ],
                  "factorAttributeName": "email"
                }
              ],
              "factorKey": "ChallengeEmail",
              "isPreferred": false,
              "isValidated": true
            },
Once a user is registered they can manage their factors using the User Preferences UI. See, Managing Factors in the User Preferences UI.

Note:

The parameter isValidated is true by default. If using factor verification as per Configuring Factor Verification, if isValidated is true then the user will be registered as verified, whereas if the value is set to false, the user will be registered as unverified.

11.6 Managing Factors in the User Preferences UI

OAA provides users with a User Preferences UI for managing factors.

Access the User Preferences UI by launching a browser and accessing https://<SpuiURL>. The user logs in to the console using their username (e.g testuser1) and their password set in the OAM OAuth identity store.

Note:

For details on finding the <SpuiUrl>, see Printing Deployment Details.

On the User Preferences Page, for each of the factors registered, a corresponding challenge factor tile is displayed. For example, if the user is registered with Oracle Mobile Authenticator (OMA) and Email challenge factors, the corresponding tiles named Oracle Mobile Authenticator and Email Challenge are displayed.

On the factor tiles, you can choose to Disable, Enable, Delete or set your Preferred Authentication factor. Click on the ... menu button on the factor tiles and select one of the following options:
  • Disable: This factor is disabled, and will not be displayed during the second-factor authentication.
  • Preferred Authentication Factor: This factor is set as the default challenge factor and is displayed automatically during the second-factor authentication. A green dot appears on the default factor in the User Preferences UI page.
  • Delete: Deletes the registered factor.
  • Enable: If the factor is disabled, you can choose to enable it by selecting this option.

In addition to the registered factors, you can also add more factors for second-factor authentication. Click Add Authentication Factor and choose the required factor from the displayed list. Based on the factors registered for the user, one, some, or all of the following factors are displayed:

Factors Values
Oracle Mobile Authenticator

Friendly Name: Specify a name.

Key: A key is generated by OAA.

QR Code: Scan the QR code using the Oracle Mobile Authenticator, Google Authenticator, or Microsoft Authenticator application.

Email Challenge

Friendly Name: Specify a name.

Email: Specify the required email.

FIDO2 Challenge

Friendly Name: Specify a name.

Click Register and press the button on your FIDO2 device. The key is copied into OAA.
OMA Push Notification Challenge

Scan the QR code, or manually register your device. In the OMA application enter the userid and PIN displayed here.
Security Question Challenge

Question 1: Select a question to answer.

Answer 1: Provide an answer the question.

Repeat for the remaining Question and Answers.
SMS Challenge

Friendly Name: Specify a name.

Phone: Specify the phone number.

Yubico OTP Challenge

Friendly Name: Specify a name.

Public ID: Type the Public ID. It must be the same as the Public ID (or serial) specified while configuring the Yubico OTP for your YubiKey device.

Secret Key: Type the Secret Key. It must be the same as the Secret Key generated while configuring the Yubico OTP for your YubiKey device.

Private ID: Type the Private ID. It must be the same as the Private ID generated while configuring the Yubico OTP for your YubiKey device.

For more details on configuring Mobile Authenticator, Security Question Challenge, Yubikey OTP Challenge, and FIDO2 Challenge, see the following tutorials:

11.7 Configuring Oracle UMS Server for Email and SMS

OAA supports Oracle UMS out-of-the-box for providing email and SMS challenges

To integrate Oracle UMS with OAA for providing email and SMS challenge factors, use the <PolicyUrl>/policy/config/property/v1 REST API as shown in the following sample request.

Note:

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

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

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

Sample Request

curl --location -g --request PUT '<PolicyUrl>/policy/config/property/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \--data '[
                {
        "name": "bharosa.uio.default.challenge.type.enum.ChallengeEmail.umsClientURL",
        "value": "<UMS_SERVER_URL>"          
},
{
        "name": "bharosa.uio.default.challenge.type.enum.ChallengeEmail.umsClientName",
        "value": "<UMS_ADMIN_USER>"          
},
{
        "name": "bharosa.uio.default.challenge.type.enum.ChallengeEmail.umsClientPass",
        "value": "<UMS_ADMIN_PASSWORD>"          
},
{        "name": "bharosa.uio.default.challenge.type.enum.ChallengeEmail.fromAddress",
        "value": "<fromAddress>"
},
{
        "name": "bharosa.uio.default.challenge.type.enum.ChallengeSMS.umsClientURL",
        "value": "<UMS_SERVER_URL>"                
},
{
        "name": "bharosa.uio.default.challenge.type.enum.ChallengeSMS.umsClientName",
        "value": "<UMS_ADMIN_USER>"                
},
{
        "name": "bharosa.uio.default.challenge.type.enum.ChallengeSMS.umsClientPass",
        "value": "<UMS_ADMIN_PASSWORD>"                
}
]'
where:
  • <UMS_SERVER_URL> is the UMS server URL, for example: http://ums.example.com:8001/ucs/messaging/webservice.
  • <UMS_ADMIN_USER> is the username for the UMS service.
  • <UMS_ADMIN_PASSWORD> is the corresponding password for <ums_username>.
  • <fromAddress> is the email address from which end users will receive the One Time Password (OTP), for example oaa@example.com

For implementing your own email and SMS servers, see Customizing Email and SMS Messaging Provider.

11.8 Configuration Properties for OAA

OAA provides REST APIs for configuring properties for challenge factors and other settings.

Use the <PolicyUrl>/policy/config/property/v1 REST API to configure properties.

Note:

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

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

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

Table 11-2 Configuration Properties for OAA

Property Name Default Value Description
bharosa.uio.default.all.factor.challengecounter.expiryTime 1800000 Expiry time of the challenge counter lock for the factors. This is the time duration for which the challenge remains unavailable for users, after challenge is locked due to maximum number of unsuccessful retries.
bharosa.uio.default.all.factor.retry.count 10 Maximum number of unsuccessful retries of the challenge for the factors. Beyond this count the challenge is locked.
bharosa.uio.default.challenge.type.enum.ChallengeEmail.appName OAA Name of the application.
bharosa.uio.default.challenge.type.enum.ChallengeEmail.challengeText Enter OTP sent to {0}. Prompt message to enter One Time Pin (OTP) on the end-user challenge page.
bharosa.uio.default.challenge.type.enum.ChallengeEmail.fromAddress oaa@oracle.com Email address of the email sending entity.
bharosa.uio.default.challenge.type.enum.ChallengeEmail.fromName OAA Name of the From email sending entity.
bharosa.uio.default.challenge.type.enum.ChallengeEmail.msgIPTemplate IP Address: Part of the email template to display message IP addres.s
bharosa.uio.default.challenge.type.enum.ChallengeEmail.msgPinTemplate Please use following one time pin to login to protected resource: Part of the email template to display One Time Pin (OTP).
bharosa.uio.default.challenge.type.enum.ChallengeEmail.msgResourceURLTemplate Resource URL Access: Part of the email template to display message resource URL.
bharosa.uio.default.challenge.type.enum.ChallengeEmail.msgSubject One Time Pin: OAA Subject title of the email template.
bharosa.uio.default.challenge.type.enum.ChallengeEmail.challengeCounterExpiryTime 1800000 Expiry time of the challenge counter lock. This is the time duration for which the challenge remains unavailable for users, after challenge is locked due to maximum number of unsuccessful retries.

If the value is not provided then the value for bharosa.uio.default.all.factor.challengecounter.expiryTime is used (default is 1800000 milliseconds)

.
bharosa.uio.default.challenge.type.enum.ChallengeEmail.retrycount Maximum number of unsuccessful retries of the challenge. Beyond this count the challenge is locked.

If the value is not provided then the value for bharosa.uio.default.all.factor.retry.count is used (default is 10).

bharosa.uio.default.challenge.type.enum.ChallengeEmail.msgTimeTemplate Time of Access: Part of the email template to display message time.
bharosa.uio.default.challenge.type.enum.ChallengeEmail.promptmessage Send OTP to {0} Prompt message to send One Time Pin (OTP) through email used on end-user challenge page.
bharosa.uio.default.challenge.type.enum.ChallengeEmail.promptselectmessage Please select one of following addresses to receive OTP. Prompt message to select addresses to send One Time Pin (OTP) to user on end-user challenge page.
bharosa.uio.default.challenge.type.enum.ChallengeOMATOTP.challengeText Enter OTP from device {1} Prompt message to enter time-based One Time Pin (OTP) on end-user challenge page.
bharosa.uio.default.challenge.type.enum.ChallengeOMATOTP.promptselectmessage Please select one of following channels Prompt message to select channels to send time-based One Time Pin (OTP) to user on end-user challenge page.
bharosa.uio.default.challenge.type.enum.ChallengeOMATOTP.challengeCounterExpiryTime 1800000 Expiry time of the challenge counter lock. This is the time duration for which the challenge remains unavailable for users, after challenge is locked due to maximum number of unsuccessful retries.

If the value is not provided then the value for bharosa.uio.default.all.factor.challengecounter.expiryTime is used (default is 1800000 milliseconds).

bharosa.uio.default.challenge.type.enum.ChallengeOMATOTP.retrycount Maximum number of unsuccessful retries of the challenge. Beyond this count the challenge is locked.

If the value is not provided then the value specified for bharosa.uio.default.all.factor.retry.count is used (default is 10).

bharosa.uio.default.challenge.type.enum.ChallengeOMATOTP.registration.showSecretKeyText true Displays a secret key in the User Preferences UI, for use with Oracle Mobile Authenticator, Google Authenticator, or Microsoft Authenticator. If the value is set to false, the secret key isn't displayed.
bharosa.uio.default.challenge.type.enum.ChallengeOMATOTP.registration.showQrcode true Displays a QR code in the User Preferences UI, for use with Oracle Mobile Authenticator, Google Authenticator, or Microsoft Authenticator. If the value is set to false, the QR code isn't displayed.
bharosa.uio.default.challenge.type.enum.ChallengeOMATOTP.keyExpiryEnabled false A boolean value that indicates whether or not secret key expiration is enabled. When enabled, the Time-based One Time Password (TOTP) secret key expiration time is checked during the challenge flow. If the key has expired, the challenge flow fails and the key is deleted. If the key has not expired, the challenge flow will continue as usual.
bharosa.uio.default.challenge.type.enum.ChallengeOMATOTP.keyExpiryTimeMinutes 60 Specifies the key's expiration time in minutes. This must be a positive whole number.
bharosa.uio.default.challenge.type.enum.ChallengeOMATOTP.registration.otpexpirytimeMs 300000 Specifies the timeout in millisecond for the Time-based One Time Password (TOTP) generated registration URL.
bharosa.uio.default.challenge.type.enum.ChallengeOMATOTP.registration.oma.config oraclemobileauthenticator://settings?ServiceName::=%deviceName%&ServiceType::=SharedSecret&SharedSecretAuthServerType::=HTTPBasicAuthentication&LoginURL::=%totpRegistrationEndpoint%/oaa/rui/totpPreferences/v1

Note: If the value of totpRegistrationEndpoint is not provided, then it's value is computed based on the kubernetes cluster/pod setup.

 
database.cache.type.enum.factor.expiryTime Value must be greater than equal to bharosa.uio.default.challenge.type.enum.ChallengeOMATOTP.registration.otpexpirytimeMs.

If not specified default value is 600 seconds.

Specifies the cache timeout in seconds.
bharosa.uio.default.challenge.type.enum.ChallengeSMS.challengeCounterExpiryTime 1800000 Expiry time of the challenge counter lock. This is the time duration for which the challenge remains unavailable for users, after challenge is locked due to maximum number of unsuccessful retries.

If the value is not provided then the value for bharosa.uio.default.all.factor.challengecounter.expiryTime is used (default is 1800000 milliseconds).

bharosa.uio.default.challenge.type.enum.ChallengeSMS.retrycount Maximum number of unsuccessful retries of the challenge. Beyond this count the challenge is locked.

If the value is not provided then the value specified for bharosa.uio.default.all.factor.retry.count is used (default is 10).

bharosa.uio.default.challenge.type.enum.ChallengeSMS.appName OAA Name of the application.
bharosa.uio.default.challenge.type.enum.ChallengeSMS.challengeText Enter OTP sent to {0}. Prompt message to enter One Time Pin (OTP) on end-user challenge page.
bharosa.uio.default.challenge.type.enum.ChallengeSMS.fromAddress oaa@oracle.com Mobile number of the SMS sending entity.
bharosa.uio.default.challenge.type.enum.ChallengeSMS.fromName OAA Name of the From SMS sending entity.
bharosa.uio.default.challenge.type.enum.ChallengeSMS.msgIPTemplate IP Address: Part of the SMS template to display message IP address.
bharosa.uio.default.challenge.type.enum.ChallengeSMS.msgPinTemplate Please use following one time pin to login to protected resource: Part of the SMS template to display One Time Pin (OTP).
bharosa.uio.default.challenge.type.enum.ChallengeSMS.msgResourceURLTemplate Resource URL Access: Part of the SMS template to display message resource URL.
bharosa.uio.default.challenge.type.enum.ChallengeSMS.msgSubject One Time Pin: OAA Subject title of the SMS template.
bharosa.uio.default.challenge.type.enum.ChallengeSMS.msgTimeTemplate Time of Access: Part of the SMS template to display message time.
bharosa.uio.default.challenge.type.enum.ChallengeSMS.promptmessage Send OTP to phone {0} Prompt message to send One Time Pin (OTP) through SMS used on end-user challenge page.
bharosa.uio.default.challenge.type.enum.ChallengeSMS.promptselectmessage Please select one of following numbers to receive OTP. Prompt message to select addresses to send One Time Pin (OTP) to user on end-user challenge page.
bharosa.uio.default.challenge.type.enum.ChallengeTOTP.promptmessage Enter OTP from registered phone Prompt message to send time-based One Time Pin (OTP) used on end-user challenge page.
bharosa.uio.default.challenge.type.enum.ChallengeYubicoOTP.challengeCounterExpiryTime 1800000 Expiry time of the challenge counter lock. This is the time duration for which the challenge remains unavailable for users, after challenge is locked due to maximum number of unsuccessful retries.

If the value is not provided then the value for bharosa.uio.default.all.factor.challengecounter.expiryTime is used (default is 1800000 milliseconds).

bharosa.uio.default.challenge.type.enum.ChallengeYubicoOTP.retrycount   Maximum number of unsuccessful retries of the challenge. Beyond this count the challenge is locked.

If the value is not provided then the value specified for bharosa.uio.default.all.factor.retry.count is used (default is 10).

bharosa.uio.default.challenge.type.enum.ChallengeFIDO2.challengeCounterExpiryTime 1800000 Expiry time of the challenge counter lock. This is the time duration for which the challenge remains unavailable for users, after challenge is locked due to maximum number of unsuccessful retries.

If the value is not provided then the value for bharosa.uio.default.all.factor.challengecounter.expiryTime is used (default is 1800000 milliseconds).

bharosa.uio.default.challenge.type.enum.ChallengeFIDO2.retrycount   Maximum number of unsuccessful retries of the challenge. Beyond this count the challenge is locked.

If the value is not provided then the value specified for bharosa.uio.default.all.factor.retry.count is used (default is 10).

oracle.security.oaa.kba.challenge.number 1

Number of security questions that the user will be asked to answer during the challenge flow. This should be set to a value no larger than the maximum number of active questions answered by the user during security question registration.

Note: This property should be used in conjunction with the oracle.security.oaa.kba.challenge.separator property described in the row below.

oracle.security.oaa.kba.challenge.separator | If oracle.security.oaa.kba.challenge.number is set to a value greater than 1, the generated challenge will contain the multiple challenges as a string, separated by the value of oracle.security.oaa.kba.challenge.separator. For example: What is your name?|What is your age?|What is your birthplace? .

When the response to the challenge is presented to the OAA server, the response is also expected to be seperated by the same separator.

By default the value is "|".

If you anticipate any of the questions or answers could contain the value "|" then you must change this parameter to use a seperator that is is not contained in the question or answer.

To override this value set oracle.security.oaa.kba.challenge.separator to a character or combination of characters of your choice.

Note: Changing the separator may impact in flight KBA authentications, Hence, perform updates to this configuration when the KBA service is offline.

oaa.user.auth.question.authn.counter.enabled true If this property is true, the risk counters are incremented.
oaa.user.auth.question.next.seq false If this property is false, oaam.kba.questions.randomorder is true, and oracle.security.oaa.kba.challenge.number is 1, the questions selected from picklist are at random. Else, the user is challenged by questions from the picklist in sequential order.
oaam.kba.questions.randomorder false If this property is true, oaa.user.auth.question.next.seq is false, and oracle.security.oaa.kba.challenge.number is 1, questions selected from picklist are at random. Else, the user is challenged by questions from the picklist in sequential order.
bharosa.kba.questions.trim.answers.for.matching true If this property is set to true, the answer and the matched value are trimmed before matching.
oaa.browser.cookie.domain   In case of an OAA-OARM install this must be set to the OAA host domain to collect the device cookie properly. For example, if the OAA is accessible on https://oaa.example.com, then set the value to oaa.example.com.
oaa.risk.integration.postauth.cp postauth

Defines the default risk assurance level for OAA assurance level. The default value is postauth and should not be changed.

Note: This property is related to OAA-OARM integration.

oaa.policy.assurance.level.default.action Challenge

Defines the default action associated with the OAA assurance level.

Note: This property is related to OAA-OARM integration.

profile.type.enum.<AssuranceLevelKey>.riskcheckpoint  

Checkpoint associated with the existing assurance level.

Note: This property is related to OAA-OARM integration.

profile.type.enum.<AssuranceLevelKey>.defaultaction  

Default action associated with the existing assurance level. Acceptable values are Allow, Block, and Challenge. For instance: 

[
{
        "name": "profile.type.enum.ChallengeMFA.defaultaction",
        "value": "<Allow/Block/Challenge>",
        "source": "database"
 }
]

Note: This property is related to OAA-OARM integration.

rule.action.enum.<actionName>.priority  

Defines the priority of the action. It can be a integer value or string "max" to identify the highest priority. For instance:

[
    {
        "name": "rule.action.enum.Block.priority",
        "value": "max",
        "source": "database"
    }
]

Note: This property is related to OAA-OARM integration.

default.all.factor.bypassChallenge.durationInMinutes   Specifies the duration for which the user is no longer challenged after a successful login.

Note: You can set the property to a negative value to disable this feature.

To configure properties to customize the user interface (UI) for the OAA Administration Console, User Preferences Console, and Runtime UI, see Customizing the OAA User Interface.

To configure properties for Factor Verification, see Configuring Factor Verification.

11.9 Configuring Factor Verification

OAA allows you to configure factor verification. Factor verification allows users to verify a factor in the User Preferences UI after the factor has been added. This allows a user check the factor is working before it is used in a user challenge. By default, factor verification is disabled.

Topics

The following topics describe how to configure factor verification:

11.9.1 Creating a Verification Integration Agent

To enable factor verification, you must create a verification integration agent.

You can create integration agents either using REST APIs or OAA Administration UI console. For details about creating integration agents using REST APIs, see REST API for Administration in Oracle Advanced Authentication.

To create a verification integration agent:

  1. Login to the OAA Administration console https://<AdminUrl>. You are redirected to the OAM login page as the console is protected by OAM OAuth. Specify your credentials and login.
  2. Under Quick Actions select Create Other Integration Agent.
  3. In the Create Integration Agent window, specify the following:
    1. Name: Enter a name for your integration agent, for example VerificationFlowAgent.

      Note:

      The property oaa.default.spui.pref.runtime.verification.agentId is set to VerificationFlowAgent by default. If you choose to give your agent a different name then you must configure the property to match. See Configuring Properties for Factor Verification.
    2. Description: Add a description for the integration agent.
    3. Integration Agent Type: API is selected by default.
    4. Click Save.

Next steps: Creating an Assurance Level for the Verification Integration Agent.

11.9.2 Creating an Assurance Level for the Verification Integration Agent

Create an assurance level for the verification integration agent.

You can create assurance levels either using REST APIs or OAA Administration UI console. For details about creating integration agents using REST APIs, see REST API for Administration in Oracle Advanced Authentication.

To create an assurance level for the verification integration agent:

  1. In the Integration Agents window, select the verification integration agent for which you need to create the assurance level.
  2. Under the Assurance Levels tab, click Create.
  3. Specify the required details:
    1. Name: Specify the name for this assurance level, for example FactorVerificationAL.

      Note:

      The property oaa.default.spui.pref.runtime.verification.assuranceLevel is set to FactorVerificationAL by default. If you choose to give your assurance level a different name then you must configure the property to match. See Configuring Properties for Factor Verification
    2. Description: Provide the description for the assurance level.
    3. Click Create.
    4. Click the Assurance Level created.
    5. Under Uses select the factors for which you want to configure factor verification.

      Note:

      Factor verification is only supported for Oracle Mobile Authenticator, Email Challenge, Yubico OTP Challenge, and SMS Challenge.
  4. Click Save.

Next steps: Configuring Properties for Factor Verification.

11.9.3 Configuring Properties for Factor Verification

To enable factor verification you must set configuration properties.

The following table lists the OAA properties that you must configure to enable factor verification.

Table 11-3 Factor Verification Properties

Property Name Description Default Value
oaa.default.spui.pref.runtime.verification.enabled This property determines if factor verification is enabled or disabled. To enable factor verification set this value to true false
oaa.default.spui.pref.runtime.verification.agentId The name of the verification integration agent. If you create a verification agent with a name other than the default VerificationFlowAgent, you must set this property to the name of the agent created. VerificationFlowAgent
oaa.default.spui.pref.runtime.verification.assuranceLevel The name of the assurance level for the verification agent. If you create an assurance level with a name other than the default FactorVerificationAL, you must set this property to the name of the assurance level created. FactorVerificationAL
Use the <PolicyUrl>/policy/config/property/v1 REST API to configure properties.

Note:

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

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

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

Next steps: Testing Factor Verification.

11.9.4 Testing Factor Verification

To test factor verification:

  1. Access the User Preferences UI by launching a browser and accessing https://<SpuiURL>. The user logs in to the console using their username and password set in the OAM OAuth identity store.

    Note:

    For details on finding the <SpuiUrl>, see Printing Deployment Details.
  2. Under Authentication Factors select Add Authentication Factor and select an authentication factor. In this example Email Challenge is selected.
  3. In the Setup Security Code via Email page, enter a Friendly Name and Email address. As factor verification is enabled, two new options are shown: Verify Now and Verify Later.

If you select Verify Now you will be asked to enter the verification code. In this example the verification code will be sent to the email address. Enter the verification code from the email and select Verify and Save. If verification is successful you will be returned to the Authentication Factors screen and the authentication factor will show as Enabled.

If you select Verify Later you will be returned to the Authentication Factors screen. The factor added will show as Unverified.

Note:

If Verify Later is selected, the factor added will not be presented in a user challenge until it is verified.

If Verify Later is selected, the factor is saved as Unverified. It can verified by selecting Verify from the factor drop down menu on the Authentication Factors screen. Once the factor is verified it will show as Enabled.

Note:

Any factors added prior to enabling factor verification will show either Enabled or Disabled and will not need to go through verification.

Important Note for Upgrades

If you are upgrading from a previous release where factor verfication wasn't supported, all previously registered factors for a user will automatically be verified after upgrade. This is true for all previously enabled and disabled factors for a user. Any new factors registered for the user after upgrade, will use factor verification.

11.10 Configuring Security Questions for Knowledge-Based Authentication

Knowledge-based authentication (KBA) is an authentication method which is used to challenge the user to prove identity based on the user’s answers substantiated by a real-time interactive question and answer process.

The KBA feature provides a rich set of challenge questions, logic behind presenting these challenge questions to users, and validations to control the answers that users can provide.

KBA is a secondary authentication feature, which is presented to the user after successful primary authentication (for example, a user entering user name and password) to enhance the security.

KBA provides an infrastructure for:

  • Questions: Users to select challenge questions and provide answers which are used to challenge them later on.
  • Categories: Manages the question categories in the system.
  • Registration Logic: Manages the level of algorithm logic used for the registration for challenge questions and answers.
  • Answer Logic: To intelligently detect the correct answers in the challenge response process.
  • Validations: Manages the validation for the answers given by a user at the time of registration.

This chapter introduces you to the key concepts behind KBA. It contains the following topics:

11.10.1 About KBA Registration

During registration, which could be enrollment, opening a new account, or other events such as a reset, the user is asked to select questions and provide answers. The order of questions that are presented to a user during the registration phase is random using configurable parameters.

The challenge questions selected at registration or during a reset are then used for authenticating users using a challenge/response process where users are challenged with one or more questions to provide identity before they are allowed to proceed with high risk log ins or access transactions.

11.10.2 Configuring Registration Logic

Registration Logic manages the registration of challenge questions and answers.

The KBA feature offers a large framework of questions for obtaining answers from the user during registration or reset. During KBA registration the user is presented with a Question Set, which is a subset of the challenge questions library. The Question Set allotted to the user is generated based on the settings configured in the Registration Logic. This Question Set prevents an imposter from harvesting questions for use in a phishing exercise.

The Question Set is broken down into several drop-down lists that contain questions to select from. The drop-down lists with questions is called a "menu."

To configure the Registration Logic, you specify the settings for Question Set generation as follows:
  • The number of questions to be registered
  • The number of questions per menu
  • The number of categories per menu

You can configure the number of questions that a user must register, the number of questions that appear in each menu, and the number of categories per menu. As standard, questions are grouped into categories. The user is allowed to select one question from each menu and enter answers for them. Only one question from each question menu can be registered.

Let us consider the following example to see how the Registration Logic settings affect the Question Set of a customer.

Question/Menu Categories/Menu Questions/Category in a Menu
7 4 2+2+2+1

The example results in registration menus containing 2 questions from category A, and 2 questions from category B, and 2 questions from category C, and 1 question from category D. This continues in a round robin fashion as needed. If there are any categories with an insufficient number of questions or an insufficient number of categories duplicate questions can result.

For example to generate a Question Set with:

  • 3 menus
  • 5 questions per menu
  • 5 categories per menu

The algorithm tries to pick one question each from 15 categories if 15 categories are available. The minimum number of questions per category should be equal to the number of questions in the Question Set divided by the total number of categories.

Pre-requisite for Configuring Registration Logic for Locales

The Administrator must ensure that there are enough questions in the database for each of the supported locale as configured in OAA Admin during deployment; otherwise, the application displays only the English language questions during registration.

The number of locale-specific questions must be equal to or greater than the "Questions User Will Register" multiplied by the "Questions per Menu" multiplied by the "Categories per Menu."

11.10.3 Configuring Answer Logic

Answer Logic validates if the answer provided by the user matches with what was provided during registration.

Answer Logic, a feature of KBA, increases the usability of challenge questions. Administrators can adjust how exact the challenge answers given by end users must match the answers they gave at the time of registration. If the answer given by a user is fundamentally correct but there are minor variations such as typos, misspellings, and abbreviations they should pass. The increased usability of KBA reduces or eliminates the need for unnecessary call center involvement in moderate risk situations and self service flows.

Answer Logic consists of advanced algorithms selected by the system to configure the level of tolerance of the erroneous answer. The algorithms are divided into three categories: Common Abbreviations, Keyboard Fat Fingering (accidentally pressing the nearest neighbor on the keyboard), and Phonetics.

Table 11-4 Answer Logic Algorithm Example

Algorithm Description Reason
Common Abbreviations This algorithm handles common abbreviations, common nicknames, common acronyms, and date format. Looks at file for allowed matches. If the file contains Mrs=Misses, the match can be made in either direction.
Keyboard Fat Fingering This algorithm handles answers with typos due to the proximity of keys on a standard keyboard. "u" is directly to the left of "i" so it is allowed.
Phonetics This algorithm handles answers that "sound like" the registered answer, regional spelling differences, and common misspellings. Smiith sounds like Smith.

You can enable or disable the Answer Logic algorithms. You can also configure the strength of some algorithms, such as Keyboard Fat Fingering and Phonetics for evaluating answers given for challenge questions.

This section contains the following topics:

11.10.3.1 Understanding Common Response Errors

This section highlights the most common response errors and shows how Answer Logic algorithms are used for the system to intelligently detect the correct answers in the challenge response process.

Examples of abbreviations, phonetics, and keyboard fat fingering are also provided.

This section contains the following topics:

11.10.3.1.1 About Abbreviations

This algorithm handles common abbreviations, common nicknames, common acronyms, and date format.

Common Abbreviations

The algorithm matches the words in the following pairs as equivalent. OAA Admin has predefined list of word-pairs that cover common abbreviations, common nicknames, and common acronyms.

  • Street - St.
  • Drive - Dr.
  • California - CA

Common Nicknames

Oracle has a predefined list of the most common nicknames that is used in the challenge response process. For example:

  • Timothy - Tim
  • Matthew - Matt

Date Format

The questions that require date as the answer specify the format in which the user should enter the answer. The format is either YYYY or MMDD, but not both. However, from experience, users still use other formats during the challenge response process. The abbreviation logic for date format sees the following as the same:

  • 0713
  • 713
  • July 13th
  • July 13
  • July 13, 1970
11.10.3.1.2 About Phonetics

This algorithm handles answers that "sound like" the registered answer, regional spelling differences, and common misspellings.

The phonetics algorithm is only supported in English.

Common Misspellings

Oracle's Phonetic Answer Logic algorithm accounts for misspellings.

  • ph - f
  • Correct word: elephant - Spelling mistake: elefant
11.10.3.1.3 About Keyboard Fat Fingering

This algorithm accounts for typos due to the proximity of keys on a standard keyboard and transposed letters. Answers with typos due to the proximity of keys on a standard keyboard are handled by this algorithm.

The number of fat fingering characters allowed depends on the length of the original word and the level set. The algorithm returns a percentage score associated with the characters that have an exact match. The intensity determines the minimum score required to match the answer with the registered answer.

The fat fingering algorithm is only supported in English.

Common Typos

  • Switching "w" and "e"
  • Switching "u" and "i"
  • Switching "t" and "r"

Examples of Fat Fingering

Correct word: signature - Fat finger: signatire

11.10.3.2 Configuring the Levels of Answer Logic

The level of Answer Logic, the intensity or strength of algorithms, used to evaluate answers given for challenge questions is adjustable.

You can enable or disable each algorithm and you can also specify the following levels for the algorithms used:

  • Off: No Answer Logic is used. Answers must exactly match those provided at the time of registration.
  • Low: Low level of Answer Logic is used. Answers provided by the user must be a match or near-match to the answers that were provided at the time of registration.
  • Medium: More Answer Logic is used. You are given some freedom for the answers that are provided. For instance, St. is acceptable for Street.
  • High: Highest level of Answer Logic is used. The constraints are not strict for matching.

Note:

The lower the setting the higher the degree of exactness required for acceptance of answers.

For example, high risk transactions such as wire transfers may require a high degree of certainty (i.e. exact match) whereas accessing personal, non-sensitive information may require a lower degree of response certainty. The following example demonstrates how the answer logic algorithm works:

Question: Who was your favorite teacher in high school?

Registered answer: Mrs. Smith

Given answer: Misses Smuth

Logic level: If set to High, the answer is accepted.

Each algorithm generates a score that represents how close the given answer is to the registered answer. You can configure OAA Admin to accept different threshold score ranges for each algorithm individually. Separate threshold values for each algorithm (low/medium/high) are set in a properties file. The default thresholds are described as follows.

Abbreviation

The values are as follows:

  • Return values: 0 or 100 (no-match OR match)
  • Levels: On or Off
  • Logic:
    • If an abbreviation entry exists linking the given strings, score is 100.
    • Else score is 0.
Fat Fingering

The values are as follows:

  • Return values: range 0 to 100
  • Levels: Off, Low (90+), Medium (75+), High (60+)
  • Logic:
    • If the string lengths do not match, score is 0.
    • If a position does not have the expected character or its neighbor, score is 0.
    • Else compute the number of positions that have the neighboring characters.
    • Score = (StringLength – NeighborPositionCount) * 100 /StringLength.
Phonetics

The values are as follows:

  • Return values: 0, 60, 75, 90
  • Levels: Off, Low (90), Medium (75), High (60)
  • Logic:
    • Compute primary and alternative phonetic keys for the given strings, using DoubleMetaphone algorithm.
    • If primary keys of both strings match, score is High.
    • Else if a primary key of one of the strings and alternate key of the other string match, score is Medium.
    • Else if the alternate keys of both string match, score is Low.
    • Else the score is 0.

11.10.4 About Top Categories

The questions are grouped into several categories and the user can select questions from these categories. The Top Categories panel lists the top five categories based on the number of questions linked with a category in descending order.

The standard categories that questions can be grouped into are listed as follows:

  • Childhood
  • Sports
  • Your Birth
  • Parents, Grandparents, Siblings
  • Children
  • Your Employment
  • Significant Other
  • Pets
  • Automobile
  • Education
  • Miscellaneous

The KBA functionality enables you to manage categories. It allows you to create, edit, delete, and view the categories. If the standard categories that questions can be grouped into do not meet your requirements, then you can create categories that can hold the relevant questions you plan to create. See Create New Category.

11.10.5 About Top Questions

The Top Questions panel lists the five most used challenge questions based on user and validation statistics.

The customer can configure a set of challenge questions that are used to authenticate users. During registration, users are presented with several question menus based on the settings configured in the Registration Logic. For example, the user may be presented with three question menus. A user must select one question from each menu and enter answers for them during registration. Only one question from each question menu can be registered. These questions become the user's "registered questions."

The KBA functionality enables you to manage challenge questions. It allows you to create, edit, delete, view, and export and import the challenge questions. If the standard challenge questions do not meet your requirements, then you can create questions as needed. You can also add a validation to the system, if needed. Validations are used to validate the answers given by a user at the time of registration. See Create New Question.

11.10.6 About Disabling Question and Category Logic

The KBA functionality enables you to disable questions and categories.

This section describes the logic to handle disabled questions and categories.

Disabling Logic

The disabling logic is as follows for KBA:

  • If you disable the last remaining question in a category, the category is automatically disabled as well.
  • The number of active categories must be equal to or greater than the maximum number of categories in the question menu. An error message results when you try to disable a category and this requirement is not met.

Consequences

The following table summarizes the disable results.

Disable Question or Category New Customers User with Disabled Question in their Question Set Users with Question Registered
Question The disabled question is not used to generate new users' question sets. At re-registration or when a user changes his preference: Disabled question are replaced with another question from the same category. The disabled question continues to be active.

If the user is re-registering or changing user preference, the disabled question is replaced with another question from the same category.
Category The disabled category is not used to generate new users' question sets. At re-registration or when a user changes his preference: All questions in the disabled category are replaced with questions from a new category that has not been used to generate current question set. Questions from the disabled category continue to be active.

If the user is re-registering or changing user preference, all questions in the disabled category are replaced with questions from a new category that has not been used to generate the current question set.

11.10.7 About Deleting Question and Category Logic

The KBA functionality enables you to delete questions and categories.

This section describes the logic to handle deleted questions and categories.

Delete Logic

The logic to delete is as follows for KBA:

  • You cannot delete a question that is in use by a registered user.
  • Deleted questions are not available for new registrations but the user currently registered for these questions can continue to use them.
  • You can delete a category if it is not referenced by questions in use.

11.10.8 Configuring Validations for Answer Registration

You can configure validations that you can use to control the answers a user is allowed to register for all questions at the time of registration.

Validations are used to validate the answers given by a user at the time of registration. For answers, you can restrict the users to alphanumeric and a few specific special characters by adding a Regular Expression validation. For example, if the question, "What year did you start junior high school," is assigned the Month-Day-Year (MMDDYY) validation, a user registering for this question is not allowed to provide "April 1st 1920" for the answer.

You can assign unique validations to each question to control the answers a user is allowed to register. While creating or editing questions, you can assign a validation, by selecting validation type from the Registration Validation list. You can also import and export validations.

To learn about validation types, see Create New Validation.