Duo

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

The integration with Identity Server is similar to that of Encap, BankID, SMS, and other authentication providers. The integration model is shown below:

This diagram is showing that the end user is redirected to Identity 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 Identity 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 Identity 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 below:

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
• 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 Identity 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 Identity 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 below:

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 Identity 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#

The login experience of the end user is similar to other authenticators that have a comparable integration pattern to that of Duo (shown 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.

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:

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

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:

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 below:

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:

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

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
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:

After register a new device or if one is already registered, the screen above 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:

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