Shibboleth at NC State » Technical Documentation » Two-Factor Attributes

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:

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:

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
<IfVersion < 2.3>
  ShibCompatWith24 On
</IfVersion>
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.