Integrate Oracle Access Management with Oracle Advanced Authentication

Introduction

This tutorial shows you how to integrate Oracle Access Management (OAM) with Oracle Advanced Authentication (OAA) so users accessing a protected application can login to OAM with Single-Sign On (SSO) and be then challenged with a second factor for multi-factor authentication.

It will also show you how to configure user migration. User migration is a process where a user logs into OAM and that user is automatically migrated to OAA with factors registered based on LDAP attributes defined. The factors registered for each user are based on the LDAP attributes defined in the OAA Authentication Plugin. If a user has any of those LDAP atributes set in OAM’s Default User Identity Store, then those factors are automatically registered for the user in OAA. For the purposes of this tutorial the LDAP attributes mail and mobile are used to set the Email and SMS factors for a user.

Objective

In this tutorial you will perform the following tasks:

  1. Register OAA as a TAP Partner in OAM
  2. Configure the OAM Agent in OAA
  3. Install and configure the OAA Plugin and Modules in OAM
  4. Test the OAM amd OAA integration is successful

Oracle Access Management Prerequisites

Before following this tutorial you must have:

For the purposes of demonstration, this tutorial builds on the environment created in the tutorial series Getting Started with Oracle Access Management 12c. In this environment Oracle Access Management uses Oracle Unified Directory (OUD) as its Default User Identity Store. An application called mybank is deployed to WebLogic Server and protected via an Oracle WebGate. Any references in this tutorial to OAM hostnames, URL’s, PATH’s, and users are based on the ones used in the Getting Started with Oracle Access Management 12c tutorials.

If using the above tutorials for your OAM environment you will need download the sample oaausers.ldif. This file contains users and groups required prior to installing OAA. Edit the oaausers.ldif and update the mail, mobile, and <password> for each user with valid values. This is so you can test that when a user logs (e.g testuser) into OAM, the user will be migrated to OAA with their factors set to SMS and Email. Run ldapmodify -f oaausers.ldif against the OUD to load the users and groups.

Oracle Advanced Authentication Prerequisites

Before following this tutorial you must have:

Register OAA as a TAP Partner in OAM

In this section you register OAA as a Trusted Authentication Protocol (TAP) Partner in OAM.

Objectives

To register OAA as a TAP Partner in OAM.

Register the TAP Partner in OAM

  1. On the OAM server, launch a terminal window as oracle and enter the following command:

    cd /u01/app/oracle/product/middleware/oracle_common/common/bin
./wlst.sh

    The output will look similar to the following:

    Initializing WebLogic Scripting Tool (WLST) ...

Welcome to WebLogic Server Administration Scripting Shell

Type help() for help on available commands

wls:/offline>

  2. Connect to the OAM Administration Server as follows:

    wls:/offline> connect ('weblogic','<password>')

    The output will look similar to the following:

    Successfully connected to Admin Server "AdminServer" that belongs to domain "oam_domain".

Warning: An insecure protocol was used to connect to the server. 
To ensure on-the-wire security, the SSL port or Admin port should be used instead.

wls:/oam_domain/serverConfig/>

  3. Run the following command to regsiter the OAA TAP partner:

    wls:/oam_domain/serverConfig/> registerThirdPartyTAPPartner(partnerName = "<partner_name>", keystoreLocation= "<path_to_keystore>", password="<keystore_password>", tapTokenVersion="v2.0", tapScheme="TAPScheme", tapRedirectUrl="<URL>")

    where :

    • <partner_name> is the name you want to give for the partner application.
    • <path_to_keystore> is the location and filename of the keystore to generate.
    • <keystore_password> is the password for the keystore generated.
    • tapRedirectUrl is any valid http URL. The URL must reachable and return a 200 OK response. Do not use https URL’s otherwise an error message will occur.

    For example:

    registerThirdPartyTAPPartner(partnerName = "OAM-MFAPartner", keystoreLocation= "/tmp/OAMOAAKeyStore.jks", password="********", tapTokenVersion="v2.0", tapScheme="TAPScheme", tapRedirectUrl="http://oam.example.com:7777")

    The output will look similar to the following:

    Registration Successful
