Duo Device Management Portal for End Users

Overview

The Duo Device Management Portal is a standalone version of our traditional prompt self-service portal available to Duo Premier, Duo Advantage, and Duo Essentials plan customers. Instead of presenting device management options alongside the Duo login prompt for a protected service, this application puts your users directly into the device management interface and can be deployed independently from any other service requiring Duo two-factor authentication for access.

The Device Management Portal permits users new to Duo to enroll their first authentication device, while also allowing existing users to add and remove authentication devices or configure options for their devices without needing to contact IT staff for help.

See our end-user guides to Managing Your Devices to learn more about the self-service tasks available to users and Enrollment to see the enrollment process. The Device Management Portal experience differs from inline enrollment and self-service by not displaying the "Continue to Login" or "Back to Login" buttons. Additionally, the Duo prompt presented to users from the Device Management Portal does not attempt an automatic push or phone call request to a user's default device, disregarding the "Automatically send this device a Duo Push" or "Automatically call this device" selection for that device's default authentication options.

Before deploying the Duo Device Management Portal you'll need an on-premises web server, configured for primary authentication to your user directory (such as AD or OpenLDAP). You should be familiar with your web application's programming language and authentication process.

Then you'll add the Duo Device Management Portal into your site with the Duo v2 Web SDK by adding a second login page that invokes the Duo application. After successfully passing primary credentials and approving Duo authentication, users gain portal access. When a user has finished updating devices, they should close the page to end the session.

Web SDK v2 client libraries are available for Python, Ruby, Classic ASP, ASP.NET, Java, PHP, Node.js, ColdFusion, and Perl.

Universal Prompt Support

Neither the OIDC-based Duo Web SDK v4 nor the Universal Prompt user experience supports the Device Management Portal application. The application details in the Duo Admin Panel do not include the Universal Prompt status information or enablement setting, and attempts to use the v4 Web SDK with this application type result in errors.

Deploy Duo Single Sign-On and enable the self-service portal in Duo Central to provide device management access to users outside of authentication to a protected application.

First Steps

Before starting:

1. Sign up for a Duo account if you don't already have one.
2. Log in to the Duo Admin Panel and navigate to Applications.
3. Click Protect an Application and locate the entry for Device Management Portal in the applications list. Click Protect to the far-right to configure the application and get your integration key, secret key, 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.
4. Download and install a supported Web SDK v2 client library (Python, Ruby, Classic ASP, ASP.NET, Java, PHP, Node.js, ColdFusion, Perl).
5. Use NTP to ensure that your server's time is correct.

To ensure no users unintentionally bypass the portal, we recommend applying a new custom application policy to your Device Management Portal application with the following settings:

• New User Policy: "Require Enrollment"
• Authentication Policy: "Enforce 2FA"
• User Location: No locations set to "Allow access without 2FA"
• Remembered Devices: "Do not remember devices

Also verify that users who need to manage their devices via the portal have active status.

Instructions

1. Generate an akey

Your akey is a string that you generate and keep secret from Duo. It should be at least 40 characters long and stored alongside your Device Management Portal application's integration key (ikey), secret key (skey), and api_host in a configuration file.

You can generate a random string in Python with:

import os, hashlib
print(hashlib.sha1(os.urandom(32)).hexdigest())

2. Call sign_request()

After you perform primary authentication (e.g. look up a user's username and password in your directory), you should call sign_request() which initializes the secondary authentication process.

sign_request() takes the Duo Device Management Portal application's ikey and skey, the akey you generated, and the username of the user of the web application who just successfully completed primary authentication. (If users can change their usernames, you'll probably want to use something that won't change, like an email address or primary key.)

For example, in Python:

sig_request = sign_request(ikey, skey, akey, username)

3. Show the Duo Device Management Portal

After generating the signed request, your server should now display a second page that will contain the Duo Device Management Portal authentication prompt within an IFRAME.

Duo's JavaScript handles the setup and communication between the IFRAME, the user, and your server. First, you will need to include a short snippet of JavaScript in the page.

<script src="/path/to/Duo-Web-v2.js"></script>
<script>
  Duo.init({
    'host': 'host',
    'sig_request': 'sig_request',
  });
</script>

In this example, Duo.init() takes the following options:

Then, you will need to include an IFRAME on the page with an id of duo_iframe. This is where the Duo device management portal will appear.

You may specify width and height attributes directly on the IFRAME tag. This is the simplest way to display the frame, but it may not fit on mobile devices. For example:

<iframe id="duo_iframe" width="620" height="330" frameborder="0"></iframe>

If you would like the frame to fit on smaller screen devices, like phones and tablets, you should use CSS to set the frame's dimensions:

<iframe id="duo_iframe" frameborder="0"></iframe>
<style>
  #duo_iframe {
    width: 100%;
    min-width: 304px;
    max-width: 620px;
    height: 330px;
  }
</style>

To make sure the page's width and zoom is set correctly for smaller screen devices, you may want to add a viewport meta tag to your page's header:

<head>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  ...
</head>

To ensure that Internet Explorer renders the page in standards mode, add this meta tag to the top of your HTML <head>.

<meta http-equiv="X-UA-Compatible" content="IE=edge">

When this page loads, the JavaScript snippet will set up the IFRAME, prompt the user for secondary authentication, provide access to the device management options.

Network Diagram

1. Connection to on-premises device management site initiated
2. Primary authentication
3. Web application connection established to Duo Security over TCP port 443
4. Secondary authentication via Duo Security’s service into the Device Management Portal
5. Web application receives authentication response
6. Device management session initiated