Skip to content

DUO plugin

Jump to bottom
maduvena edited this page Nov 10, 2020 · 15 revisions

Integrating Duo's 2fa credentials with Casa

DUO's MFA Service

Multi-factor authentication from Cisco's Duo protects your applications by using a second source of validation, like a phone or token, to verify user identity before granting access. Duo is engineered to provide a simple, streamlined login experience for every user and application, and as a cloud-based solution, it integrates easily with your existing technology.

This document will explain how to use Gluu's Duo interception script along with a Plugin in Casa to enroll a user's biometric traits and use it is as a method for 2FA.

In order to use this authentication mechanism your organization will need to register for a DUO account.

Prerequisites

Configure DUO Account

A. Sign up for a DUO account.

B. Setting up DUO Web SDK:

  1. Make the necessary configurations so as to be able to add Duo's strong two-factor authentication to your web application, complete with inline self-service enrollment and Duo Prompt(iframe which enables login and enrollment). The steps are here - https://duo.com/docs/duoweb
  2. Generate an akey. You'll find steps for the same in the same document under "Instructions"
  3. Note that Integration key (ikey), Secret key (skey) and akey (generated from step b.) will be used in /etc/certs/duo_creds.json in the Gluu server.
  4. Note that API hostname will be used in Gluu's interception script as property "duo_host"
  5. Enable the Self-Service Portal - https://duo.com/docs/self-service-portal

C. Setting up Admin API:

  1. Ensure that you have the role of an "owner" in the DUO account (Note that owner role has higher privileges over admin role). To access the Admin API, the required role for it is Duo Owner level Administrator, further details into this here: https://duo.com/docs/adminapi#first-steps. More information to the different administrator roles are here https://duo.com/docs/administration-admins#duo-administrator-roles. To get access to this tab, please ask any of the other admins on the account to raise your permissions to owner level.
  2. Note that ikey, skey will be used in /etc/certs/duo_creds.json in the Gluu server under the name admin_api_ikey and admin_api_skey

Script configurations

Log into oxTrust, and go to Configuration > Person Authentication scripts > duo.

Script contents

Download this file and copy its contents in the Script form field.

Properties

The mandatory properties in the DUO authentication script are as follows

Property Status Description Example
duo_creds_file Mandatory Path to ikey, skey, akey /etc/certs/duo_creds.json
duo_host Mandatory URL of the Duo API Server api-random.duosecurity.com

Contents of duo_creds_file as configured in Properties

  1. Here is a sample file - https://github.com/GluuFederation/casa/blob/version_4.2.2/plugins/duo/extras/duo_creds.json
  2. The contents of the file can be populated by referring to Step 2 and 3 under "Configure DUO Account"

Save changes

Click on Enable under the script contents box, and press Update at the bottom of the page.

Configure oxauth

  1. To integrate the DUO script with casa, the following files should be copied to /opt/gluu/oxauth/custom/pages/casa a. casa.xhtml b. duologin.xhtml c. fullwidth-template.xhtml

  2. Copy oxauth.properties file from here to /opt/gluu/oxauth/custom/i18n/ inside chroot

Plugin installation

Add the plugin to Casa

  1. Download the plugin

  2. Log in to Casa using an administrator account

  3. Visit Administration console > Casa plugins

  4. Click on Add a plugin... and select the plugin jar file

  5. Click on Add

Alternatively you can log into chroot and copy the jar file directly to /opt/gluu/jetty/casa/plugins.

Enable the authentication method

Wait for one minute, then visit Administration Console > Enabled methods and tick duo. On the right, the plugin will be selected by default. Finally save the changes.

Testing

So far, users that log into Casa should be able to see a new entry "DUO credentials" that will appear under "2FA credentials" .

plugins page

The steps to enroll your DUO credentials are self explanatory. Follow the instructions on the web page. You can enroll again or delete your credentials by visiting your registered credential.

plugins page

Note - When you first use BioID you may wish to enroll a few times at different times of days or in different locations under a variety of environmental conditions. Once you can be reliably recognized, you only need to enroll again if something in your face changes significantly (such as after an accident or cosmetic surgery, or if you radically change eyeglasses, facial hair, facial jewelry, etc.) or if you often have to try more than once to be recognized. Once recognized, BioID typically adjusts itself to adapt to the changes right away.

plugins page

Use the biometric credential as a second factor

Ensure you have added another credential, hopefully of a different kind, for example a mobile phone number or an OTP token. Then visit the home page and click the toggle to turn 2FA on and logout. Try to access the application once more and supply the username and password for the account recently used to enroll the biometric credential. Depending on the numeric level assigned to the bioid script, you will be prompted for a different factor, for instance, to enter an OTP code. If so, click on Try an alternative way to sign in and click on Biometric credential.

plugins page

Follow the instructions on the screen for verification of facial and periocular traits.

Finally you will be redirected and get access to the application.

Clone this wiki locally