wls:/oam_domain/serverConfig/>

    In the example above a keystore /tmp/OAMOAAKeyStore.jks will be generated. This key and password will be used later when registering the OAM as an agent in OAA.

  4. Run the following command to exit wlst:

    wls:/oam_domain/serverConfig/> exit()
Exiting WebLogic Scripting Tool.

Configure the OAM Agent in OAA

In this section you configure an agent for OAM in the OAM Administration Console.

Objectives

To configure an agent for OAM in OAA.

Configure the OAM Agent in OAA

  1. Login to the OAA Administration console with you administrator credentials.g: https://oaa.example.com/oaa-admin

  2. Under Quick Actions select Create OAM Integration Agent.

  3. In Create Integration Agent, Details tab, enter the following:

    • Name: <partner_name> where the value is the same as the TAP Partner Name registered earlier e.g: OAM-MFAPartner
    • Description: OAM TAP Partner for OAA
    • Integration Agent Type: Oracle Access Management
    • Client ID: Click Re-Generate
    • Client Secret: Click Re-Generate
    • Private Key File: Either drag and drop the key file created when registering the TAP Partner e.g /tmp/OAMOAAKeyStore.jks, or click + to select it from the file system
    • Private key Password: <password> The password entered for the keystore when registering the TAP Partner

    For example:

    Description of the illustration createagent.jpg

  4. Copy the Client ID e.g e1d7dd2d-83e2-4ac8-b338-5dbc6348b526 and Client Secret e.g 34e360cf-3ccc-4dcd-911e-0b00e367dcee9 to a safe place as these are required later when configuring OAM.

  5. Click Save

  6. In the Integration Agents screen click the agent just created e.g: OAM-MFAPartner

  7. In Assurance Levels click Create.

  8. In Create Assurance Level enter the following and click Create:

    • Name: OAM-MFA-Level
    • Description: OAM-MFA-Level for OAM Integration

    For example:

    Description of the illustration assurancelevel.jpg

    Note: The value entered for Name will be used later in the OAM OAA Plugin configuration for the ASSURANCE_LEVEL.

  9. In the Assurance Levels tab click OAM-MFA-Level

  10. Under Uses select the Factors for to assign to the Assurance Level, for example: Oracle Mobile Authenticator, Email Challenge and SMS Challenge and click Save.

    For example:

    Description of the illustration definepolicy.jpg

Install and configure the OAA Plugin in OAM

In this section you configure the OAA Plugin in OAM.

Objectives

To configure the OAA Plugin in OAM and to create an associated authentication module to enable integration with OAA for second factor authentication.

Install the OAA Plugin for OAM

Note: If using OAM with April 22 Bundle patch (12.2.1.4.220404) or later, you can skip this section and move to Create an Authentication Module for OAA as the plugin is included in OAM by default.

  1. On the OAA environment where the oaamgmt pod is running, copy the OAA Plugin OAAAuthnPlugin.jar from the pod /u01/oracle/libs directory to a directory on the host machine (e.g /scratch/OAA):

    $ kubectl cp <namespace>/<oaamgmt_pod>:/u01/oracle/libs/OAAAuthnPlugin.jar <directory>/OAAAuthnPlugin.jar

    For example:

    $ kubectl cp oaans/oaamgmt-oaa-mgmt-5c68dc9c57-t2h6w:/u01/oracle/libs/OAAAuthnPlugin.jar /scratch/OAA/OAAAuthnPlugin.jar

  2. Launch a browser and access the OAM Administration console: http://oam.example.com:7001/oamconsole. Login as weblogic/<password>.

  3. Copy the OAAAuthnPlugin.jar over to the machine where the browser is running.

  4. Navigate to Application Security -> Plug-ins -> Authentication Plug-ins.

  5. In the Plug-ins tab select Import Plug-In.

  6. In the Import Plug-in window select Choose File to select the Plug-In File (*.jar). Select the location of the OAAAuthnPlugin.jar and click Import.

  7. On the same page navigate to the Search field and enter OAAAuthnPlugin. Highlight the plugin and select Distribute Selected.

  8. Once the Activation Status of the plugin says Distributed select Activate Selected. The Activation Status should change to Activated.

    For example:

    Description of the illustration oaaauthnplugin.jpg

  9. Close the Plugins-tab.

