12 Integrating OAA with Other Products

OAA allows integration with other products to support Multi-factor Authentication (MFA) either through REST APIs or browser-based flows.

OAA can be integrated with clients supporting browser-based user flows, for example Oracle Access Management (OAM) and Oracle Identity Manager (OIM), or REST API based user flows such as Oracle RADIUS Agent (ORA) or custom developed applications using REST API's.

12.1 Integrating OAA with OAM

OAA can be integrated with OAM using the OAAAuthnPlugin and registering OAA as a TAP partner.

If you are installing OAA December 24 or later, this is installed and configured for you. For releases prior to December 24, this must be configured manually.

OAA Interaction with OAM to Provide Multi-Factor Authentication

The following provides an overview of the user interaction flow for OAA-OAM integration through a browser-based flow.

  1. The user accesses the OAM (WebGate) protected resource through the browser.
  2. The user is redirected to OAM for authentication.
  3. OAM presents the Login Screen to the user and after authentication redirects the flow to OAA with the TAP Token for multi-factor authentication.

    Note:

    OAA integrates with OAM using the OAAAuthnPlugin and by registering OAA as a TAP partner.
  4. OAA presents the user with the additional challenge pages with factors for authentication.
  5. After the challenge flow is complete, user is redirected back to OAM with success or failure messages.
  6. User is granted access to the resource if the multi-factor authentication was successful.

Configuring OAM with OAA

If you installed using December 24 release or later, this is configured for you during installation. For releases prior to December 24, to configure OAM with OAA, or if you want to know more about how this OAM and OAA integration works, see the tutorial Integrate Oracle Access Management with Oracle Advanced Authentication .

12.2 Integrating OAA with ORA

OAA can be integrated with Oracle RADIUS Agent (ORA) using REST APIs.

OAA Interaction with ORA to Provide Multi Factor Authentication

In the example below an Oracle Database is integrated with ORA and OAA.

  1. User logs in into the Database with a database client (sqlplus) and the user credentials (username/password) are verified.
  2. After authentication, the database invokes ORA for the second factor authentication.
  3. ORA invokes an API to determine the user challenge and presents a challenge prompt for the user:
    1. OAA provides the challenge prompt information.
    2. User is shown a prompt and is asked for an answer by ORA.
  4. ORA redirects to OAA and it validates the answer provided by ORA.
  5. ORA redirects back for resuming the database login session.
  6. User is granted access to the database if the challenge validation was successful.

Configuring ORA with OAA

To configure ORA with OAA, see the tutorial Use Oracle RADIUS Agent with Oracle Advanced Authentication for Multi-Factor Authentication.

12.3 Integrating OAA with OIM

You can implement the password management feature for OAA-protected applications by integrating OAA with Oracle Identity Manager (OIM).

The Forgot Password feature allows the user to request a password reset. Oracle Identity Management (OIM) exposes REST APIs for password management. OAA uses these REST APIs to reset the user password.

The following topics provides an overview of the user interaction flow for OAA-OIM integration through OIM REST APIs.

Topics

12.3.1 Understanding the Forgot Password Flow for OAA and OIM Integration

The Forgot Password flow allows the users to reset their password after successfully answering all challenge questions.

Note:

You must ensure that OIM is integrated with OAM prior to following these steps.

Consider a scenario where the user is at the OAM Login page and clicks the "Forgot Password" link. The Forgot Password feature is implemented as part of OAA. OAM redirects the user to the OAA "Forgot Password" URL, and passes the destination URL to which OAA must redirect upon a successful password change as a query parameter (backURL).

The flow of interactions between the components is as follows:

  1. A user tries to access a resource protected by OAM.
  2. The OAM Webgate (SSO Agent) intercepts the request and redirects the user to the Oracle Access Manager Login Page.
  3. The user clicks on the Forgot Password link on the Oracle Access Manager Login page, which sends the user to the OAA Forgot Password URL.
  4. The user enters the username, which is redirected to KBA for authentication to proceed further to reset the password.
  5. OAA interacts with the user to enable the user to reset the password.
  6. Navigate to the application URL to which access was attempted in step 1. Specify your credentials to log in.

12.3.2 Configuring the Forgot Password Feature

You can integrate OAA with OIM using the OIM REST APIs to configure the forgot password feature.

Prerequisite: You must ensure that OIM is integrated with OAM prior to following these steps.
There are three configurations that you must perform to implement the Forgot Password feature:
  1. Configuring the OAA Admin Console. See Configuring OAA for OIM Integration.
  2. Establishing a connection between OAA and OIM. See Configuring OIM Properties for Integration.
  3. Configuring OAM and OIM integration. See Configuring OAM Forgot Password Link.
12.3.2.1 Configuring OAA for OIM Integration

