Contents
Simplify self-service device management for your users with a Duo-hosted portal secured by Duo Single Sign-On and featuring the new Universal Prompt experience. Try Duo Central today!
Self-hosted Duo Device Management Portal applications based on Duo Web SDK v2 are not compatible with the Universal Prompt and will reach the end of support on September 30, 2024.
Duo will update the Device Management Portal application with v4 Duo Web SDK support in early 2024. Once available, you will need to update your on-premises Duo Device Management applications to use Web SDK v4 before enabling the Duo Universal Prompt device management experience.
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.
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 |
Read the Universal Prompt Update Guide for more information about the update process and the new login experience for users.
Migration to Universal Prompt for your Device Management Portal application will be a three-step process:
- You update your on-premises Device Management Portal application from Duo Web SDK v2 to Duo Web SDK v4, which will implement a redirect to Duo during device management authentication to support the Universal Prompt.
- Access device management using the updated application so that Duo makes the Universal Prompt activation setting available in the Admin Panel. This first authentication after updating will show the traditional Duo device management experience in a redirect.
- From the Duo Admin Panel, activate the Universal Prompt experience for users of that Duo Device Management Portal application. Once activated, all users of the application will see the Duo Universal Prompt device management experience in a redirect.
We must complete back-end modifications before you can start development efforts to upgrade your application to Universal Prompt. For now, the "Universal Prompt" section of your Device Management Portal's details page shows its status as "Waiting on Duo" with the activation options inaccessible.
After Duo makes the necessary service changes and you have updated your Device Management Portal application to use Duo Web SDK v4, you'll return to the settings on this page to activate the Universal Prompt for your Device Management Portal users.
If you want your users to see the Universal Prompt device management experience now, or do not want to continue maintaining an on-premises Device Management Portal application server, then you can 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:
- Sign up for a Duo account if you don't already have one.
- Log in to the Duo Admin Panel and navigate to Applications.
- 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.
- Download and install a supported Web SDK v2 client library (Python, Ruby, Classic ASP, ASP.NET, Java, PHP, Node.js, ColdFusion, Perl).
- 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)
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',
});
</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()
|
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
- Connection to on-premises device management site initiated
- Primary authentication
- Web application connection established to Duo Security over TCP port 443
- Secondary authentication via Duo Security’s service into the Device Management Portal
- Web application receives authentication response
- Device management session initiated