Duo for Oracle Access Manager

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.

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 → Protect an Application.
3. 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 with 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.

Duo Universal Prompt

The Duo 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

For Oracle Access Manager applications created before March 2024, migration to Universal Prompt is a three-step process:

1. Install an update for the Oracle Access Manager application, which implements a redirect to Duo during authentication to support the Universal Prompt.
2. Authenticate with Duo 2FA using the updated application so that Duo makes the Universal Prompt activation setting available in the Admin Panel. This first authentication after updating shows the traditional Duo prompt in a redirect instead of an iframe.
3. From the Duo Admin Panel, activate the Universal Prompt experience for users of that Duo Oracle Access Manager application if the traditional prompt is still selected. Once activated, all users of the application see the Duo Universal Prompt in a redirect.

If you created your Oracle Access Manager application before March 2024, 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, before you activate the Universal Prompt for your application.

New Oracle Access Manager Applications

When you install the latest version of Duo for OAM you're ready to use the Universal Prompt. Oracle Access Manager applications created after March 2024 have the Universal Prompt activated by default. 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 "Activation complete", with these activation control options:

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

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 "Update required". To update Duo for OAM application to a newer version, follow the update directions below.

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 "Ready to activate", with these activation control options:

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

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 "Activation Complete" here and on the Universal Prompt Update Progress report.

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. However, this will still deliver the Duo prompt via redirect, not in an iframe. Keep in mind that support for the traditional Duo prompt ended for the majority of applications in March 2024.

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

   

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.

   

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.

   

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.

    

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.

   

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.

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

Network Diagram

1. OAM client connection initiated.
2. Primary authentication at OAM server
3. OIDC redirect to Duo's service.
4. Secondary authentication and client access device checks via Duo Universal Prompt.
5. OAM receives Duo authorization response.
6. OAM user login complete.