Skip navigation
Documentation

Device Management Portal

Contents

Overview

The Duo Device Management Portal is a standalone version of our self-service portal available to Duo Beyond, Duo Access, and Duo MFA plans 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.

Device Management Portal

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). Then you'll add the Duo Device Management Portal into your site by simply 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.

Client libraries are available for Python, Ruby, Classic ASP, ASP.NET, Java, PHP, Node.js, ColdFusion, and Perl. You should be familiar with your web server's programming language and authentication process.

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 Device Management Portal in the applications list. Click Protect this Application to get your integration key, secret key, and API hostname. (See Getting Started for help.)
  4. Download and install a supported 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:

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 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)
Note

sign_request() performs a HMAC-SHA1 of the username, integration key, and an expiration timestamp, using the application's secret key as the HMAC key. By generating this server-side and after primary authentication, Duo is assured that the user is indeed authorized to proceed to the secondary stage of authentication.

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',
    'post_action': 'post_action'
  });
</script>

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

host Your API hostname (i.e. api-XXXXXXXX.duosecurity.com)
sig_request The signed request generated by sign_request()
post_action The server-side URI where secondary authentication results (the signed response) would be POSTed to if this was a standard authentication prompt. While the device management portal application does not actually post a signed response to another URI, this value is required.

Then, you will need to include an IFRAME on the page with an id of duo_iframe. This is where the secondary authentication prompt 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

Network Diagram for Device Management Portal

  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

Ready to Get Started?

Sign Up Free