Create an Authentication Module for OAA

  1. In the OAM console navigate to Application Security -> Plug-ins -> Authentication Modules.

  2. In the Authentication Modules tab click Create Authentication Module then Create Custom Authentication Module.

  3. In the Authentication Module -> General tab enter the following:

    • Name: OAA-MFA-Auth-Module
    • Description: OAA MFA Authentication Module

  4. Click the Steps link and in the Steps tab click Add.

  5. In the Add new step window enter the following and click OK:

    • Step Name: UserIdentificationStep
    • Description: Identify User
    • Plug-in Name: UserIdentificationPlugIn

  6. Click Add again, enter the following and click OK:

    • Step Name: User OAA MFA Step
    • Description: MFA with OAA
    • Plug-in Name: OAAAuthnPlugin

  7. Click Add again, enter the following and click OK:

    • Step Name: PasswordValidation
    • Description: Validate user password on OAM
    • Plug-in Name: UserAuthenticationPlugin

    The module should currently look as follows:

    Description of the illustration modulesteps.jpg

  8. Click User OAA MFA Step and populate the following fields:

    • OAA_URL: <SPUI_URL/authn/v1> for example https://oaa.example.com/oaa/rui/authn/v1
    • TAP_AGENT: <partner_name>. This value should be the name given when registering the TAP Partner with OAM e.g OAM-MFAPartner
    • APPLICATION_ID : <app_id>. This is the name of the OAA group to associate with OAM users that are migrated to OAA e.g Default. This value should match the oauth.applicationid used when installing OAA otherwise end users will not be able to access the User Preferences UI.
    • IDENTITY_STORE_REF: <default_user_identity_store>. This should be set to the value of Default Store set in the OAM console -> Configuration -> User Identity Stores. For example OUDStore
    • ASSURANCE_LEVEL: <assurance_level>. This value should be set to the Assurance Level created in OAA earlier e.g OAM-MFA-Level
    • CLIENT_ID: <client_id>. This is the value of the client ID copied when creating the agent earlier e.g: e1d7dd2d-83e2-4ac8-b338-5dbc6348b526
    • CLIENT_SECRET: <client_secret>. This is the value of the client ID copied when creating the agent earlier e.g: 34e360cf-3ccc-4dcd-911e-0b00e367dcee
    • LDAP_ATTRS: mail,mobile. These are the LDAP attributes set for email address and and mobile number for users in the LDAP server. This allows that user data to be migrated to OAA. Note: LDAP_ATTRS must be specified in lowercase. This is true even if the LDAP attribute is stored in LDAP as camelCase.

    For example:

    Description of the illustration useoaamfastep.jpg

  9. Click Save.

  10. Click Steps Orchestration and from the Initial Step drop down list select User OAA MFA Step.

  11. In the table select the values as follows:

    Name Description On Success On Failure On Error
    UserIdentificationStep Identify User Password Validation failure failure
    Use OAA MFA Step MFA with OAA success UserIdentificationStep failure
    PasswordValidation Validate user password on OAM Use OAA MFA Step failure failure

    For example:

    Description of the illustration stepsorchestration.jpg

  12. Click Apply.

