Skip navigation
Documentation

Duo for Oracle Access Manager

Last Updated: September 23rd, 2021

Duo integrates with Oracle Access Manager to add two-factor authentication to your single sign-on logins, complete with inline self-service enrollment and Duo Prompt.

Duo's plug-in for Oracle Access Manager supports Oracle Access Manager 11g and later. The plugin supports FORM and COOKIE RequestCacheType configurations.

Before you install Duo for OAM, determine a Redirect URL to which the Duo plugin should redirect back to after successful two-factor authentication, which usually is the embedded credential endpoint for your OAM instance. An example URL example for ECC basic authentication flow would be https://<<oam-server-host>>:<<port>>/oam/server/auth_cred_submit. The redirect URL must use https and specify the server by hostname, not by IP address, with a maximum length of 1024 characters.

Connectivity Requirements

This application communicates with Duo's service on TCP port 443. Firewall configurations that restrict outbound access to Duo's service with rules using destination IP addresses or IP address ranges aren't recommended, since these may change over time to maintain our service's high availability. If your organization requires IP-based rules, please review this Duo KB article.

First Steps

If you already have a previous version of the Duo OAM plugin installed, you must remove it before installing the v2 Universal plugin. See the steps in the Update the Duo Plugin section for more information..

  1. Sign up for a Duo account.
  2. Log in to the Duo Admin Panel and navigate to Applications.
  3. Click Protect an Application and locate the 2FA-only entry for Oracle Access Manager in the applications list. Click Protect to the far-right to configure the application and get your Client ID, Client secret, and API hostname. You'll need this information to complete your setup. See Protecting Applications for more information about protecting applications in Duo and additional application options.

    Previously, the Client ID was called the "Integration key" and the Client secret was called the "Secret key".

  4. Download the latest DuoUniversalPlugin.jar 2.x.x plugin file from GitHub.

Treat your client secret like a password!

The security of your Duo application is tied to the security of your client secret. Secure it as you would any sensitive credential. Don't share it with unauthorized individuals or email it to anyone under any circumstances!

Duo Universal Prompt

The new Universal Prompt provides a simplified and accessible Duo login experience for web-based applications, offering a redesigned visual interface with security and usability enhancements.

Universal Prompt Traditional Prompt
 Duo Push in Universal Prompt  Duo Push in Traditional Prompt

Migration to Universal Prompt for your Oracle Access Manager application is a two-step process:

  • Install an update for the Oracle Access Manager application to support the Universal Prompt.
  • Activate the Universal Prompt experience for users of that Duo Oracle Access Manager application.

Before you activate the Universal Prompt for your application, it's a good idea to read the Universal Prompt Update Guide for more information about the update process and the new login experience for users.

New Oracle Access Manager Applications

When you install the latest version of Duo for OAM you're ready to use the Universal Prompt. If you're configuring Oracle Access Manager now, proceed with the installation instructions in this document.

The "Universal Prompt" area of the application details page shows that this application is "New Prompt Ready", with these activation control options:

  • Show traditional prompt: (Default) Your users experience Duo's traditional prompt when logging in to this application.
  • Show new Universal Prompt: Your users experience the Universal Prompt when logging in to this application.

Universal Prompt Info - Application Ready for Universal Prompt

Existing Oracle Access Manager Applications

Duo for OAM needs a software update installed to support the Universal Prompt. The "Universal Prompt" section of your existing Oracle Access Manager application reflects this status as "App Update Ready". To update Duo for OAM application to a newer version, follow the update directions below.

Universal Prompt Info - Update Available

Once a user authenticates to Duo for OAM via the updated Duo plugin, the "Universal Prompt" section of the Oracle Access Manager application page reflects this status as "New Prompt Ready", with these activation control options:

  • Show traditional prompt: (Default) Your users experience Duo's traditional prompt when logging in to this application.
  • Show new Universal Prompt: Your users experience the Universal Prompt when logging in to this application.

