Duo

The Duo authenticator can be used to log users in using Duo, from Cisco. This service provides two-factor authentication using various methods, including:

  • Push notifications to the Duo mobile app
  • SMS-based login where an One-time Password (OTP) is texted to the user
  • OTP generation (also in the Duo mobile app)

Other factors are also available and it is possible for this selection to be automatic based on heuristics and configuration.

The integration with the Curity Authentication Server is similar to that of Encap, BankID, SMS, and other authentication providers. The integration model is shown in Fig. 44:

Overview of Duo integration

Fig. 44 Overview of Duo integration

This diagram is showing that the end user is redirected to the Curity Authentication Server from a service provider application in their user agent, typically a browser (1). This service provider may be a SAML service provider, OAuth client or OpenID Connect Relying Party. Whatever kind of provider, the user is then prompted to identify themselves. Authentication at Duo is then initiated for this user (2). While this takes place, the flow at the Curity Authentication Server is left pending (3). The user authenticates, e.g., by responding to the push notification received to the Duo mobile app (4). When this happens, the the Curity Authentication Server observes this (by making a Web service call to the Duo API) (5). Finally, the user is redirected back to the application that initiated the flow using whatever protocol the service provider was integrated with (6).

Configuration Settings

To setup and configure a Duo authenticator instance, only a few settings are needed:

  • An account manager where users are looked up
  • An authenticator that should be used to authenticate users prior to registeration
  • The Duo API hostname
  • The Duo auth API integration key and secret key
  • The Duo admin API integration key and secret key
  • The factors that should be allowed to be used

The first setting, Duo API hostname, is the same host for both the admin and auth APIs. It is something in the form xyz.duosecurity.com. It and the API integration and secret keys can be obtained from the Duo admin console under Applications. This is shown in Fig. 45:

../../_images/duo-api.png

Fig. 45 Auth API configuration in the Duo admin console

For more details about setting up this application in Duo, refer to the auth API documentation.

The admin API integration and secret keys can be found in the same place in the Duo admin console – under Applications. However, it may need to be enabled by contacting Duo support. Consult the admin API documentation for the details.

“Factors” are the allowed login methods. These include:

  • Auto – the factor that should be used is automatically selected by Duo which will be either a push notificaton or phone call
  • Push – the user is sent a push notification that opens the Duo mobile app where the user will approve the login (shown below in Fig. 55)
  • Mobile OTP – the user, operating the Duo app, visually observe an OTP that is generated by the app and enters it to authenticate themselves
  • SMS – the user is texted an OTP that they will enter into the screens rendered by the Curity Authentication Server to authenticate themselves
  • Phone – the user is called and can approve the login by pressing a preconfigured key on the phone keypad

The last setting is the account manager. This manages where users will be looked up in the Curity Authentication Server. Users must exist in this data source in order to login with Duo.

Refer to the configuration reference for more details.

Creating a New Authenticator

The general process for setting up a Duo authenticator is the same as other types of authenticators. The Duo-specific settings described above must also be configure. This can be done using any of the management interfaces, including the UI, CLI, XML files, and RESTCONF API. In the UI, this page is shown in Fig. 46:

../../_images/duo-authenticator-admin-ui.png

Fig. 46 Configuring a Duo Authenticator in the Admin UI

The required configuration settings are marked with an asterisk and validation is in place to ensure that all fields are properly configure before being committed. Some important parts to take note of include:

  • If registration will be handled outside of the Curity Authentication Server, then it can be disabled. This will allow for cases where credentials might be provided to customers or employees as a part of a signup or onboarding process that does not involve Curity.
  • If registraiton is enabled, then an authenticator must be configured which will be used to authenticate users prior to them being able to register new devices.
  • An authenticator must be configured for registration. This will be used to authenticate the user before they can register a device using Duo.
  • The Show Info Before Registration setting will enable or disable an interstitial page that is shown to the user prior to registration. It provides them with information about where they can download the Duo app and what is about to happen. This provides helpful context, as they would otherwise see whatever screen the registration authenticator renders after clicking Add a New Device (or its localized equivalent).
  • Auto-login after registration can be enabled

After configuring all the required settings, the changes can be committed and the new Duo authenticator can be used by any service provider or OAuth client that is allowed to use it.

Logging In

Tip

To see the entire flow described below, checkout the demonstration video in the resource section of the Curity website.

The login experience of the end user is similar to other authenticators that have a comparable integration pattern to that of Duo (shown in Fig. 44 above), like SMS, Encap, email, etc. The first thing that a user must do is identify themselves. This step involves the user entering their username.

../../_images/screen1.png

Fig. 47 Entering a username

This first step is not shown if some other authenticator has been configured to run prior to the Duo authenticator. In any event, the next screen the user will see is the device selection page:

../../_images/screen2.png

Fig. 48 Selecting a Duo device and registering a new one when none exist

Note

The pages shown in this section can be fully customized like any other. Refer to the developer guide for details.

If the user does not have any devices registered, the page in Fig. 48 is shown. If the user has a registered device, they can still register another on a screen that looks like this:

../../_images/screen2-if-registered-devices.jpg

Fig. 49 Using an existing, registered device or adding a new one

In the former case where the user does not have any devices registered yet, when a new one is added, they will be shown a interstitial page containing information about the use of Duo (if configured). By default, it looks like this:

../../_images/info-screen.png

Fig. 50 Interstitial information page describing how to download the Duo app and register

On this page, the user can:

  • Realize that they are registering, so they are not surprised when asked to authenticate themselves
  • Click the applicable app store icon to download the Duo app for their mobile device
  • Scan a QR code that will help them get the app installed on their mobile device

If the user clicks the QR code, they will be taken to a simple (unauthenticated) page that includes links to download the Duo app for their mobile device. The QR code can be helpful when the user is registering a device other than the one they are on. An example of this page is shown in Fig. 51:

../../_images/duo-download-page.png

Fig. 51 Duo app download page on a mobile device

After authenticating and downloading the app, the user must activate their device. This is done by proving that they are in control of it. For this to happen, the user needs to provide the phone number of the device. They can also provide an alias and specify the device type if they wish:

../../_images/device-data-screen.png

Fig. 52 Entering data about a new device

After doing this, they are presented with the following screen:

../../_images/link-device-screen.jpg

Fig. 53 Linking (i.e., activating or pairing) a device by proving possession of it

On this screen, the user has to prove that they control the device that they are activating. They can do this in a number of ways:

  1. Scan a QR code with the Duo app installed on that device (shown in the video below)
  2. Click a link on the device which opens in the Duo app
  3. Have a link sent to the device via SMS which will open the Duo app

Any of these techniques will pair the device with the user.

After one of these is done, they will see the following screen, concluding the activation / pairing process:

../../_images/reg-finished-screen.png

Fig. 54 Successful completion of device pairing which takes place when a new device is added by a user

After register a new device or if one is already registered, the screen depicted in Fig. 49 will be shown. Here, a user can authenticate using the Duo app on their device by:

  1. Entering an OTP generated by the Duo app
  2. Request an OTP to be sent to them via SMS
  3. Receiving a voice call to their device where they will be able to approve the login using device’s keypad
  4. Receive a push notification that will open in the Duo app.

When the later is used, the user will be presented with a screen similar to the following:

../../_images/push-not-screen.jpg

Fig. 55 Receiving a push notification in the Duo mobile app

Regardless of which method is used to authenticate, after doing so, the flow will complete and the user will be logged in at the Curity Authentication Server.

Tip

To see the entire flow described above, checkout the demonstration video in the resource section of the Curity website.