Two-Factor Attributes

We are using Duo Security to provide Two-Factor Authentication to service providers authenticated by Shibboleth. Our IdP servers are configured to preauth a user at Duo to determine if they have a Duo account. Users who do have an account will be asked to provide their Duo credential. Users who are not yet enrolled will bypass the Duo check.

Some of our Service Providers may wish to determine if a user is enrolled in Duo, and if they actually had to authenticate using Duo for the current session. To aid this, we have added these two attributes to our release policy for NCSU Federation members.

ncsuEnrolledTwoFactor (env SHIB_2FENROLL)

We pull the enrollment list from Duo Security and use it to populate this value in our attribute. Users who have just enrolled in Duo will take 3-9 hours to see a change in this value from Shibboleth.

Values are:

Y = The user was enrolled in Duo at the last time we polled.
N = The user is not enrolled in Duo.

ncsuAuthedTwoFactor (env SHIB_2FAUTHED)

During the Shibboleth login, we run a preauth check at Duo to see if the user is required to authenticate to Duo in addition to using their password. After the authentication has completed, we populate this value to indicate if the Duo flow was used.

Values are:

Y = The user was presented with the Duo authentication page and successfully passed it.
- The user presented the correct password, was found in Duo, and successfully provided their Duo credential.
- This could also mean the user previously checked the remember me for 30 days cookie, and did not need to provide a Duo credential this time.
- This could also mean the user logged in with Duo earlier within the same IdP session, so they did not have to provide their password or Duo again.
- Rarely, this could also mean the user has an account in a state such that Duo told us to authenticate the user. Duo then bypassed the actual 2FA authentication, and returned a success.
N = The user bypassed the Duo authentication. The login only used password.
- Most of the time, this means the user is not enrolled in Duo, so Duo told us to bypass the authentication.
- Rarely, this could also mean that the Duo was unreachable, so the Duo credential could not be checked.

Most of the time both of these attributes will return the same value. If the user is enrolled, they should be required to auth to Duo. If they are not enrolled but did auth, it probably means our enrollment data is slow to update. If they are enrolled but did not auth, it probably means there's something wrong with the Duo service so the check was bypassed.

Using These Attributes

These attributes were added to our IdP servers in July, 2017. If you have a Service Provider that you configured before this date, you will need to update your attribute mappings file to read the values into your environment.

Get the latest copy of the Sample 3.0 attribute-map.xml and replace or update the copy on your Service Provider, as follows:

# on your server, as root
cd /etc/shibboleth
wget https://docs.shib.ncsu.edu/docs/sample30-attribute-map.xml
diff sample30-attribute-map.xml attribute-map.xml
    # this is optional, to review any changes
    # before you replace the file
cp sample30-attribute-map.xml attribute-map.xml
service shibd restart
    # or "systemctl restart shibd" - on newer linux

If you have a test SP page, you should be able to login to that URL and see the variables SHIB_2FENROLL and SHIB_2FAUTHED in your environment.

Using these attributes in .htaccess files

It is possible to setup an access rule on your directory such that a user must be enrolled or authed with two-factor to visit the site. The .htaccess rules would look like this:

AuthType shibboleth
ShibRequestSetting requireSession true
require shib-attr SHIB_2FAUTHED Y

The problem with using this is the user will simply be blocked from the site with a generic error message if they did not use Duo during their login. The user-friendly way to handle this is to let all authenticated users access the site, but then write some code into your page(s) to catch the users with SHIB_2FAUTHED=N and give them a page that asks them to enroll in Duo before returning.