How to set up Single Sign-on / MFA (Cisco DUO)

The end user experience

1. The user will enter their username and password as usual.  
2. After clicking the logon button, they will be redirected to DUO security to perform another factor of authentication.  This may be a DUO Push, a request for a 6 digit password or any other additional authentication factor that DUO has available.
3. When the user successfully completes the additional factor in DUO, DUO will redirect the user back to SchoolFi or the Employee Portal.

Buzz words

• Cisco DUO - Provides Multi Factor Authentication to other applications as a service.
• OIDC – OpenID Connect.  This is the protocol / standard that is used by SchoolFi to communicate with Cisco DUO to hand off the Multi Factor Authentication process.   OIDC is an extension to the OAuth 2 protocol that defines the mechanisms for Authentication. 
• https://openid.net/connect/
• OAuth 2.0 – OAuth 2.0 is the industry-standard protocol for authorization.  https://oauth.net/2/

Setup Process overview

• Create the SchoolFi and SchoolFi Employee Portal Applications in DUO
• Configure SchoolFi to use the DUO MFA applications as OIDC Providers.
• Setup SchoolFi for MFA
• Setup individual Users and/or Employee Portal users to use the DUO MFA.

Create/protect SchoolFi and SchoolFi Employee Portal Applications in DUO

The following steps will not affect users logging into SchoolFi or the Employee Portal.

1. Log into DUO as an administrator.
2. In the left panel, choose the 44809950 link.
3. Click the Protect an Application button or the Protect an Application link.
4. Click the Protect button for the Web SDK application in the list of applications.
5. Click the Activate Now button when asked if you would like to Activate the Universal Prompt for Web SDK
6. Go to the Settings section and change the name of the application from Web SDK to SchoolFi.
7. Repeat steps 2 through 6, but the name in step 6 will be SchoolFi Employee Portal

Configure SchoolFi to use the DUO MFA applications as OIDC Providers.

Create the SchoolFI MFA Provider

The following steps will not affect users logging into SchoolFi or the Employee Portal.

1. Log into SchoolFi as an Administrator
2. Go to the System -> Security -> Single Sign-on / MFA -> Providers screen.
3. Click the Add Providerbutton.
   1. Code: DUO_MFA_STAFF  (or DUO_MFA_PORTAL for the Employee Portal Setup)
   2. Provider: Cisco DUO
   3. Description: DUO MFA
   4. Type: Multi-Factor Authentication
   5. Client Id: Copy and paste these fields from the Schoolfi application setup screen.
   6. Client Secret: Copy and paste these fields from the Schoolfi application setup screen.
4. On the modify DUO_MFA_STAFF page, make the following changes:
   1. Click the SchoolFi checkbox (leave the Employee Portal Unchecked.. do the opposite if you are setting up the Employee Portal Application)
   2. Change the DNS name in the end point from https://CHANGEME.duosecurity.com to the one in the API hostname field in the SchoolFi application setup screen in DUO.
   3. Click the Save button to save the changes

Testing Connectivity between SchoolFi and DUO

Basic connectivity

Click the Send OAuth 2.0 Ping button.   This will send a basic test ping to Cisco DUO.  You should get this as a response:

If you are not getting that as a response, the most likely problem is that a firewall in your organization is blocking the request to DUO.  Do not advance to the next step until this is working.

API Configuration Test

Click the DUO Health Check button.   This will send a more advanced ping that validates the application id and secret part of the protocol connection.

If you are not getting that as a response, the most likely problem is that one of the values in the Client Id, Client Secret or URL End Point Root is incorrect.  Do not advance to the next step until this is working.

Repeat the steps above for the Employee Portal application.

Once completed, the Providers screen should look like this:

Configuring SchoolFi Users to use DUO for MFA

Choose a user to test the MFA with Cisco DUO from the System -> Security -> Users screen.

Do not choose the user you are currently logged in as, you do not want to accidentally lock yourself out of the system if the feature is not setup correct.

Change MFA Provider drop down to the DUO MFA option and click save.

The Single Sign-on Id field should now display a warning if there is no value in it.  This must match the username or one if it’s aliases as it appears in the Cisco DUO Users screen.

Using a different browser (or log out of your current session); attempt to login as this user.

Configuring Employee Portal Users to use DUO for MFA

Choose an employee portal user to test the MFA with Cisco DUO from the Setup-> Employee Portal -> Users screen.

Do not choose the user you are currently logged in as, you do not want to accidentally lock yourself out of the system if the feature is not setup correct.

Change MFA Provider drop down to the DUO MFA option and click save.