You must create an integration agent to integrate client applications with OAA. Then, you must create assurance levels for an integration agent and define rules for an assurance level. You can perform these tasks using the OAA Administration UI console.
Perform the following steps 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. Under Quick Actions select Create Other Integration Agent.
  3. Click Manage Integration Agents.
  4. In the Create Integration Agent window, specify the following:
    1. Name: Enter a name for the integration agent, for instance, ForgotPasswordFlowAgent.
    2. Description: Add a description about the integration agent.
    3. Integration Agent Type: From the list, select API.
    4. Click Save.
  5. In the Integration Agents window, click the integration agent for which you need to create the assurance level, for instance ForgotPasswordFlowAgent link.
  6. Under the Assurance Levels tab, click Create.
  7. Specify the required details:
    1. Name: Specify the name for this assurance level, for instance, ForgotPasswordAL.
    2. Description: Provide the description for the assurance level.
  8. Click Create.
  9. Under the Assurance Levels tab, click the required assurance level for which you are required to define rules, for instance ForgotPasswordAL link.
  10. Under Uses select the required factors to assign to the assurance level. In this scenario, select Security Question Challenge only.
  11. Click Save.
12.3.2.2 Configuring OIM Properties for Integration

OAA uses the REST APIs to communicate with OIM for all the user operations. Therefore, you need to establish a connection between OAA and OIM so that the integration happens seamlessly.

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

You need to set the following OIM properties as per your environment, for example:

curl --location -g --request PUT 'https://<PolicyUrl>/policy/config/property/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \
--data '[
{
"name": "oaa.default.user.management.provider.enum.oim.url",
"value": "https://<OIM Managed Server>:<OIM Managed Port>"
},
{
"name": "oaa.default.user.management.provider.enum.oim.admin.username",
"value": "<Username of Oracle Identity Manager Administrator>"
},
{
"name": "oaa.default.user.management.provider.enum.oim.admin.password",
"value": "<Password of Oracle Identity Manager Administrator>"
},
{
"name": "oaa.default.user.management.provider.enum.oim.oaaDefaultGroup",
"value": "<Default Group Name of User>"
}
]'

Note:

  • The <username> and <password> in the preceding command should be related to oaa-policy as they are policy and oaa-related users. Here, <username> refers to <RELEASENAME>-oaa, and <password> refers to <Base64Decoded(oaaapikey)>. For instance, idmenv0025-oaa-policy could be used as a user name.
  • You must note that when you make a PUT call from https://<host>:port>/policy/config/property/v1 and then a GET call from https://<host>:port>/oaa/runtime/config/property/v1?propertyName=oaa.default.user.management.provider.enum.oim, this property requires a few seconds (typically 30 seconds) to retrieve the details from the OAA service config API.

Optional OIM Properties

There are some optional OIM properties that you can configure using the REST APIs.
Property Description
oaa.default.user.management.provider.enum.oim.forgotPassword.queryParamNameForSuccessRedirectUrl=backUrl The value of the parameter is the query parameter name. It refers to the value that you provide for the redirect URL where the user is redirected after successful password change.

Note: You must ensure that the value of backUrl begins with http:// or https:// as follows: https://<host>:<port>/oaa/usermgmt?ojr=forgotpasswordusername&backUrl=https://example.com/

oaa.default.user.management.provider.enum.oim.forgotPassword.successRedirectUrl It refers to the redirect URL to which the user is redirected after successful password change.

Note: If the successRedirectUrl property is present along with queryParamNameForSuccessRedirectUrl property, then the successRedirectUrl takes precedence.

oaa.default.user.management.provider.enum.oim.forgotPassword.ui.configErrorMessage It refers to the error that is thrown if there is an OIM configuration issue. It is as follows: "There is an error, please check with your system administrator."
oaa.default.user.management.provider.enum.oim.forgotPassword.ui.heading It refers to the heading that you provide for the Forgot password screen.
oaa.default.user.management.provider.enum.oim.forgotPassword.ui.userNotFoundMessage It refers to the error message, which is thrown if the user account is not found.
oaa.default.user.management.provider.enum.oim.forgotPassword.ui.factorNotConfigured It refers to challenge questions not configured.
12.3.2.3 Configuring OAM Forgot Password Link

You must configure the OAM and OIM integrated environment so that the Forgot Password link points to OAA instead of OIM for password reset.

Use the following CURL command to update OAM to point to OAA for resetting the password:
curl --user weblogic_idm:<password> -i -H "Content-Type:application/json" -H "Accept: */*" \
-X PUT -d '{"forgotPasswordURL":"https://<SpuiUrl>/oaa/usermgmt"}' \
http://<OAM host>:<OAM port>/oam/admin/api/v1/configurationService/forgotPassword

Note:

For detail on how to find the <SpuiUrl>, see Printing Deployment Details

12.4 Integrating OAA with other Applications

OAA can be intergrated with other applications using REST API's.

The Oracle Advanced Authentication REST APIs provide a way to integrate Oracle Advanced Authentication with REST clients so developers can create applications that can use Oracle Advanced Authentication. For example, application developers can use REST API's to create applications for OAA administration, allow end users to set their factor preferences, or challenge and validate end users for second factor authentication with OAA.

For examples of common REST API calls, see Use Oracle Advanced Authentication REST APIs with Postman.

For a full list of REST API's, see: