NetIQ Access Manager and Duo Web SDK

Multi-factor Authentication (MFA) has been around for a while but is becoming more and more common in organizations that want to make accessing resources and applications more secure.

Even if you do not know what MFA is, odds are that you have interacted with it at some point in recent years. If you have ever had a website, application, or connection that prompted you to enter a code, push a button on your phone, or click a link in an email after entering your standard username and password then you have performed MFA.

Essentially, MFA is a secondary authentication that is usually tied to an email account, a device (your phone), or a registered application on your phone. Since usernames and passwords can be stolen or hacked, this second authentication provides an extra layer of security to ensure that whoever is attempting to access that resource also controls the registered account/device registered to that user and not just the old-fashioned username and password.

Today there are a number of different vendors out there that provide MFA solutions. One of the forerunners in that space is Duo. Duo offers a number of integration points with their MFA technology. One such integration is the Duo Web SDK. This SDK allows you to create a custom integration component, in various programming languages, that is tailored to fit your needs.

When it comes to securing resources, a lot of companies want to have that multi-layered security while maintaining ease of access for the end-users. This includes Single Sign-On (SSO) capabilities that allow users to enter their credentials once but have access to multiple resources without being prompted to log in to them individually. MicroFocus/NetIQ offers an excellent SSO solution called NetIQ Access Manager (NAM) that works with Duo.

To add Duo SDK to NAM there are a couple of different things that need to be done. For instance, the Duo Web SDK source code is not, in its current offering, plug-n-play ready for NAM. There are some NAM specific additions that need to be coded for before the SDK can be successfully implemented.

Because the Duo Web SDK will be a custom Java class in NAM, there are certain criteria that must be met before the custom class will be recognized by NAM. The NetIQ/Microfocus NAM documentation found here. The NAM 4.4 Appliance Developer Guide details the various calls, required packages, etc. that will be needed in your custom Java project, the only language NAM currently supports.

One of the key details to remember when building your custom Java class for NAM/Duo integration is the identifying attribute in your data store that matches the User ID value in your Duo instance. For example, if your Duo User ID is the user’s email address, then you will need to be sure that your custom authentication class pulls the appropriate email address attribute from your data store and sets it as the duoUserID value.

Side note: Depending on your coding and specific Duo development skills, this value. if it is the same value as the NAM Login ID, can be passed as a parameter from NAM to the Duo custom Java class. More on NAM parameters below.

The creation of the custom Java class is the trickiest part to this integration and is where most failures will occur. It is recommended that the combining of the Duo Web SDK and the NAM custom class requirements be done by someone with Java development experience to ensure a smooth integration. And, while it may be possible to combine the Duo Web SDK source code into your custom Java class for NAM, it is recommended that the two components be separate, i.e. 2 different jar files. This way, if one of the two components needs to be updated due to vendor changes, that component can be recompiled without risk to the other code.

And again, in the custom Java class code, the main thing is to make sure the Duo User ID is leveraging the matching valued attribute in your data store. If the Duo parameter is not receiving the proper information then the Duo SDK calls will fail to find the registered Duo account and MFA will fail with an error that prevents users from accessing the protected NAM resources.

With the custom Java class files created using the Duo Web SDK and the NAM custom class development guidelines (documentation link provided above), the next step is integrating the custom class into NAM and configuring the NAM authentication services to call and pass the required data to the custom class for Duo MFA functionality.

To leverage the Duo MFA functionality within the NAM login screens it does require a custom login page/form in NAM. The Duo Web SDK does include code samples for a login page that includes the proper Duo commands and prompts. This login form can be customized as you see fit so that it meets your organization’s design standards and such. To deploy the custom login form to NAM, please follow the instructions below:

Copy Custom Login Page to NAM Server

  1. Copy the custom .jsp file to the /opt/novell/nids/webapp/jsp directory on the NAM server(s).
    1. Note: If you have more than one NAM server, you will be required to copy this file to each NAM server manually. NAM does not replicate these files among servers in the cluster.
  2. Make sure the file permissions on the new custom login page are set to 644 (rw-r—r–).
    1. NOTE: The owner and group can be set to root or novlwww but the preference is novlwww so that it is consistent with other NAM files. Future security changes or patches may change how NAM accesses this data, so it is better to have it the same as the standard NAM files just in case.
    2. Copy the images and scripts associated with the custom .jsp page to the /opt/novell/nids/webapp/images directory on the NAM server(s).
    3. Note: If you have more than one NAM server, you will be required to copy these files to each NAM server manually. NAM does not replicate these files among servers in the cluster.
  3. Edit the file permissions on the folder/directory and all files contained within to the following rights:
    1. Group: novlwww
    2. Owner: novlwww
    3. Rights: 755 (or rwxr-xr-x)

From here, the next step is to copy the custom Java .jar files to your NAM servers and configure the new NAM authentication process (Class > Method > Contact) to leverage the Duo components and apply them, when/where necessary within the NAM authentication process. To create a basic NAM authentication process that leverages Duo MFA for each login attempt follow the directions below.

Apply Custom Java Class and Configure NAM

  1. Using Java, compile the custom Java classes using the Duo Web SDK.
    1. Note: This may require customization of the Java code to leverage your preferred identity attribute in your LDAP data store that matches the Duo User ID value in Duo.
  2. Copy the custom.jar files to the /opt/novell/nids/lib/webapp/WEB-INF/lib directory of your NAM server(s).
    1. Note: If you have more than one NAM server, you will be required to copy these files to each NAM server manually. NAM does not replicate these files among servers in the cluster.
    2. Note: If you created two jar files (one for the Duo SDK and one for the NAM custom Auth class), both jar files are needed for the Duo method to work properly. If either jar file is missing or not properly set to the correct permissions, then the process will result in errors on the login screens in NAM.
  3. Adjust the permissions of both jar files to the following settings:
    1. Group: novlwww
    2. Owner: novlwww
    3. File Permissions: 644 (or rw-r—r–)
  4. Restart each NAM server the custom jar files were added to. The restart is required for NAM to properly invoke the new Java classes.
    1. Note: Do not proceed to the next step until both jar files are on each NAM server in the specified location and each NAM server has been restarted. If one or more jar files are missing from a NAM server or a NAM server is not restarted, then the Duo related class(es) in NAM for that NAM server will not function properly. It may require the Duo class(es) to be deleted in NAM and recreated before NAM can properly invoke the Duo classes contained within the jar files if the classe(es) are defined before all previous steps have been completed.
  5. In NAM, do the following to create the necessary Duo components:
    1. Create a new NAM class
        1. The Java class path will be required in NAM once “Other” is selected in the Java class selection field. The value must be entered exactly as it appears here unless otherwise changed by your Java developer in the Java project based on the code provided.
        2. “com.novell.nam.authentication.uth.custom.DuoSecurityClass” or whatever your custom Java path may be.


    2. Create a new NAM method


      1. Make sure the Class points to the Duo class created in the previous step.
      2. A User Store is not required for this class since the authentication/authorization process is handled by the Duo Java class and points to your Duo Host defined parameter value.
      3. The duoHOST, duoAKEY, duoIKEY, and duoSKEY parameter values are specific to your Duo instance.
      4. The duoUserID parameter could be added here depending on how the custom Java classes were coded. In some instances, the duoUserID value will be populated in the custom class based on a defined attribute look-up.
      5. MainJSP and JSP are NAM specific properties that tells NAM to use a custom login JSP page named ndus_login.jsp.
    3. Assign the new NAM/Duo method to any authentication contracts desired for DUO integration.

Additional Comments & Suggestions

If you want to use the custom login page for the standard username/password screen instead of the default NAM login page, just add the MainJSP = true< and JSP = <your custom .jsp page name> as properties of the NAM Method(s) being used by your NAM contract(s) where you want to leverage that .jsp page.  (Refer to the DuoSecurityClass screenshot for example usage.)

Be sure to apply/update all NAM configuration changes through the NAM Administration Console for the changes to take effect. While the changes are being applied, NAM services will be temporarily suspended but this process generally only takes a few seconds to complete.  It is generally recommended that such changes be made to a Production level environment during off-peak times to minimize disruption to end-users.

If you want to use a custom authentication query instead of the standard NAM cn/password combo, you can add a parameter to your desired NAM Method(s) to use custom LDAP queries against your configured LDAP data store.  The parameter name is “Query” and the value is your desired LDAP complaint query, for example: “(&(objectclass=person)(|(DirXML-ADAliasName=%Ecom_User_ID%)(cn=%Ecom_User_ID%)))”

Not all organizations will want to use MFA for all authentications. Some organizations may only want to prompt some users for MFA while other users are only required to input the standard username/password. This may be based on a user’s position within the organization, the user’s group memberships within the NAM defined data store(s), or even where in the world the user is attempting to access the target resource from. NAM has the ability to define risk-based policies that can determine if/when a user should be prompted for MFA. If your organization wants to leverage conditional MFA then create the required Risk-based policy, class, and method in NAM, then instead of assigning the Duo NAM Method to a NAM Contract assign the Risk-Based Method. This will allow NAM to prompt for the username/password combo, then perform any risk-based checks to see if Duo MFA is needed for that login attempt, and then the risk-based policy will call the Duo NAM Method to prompt for Duo MFA if the policy determines MFA is needed.

Bonus Information: A Wildcard SSL Certificate allows you to secure your domain name and unlimited sub-domain names using one certificate. Wildcard SSL certificates work similarly to regular SSL certificates securing the connection between your website and the Internet browser your customers use.