Universal Prompt Info - Application Ready for Universal Prompt

In addition, the "Integration key" and "Secret key" property labels for the application update to "Client ID" and "Client secret" respectively. The values for these properties remain the same.

Activate Universal Prompt

Activation of the Universal Prompt is a per-application change. Activating it for one application does not change the login experience for your other Duo applications.

Enable the Universal Prompt experience by selecting Show new Universal Prompt, and then scrolling to the bottom of the page to click Save.

Once you activate the Universal Prompt, the application's Universal Prompt status shows "Update Complete" here and on the Universal Prompt Update Progress report.

Universal Prompt Info - Universal Prompt Activation Complete

Should you ever want to roll back to the traditional prompt, you can return to this setting and change it back to Show traditional prompt.

Universal Update Progress

Click the See Update Progress link to view the Universal Prompt Update Progress report. This report shows the update availability and migration progress for all your Duo applications in-scope for Universal Prompt support. You can also activate the new prompt experience for multiple supported applications from the report page instead of visiting the individual details pages for each application.

Import the Duo JAR file

  1. Sign into your Oracle Access Manager administrative console on your OAM server and click Application Security in the top right-hand corner.

  2. On the launch pad page click Authentication Plug-ins located under "Plug-ins".

  3. On the "Plug-ins" page click Import Plug-in....

  4. Browse to and select the DuoUniversalPlugin.jar file you downloaded earlier. Click Import to import the Duo JAR file.

  5. Click the refresh button on the "Plug-ins" page to reload the plug-ins.

  6. Scroll through the listed plug-ins and select DuoUniversalPlugin. It will show an "Activation Status" of Uploaded.

  7. Fill out the Client ID, Client Secret, API hostname, Redirect URL, and Fail mode fields located under "Plug-in Details: DuoUniversalPlugin"

    Client ID Your Client ID or Integration key from the OAM application in the Duo Admin Panel.
    Client Secret Your Client secret or Secret key from the OAM application in the Duo Admin Panel.
    API hostname Your API hostname from the OAM application in the Duo Admin Panel.
    Redirect URL The embedded credential endpoint URL for your OAM instance (example: https://<<oam-server-host>>:<<port>>/oam/server/auth_cred_submit).
    Fail mode Either safe or secure:
    failmode Description
    open In the event that Duo's service cannot be contacted, users' authentication attempts will be permitted without 2FA if primary authentication succeeds. (Default)
    closed In the event that Duo's service cannot be contacted, all users' authentication attempts will be rejected.
    User Store Optional. If you'd like to use a different user identity store from the default system store, enter the name of the store here. Enter the store name exactly as shown in the "OAM ID Stores" table on the "User Identity Stores" configuration page.

    When all the fields have been populated click Save.

    Upload DuoPlugin JAR file to OAM

  8. Once you've successfully saved the settings click the Distribute Selected button at the top of "Plug-ins" section. Click the refresh button to refresh the plug-ins page. The "Activation Status" will change to Distributed.

  9. With the "DuoUniversalPlugin" selected click Activate Selected. Wait a moment for the page to reload and then click the refresh button. It will show an "Activation Status" of Activated.

    Activated DuoPlugin JAR file to OAM

Add Duo to an Authentication Module

Once the Duo plug-in has been uploaded and activated, add Duo to an existing authentication module and tell the plug-in how to respond during logins.

  1. While logged into the administrative console for Oracle Access Manager click Application Security in the top right-hand corner of the screen.

  2. On the launch pad page click Authentication Modules located under "Plug-ins".

  3. On the "Authentication Modules" page click on the authentication module to which you want to add Duo as an authentication step.

  4. Click on the "Steps" tab. Click the + button to open the "Add new step" wizard.

  5. Type Duo Universal for Step Name.

  6. Leave the Description field blank.

  7. Select DuoUniversalPlugin from the drop-down for Plug-in Name and click OK to add the new Duo step.

    Create a new step in the authentication module

  8. Click on the "Steps Orchestration" tab. You should see the Duo Universal as the last step in the list.

  9. For the step immediately preceding Duo, change the On Success selection to Duo Universal using the drop-down. This means that if that step succeeds, the next step should invoke Duo authentication.

  10. For the "Duo Universal" step, set On Success to success using the drop-down.

  11. Set both the On Failure and On Error for the "Duo Universal" step to failure using the drop-down.

  12. Click the Apply button. The page reloads confirming the module update.

    Configure the authentication module

You can repeat these steps to add Duo Universal 2FA to other authentication modules.

Restart Oracle Access Manager

The Duo plug-in requires that the Oracle Access Manager must be restarted before the plug-in can be used. There are two different methods for restarting Oracle Access Manager.

Method One

Restart Oracle Access Manager through the WebLogic console.

  1. Sign into your WebLogic administrative console on your OAM server.

  2. On the WebLogic administrative console click Environment in the left-hand side menu.

  3. Click Servers on the "Summary of Environment" page.

  4. On the "Summary of Servers" page click the Control tab.

  5. Locate your Oracle Access Manager server and click the checkbox next to it. Click the Shutdown button and choose between the shutdown options.

  6. Once the server is completely shut down click Start.

    Protect an Application Domain with Duo 2FA

Method Two

Restart Oracle Access Managers through scripts

  1. While signed into the Oracle Access Manager server locally with a terminal open or through SSH, navigate to the bin directory of your Oracle Access Manager server.

    Example: $ORACLE_HOME/user_projects/domains/your_domain_name/bin

  2. Shutdown the Oracle Access Manager server by running the command below. Replace MANAGED_SERVER_NAME with the name of your Oracle Access Manager server, in this example it is oam_server. Replace ADMIN_SERVER_URL with the URL of your Oracle Access Manager console, an example would be https://oam.yourcompany.com:7001.

    ./stopManagedWebLogic.sh MANAGED_SERVER_NAME ADMIN_SERVER_URL

  3. Once the server has shut down, run the following command to start up the server using the same values from the last step.

    ./startManagedWebLogic.sh MANAGED_SERVER_NAME ADMIN_SERVER_URL

    Note: If you are running WebLogic and Oracle Access Manager on Windows instead of Linux replace stopManagedWebLogic.sh with stopManagedWebLogic.cmd and startManagedWebLogic.sh with startManagedWebLogic.cmd.

Test Duo 2FA

Once your Oracle Access Manager server has been successfully restarted, log into an Application Domain protected with Duo. Enter your primary directory logon information, approve Duo two-factor authentication, and get redirected to your site after authenticating.

OIDC Duo Prompt *Universal Prompt experience shown.

Congratulations! Oracle Access Manager is now protected with Duo two-factor authentication.

Logging

Duo for Oracle Access Manager logs are saved within the normal Oracle Access Manager log files located at $ORACLE_HOME/user_projects/domains/your_domain_name/servers/your_oam_server/logs/.

Update the Duo Plugin

There is no direct update path from v1 of the Duo OAM plugin to v2. If you need to update from to v2 you should completely remove the existing v1 plugin and configuration from your OAM server, and then download the v2 plugin JAR and follow the rest of the installation steps.

To remove the v1 Duo plugin from OAM:

  1. Edit any OAM Application Domain to which you added Duo to remove that rule.
  2. Delete any authentication schemas you created for the Duo v1 plugin and WAR file.
  3. Remove the v1 "Duo 2FA" authentication module.
  4. Go to the OAM Plug-ins page and first deactivate and then remove the v1 "Duo Plugin".
  5. Edit your WebLogic deployment's application assistants to delete the "DuoLogin" deployment and corresponding DuoLogin.war file.
  6. Verify that OAM login works without Duo, and then install the Duo v2 OAM plugin and update your authentication modules.

Troubleshooting

Need some help? Take a look at our OAM Knowledge Base articles or Community discussions. For further assistance, contact Support.