Create an OAA Authentication Scheme

  1. In Application Security Launchpad -> Access Manager, click on Authentication Schemes.

  2. On the Authentication Schemes tab select Create Authentication Scheme

  3. In the “Create Authentication Scheme” tab enter:

    • Name: <scheme_name> e.g OAA-MFA-Scheme
    • Description: OAA MFA Authentication Scheme
    • Authentication Level: 2
    • Challenge Method: Form
    • Challenge Redirect URL: /oam/server/
    • Authentication Module: OAA-MFA-Auth-Module
    • Challenge URL: /pages/login.jsp
    • Context Type: Default
    • Context Value: /oam
    • Challenge Parameters: initial_command=NONE. This parameter allows Passwordless login. See Passwordless Login

    Description of the illustration authnscheme.jpg

  4. Click Apply.

Update the WebGate to use the OAA MFA Scheme for the protected application

Note: In the examples below the webgate webgate_7777 is used and the application URL protected is /mybank. Change accordingly if using something different.

  1. In Application Security Launchpad -> Access Manager click on Application Domains.

  2. In the Application Domain tab click Search.

  3. Click on the WebGate to update e.g: webgate_7777.

  4. In the WebGate tab (webgate_7777), click Authentication Policies. Click Create.

  5. In Create Authentication Policy enter the following and click Apply:

    • Name: OAA_MFA-Policy
    • Authentication Scheme: OAA-MFA-Scheme

  6. In the WebGate tab (webgate_7777) tab, select the Resources tab, click Search, and then click Create.

  7. In the Create Resource tab enter the following and click Apply:

    • Type: HTTP
    • Description: OAA Resource
    • Host Identifier : webgate_7777
    • Resource URL: /mybank/**
    • Operations: ALL
    • Protection Level: Protected
    • Authentication Policy: OAA_MFA-Policy
    • Authorization Policy: Protected Resource Policy

    Note: If you have other /mybank URI’s already protected then update those and change the Authentication Policy to OAA_MFA_Policy

  8. Restart the OAM servers to pick up the new OAA plugin configuration.

Test the OAM and OAA integration

In this section you access the protected application, login to OAM and test that second factor authentication works.

Objectives

To test the OAA and OAM integration works successfully.

Test the OAM and OAA integration

  1. Launch a browser and access the protected application e.g: http://oam.example.com:7777/mybank. As this application is protected you should be redirected to the OAM login page. Log in as the new user testuser/<password>.

    Description of the illustration oamlogin.jpg

  2. If the login is successful you will be redirected to the OAA endpoint e.g: https://oaa.example.com/oaa/authnui. As LDAP_ATTRS for the OAA Plugin in OAM are set to mail,mobile and those LDAP attributes are populated for the testuser, then a challenge choice page is presented for the user to select either EMAIL or SMS. Under Email Challenge select Send OTP to te**@**.com.

    Description of the illustration challengechoice.jpg

  3. You will be redirected to the Email page where you are asked to Enter OTP from the registered email Device1. In the Enter OTP field enter the one time passcode that is emailed to the users email address and click Verify.

    Description of the illustration emailotp.jpg

  4. If the authentication is successful you should be redirected to the protected application page e.g /mybank.

    Description of the illustration mybank.jpg

  5. Close the existing browser and launch a new browser. Access the protected application once more e.g: http://oam.example.com:7777/mybank.

  6. As passwordless login is enabled via the initial_command=NONE parameter in the Authentication scheme OAA-MFA-Scheme the user is not asked to enter the OAM user and password and is directed to choose their second factor authentication method. Under SMS Challenge choose Send OTP to phone 0****3.

    Description of the illustration challengechoice.jpg

  7. You will be redirected to the SMS page where you are asked to Enter OTP from the registered SMS Device. In the Enter OTP field enter the one time passcode that is sent to the users mobile device and click Verify.

  8. If the authentication is successful you should be redirected to the protected application page e.g /mybank.

Learn More

Feedback

To provide feedback on this tutorial, please contact idm_user_assistance_ww_grp@oracle.com

Acknowledgements

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.