TOTP

Overview

The TOTP plugin provides a login flow that implements a bare-bones form of support for TOTP OATH tokens. Any software or hardware token supporting the TOTP algorithm should work. It can be used to piggyback on the existing Password flow's login form view, with an additional field to collect the token code, or it can be run separately with a dedicated view, usually via the IdP's Multi-Factor Authentication feature. In either case, the identity of the subject used to resolve token seeds is generally based on an earlier authentication step.

There are some limitations to understand about this add-on:

• There is no support for enrollment of users and tokens or for managing those enrollments.

• The default implementation provides a couple of options for looking up token seeds for subjects, a static/dummy option for testing and making use of the IdP's Attribute Resolver service to look up (and optionally decrypt) token information at runtime. An extension point does exist for providing alternative token sources, but this interface is not at this time a public API so should be viewed as unstable.

Taken together, this plugin is probably best viewed as either a feature for local extension or as a tool for some limited kinds of deployments where tokens can be managed by hand in some way much as SSH keys often are by small teams.

Plugin Installation

Token Creation and Testing

While this plugin lacks real management functionality, there is a simple command-line tool installed into bin for generating new token seeds and performing test validations.

The output includes the unencrypted, Base32-encoded seed, a URL that can be used to manually install the token into software authenticators, and a URL to a QR code generator for the token.

Generating tokens

$ cd /opt/shibboleth-idp 
$ bin/totpauth.sh --home . --issuer Shibboleth --account jdoe
Seed: 7ZODY4DQQ76DHYL3JK66DJIR3TE3QPW5
URL: otpauth://totp/Shibboleth:jdoe?secret=7ZODY4DQQ76DHYL3JK66DJIR3TE3QPW5&issuer=Shibboleth
QR Code: https://api.qrserver.com/v1/create-qr-code/?data=otpauth%3A%2F%2Ftotp%2FShibboleth%3Ajdoe%3Fsecret%3D7ZODY4DQQ76DHYL3JK66DJIR3TE3QPW5%26issuer%3DShibboleth&size=200x200&ecc=M&margin=0

The same utility also includes a mode for validating codes by supplying both the seed and a code to check.

Configuration

Installing/enabling this module will only populate a few files:

Other than the user interface, which is fairly self-explanatory, the only configuration required is to define how to resolve token seeds to use while validating a particular subject's token codes. This is assumed to be the Attribute Resolver in most "real" cases, but it's also possible to define some static tokens for testing in a Spring configuration file (e.g., conf/global.xml).

Clock Drift

The major problem with TOTP tokens is that they’re subject to clock drift, eventually getting so far out of sync that they start failing. Due to resource constraints, a desire to avoid writing data about each token at runtime, and the limitations of the library used, this plugin is not RFC compliant and does not implement per-token offsets at this time. For the time being, only a global window size and “step size” can be configured, which does address drift, but only globally.

We advise the use of independently synchronized tokens with this plugin.

User Interface

After installation, a view (with some error handling examples) is provided to support a "two-stage" user interface where the token code is collected after an initial factor is completed that will supply the username to this flow. This is designed to work out of the box with a simple "Password flow, then TOTP flow" MFA configuration, much as the Duo flow works.

As an alternative, you may choose to "collapse" the collection process so that the Password login form includes the input field to collect the token code. This would perhaps be appropriate in cases when you impose TOTP as a second factor to all requests. The name of the input field is "tokencode" by default but is controllable with the idp.authn.TOTP.fieldName property. With this approach, the same underlying configuration is used but the flow will try and locate the form field before displaying the second view, and if for some reason the code fails, it will simply fall back to the second view to reprompt for the code.

One note about this: because of the way Spring messages work, unfortunately putting the input field on the Password collection view will not allow use of any Spring message identifiers that are pre-installed with this module, namely "idp.totp.field" for the field label. So you would need to add that to your own conf/messages.properties file or just inline the label.

Finally, for non-browser use, it's also possible to supply the code in a request header, "X-Shibboleth-TOTP" by default, also controllable with a property. Because of this, the flow is installed by default as supporting non-browser use, though if the header is missing there is no user interface to ask for one.

Source of Token Seeds

This plugin supports a public interface to obtain the token seeds for a specific user at runtime. There are two implementations provided, as described below.

$ cd /opt/shibboleth-idp
$ bin/seckeygen.sh --alias totp --count 1 \
	--storefile credentials/totpsealer.jks \
    --storepass password \
    --versionfile credentials/totpsealer.kver

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:util="http://www.springframework.org/schema/util"
       xmlns:p="http://www.springframework.org/schema/p"
       xmlns:c="http://www.springframework.org/schema/c"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
                           http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd
                           http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd"

       default-init-method="initialize"
       default-destroy-method="destroy">

    <bean id="totp.DataSealerKeyStrategy" lazy-init="true"
            class="net.shibboleth.shared.security.impl.BasicKeystoreKeyStrategy"
        p:keystoreType="JCEKS"
        p:keystoreResource="%{idp.home}/credentials/totpsealer.jks"
        p:keyVersionResource="%{idp.home}/credentials/totpsealer.kver"
        p:keyAlias="totp"
        p:keystorePassword="password"
        p:keyPassword="password"
        p:updateInterval="PT1H" />

    <bean id="totp.DataSealer" lazy-init="true"
        class="net.shibboleth.shared.security.DataSealer"
        p:keyStrategy-ref="totp.DataSealerKeyStrategy" />

 </beans>

$ cd /opt/shibboleth-idp
$ bin/sealer.sh --quiet conf/totpsealer.xml enc data

<bean id="shibboleth.authn.TOTP.SeedSource" parent="shibboleth.authn.TOTP.StaticSeedSource">
	<property name="seeds">
		<map>
			<entry key="jdoe">
				<list>
					<value>K44GQWBAI54IQELEGYPDZG5LAJ6EJX73</value>
				</list>
			</entry>
			<entry key="jsmith">
				<list>
					<value>MLDE4YVTA7YKD5NZTDQX65ZPZ2A2OMW2</value>
				</list>
			</entry>
		</map>
	</property>
</bean>

Reference

<list>
    <bean parent="shibboleth.SAML2AuthnContextClassRef"
        c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken" />
	<bean parent="shibboleth.SAML1AuthenticationMethod"
		c:method="urn:oasis:names:tc:SAML:1.0:am:HardwareToken" />
</list>

idp.authn.TOTP.supportedPrincipals = \
    saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken, \
	saml1/urn:oasis:names:tc:SAML:1.0:am:HardwareToken

<util:list id="shibboleth.AvailableAuthenticationFlows">
 
    <bean p:id="authn/TOTP" parent="shibboleth.AuthenticationFlow"
            p:order="%{idp.authn.TOTP.order:1000}"
            p:nonBrowserSupported="%{idp.authn.TOTP.nonBrowserSupported:true}"
            p:passiveAuthenticationSupported="%{idp.authn.TOTP.passiveAuthenticationSupported:true}"
            p:forcedAuthenticationSupported="%{idp.authn.TOTP.forcedAuthenticationSupported:true}"
            p:proxyRestrictionsEnforced="%{idp.authn.TOTP.proxyRestrictionsEnforced:%{idp.authn.enforceProxyRestrictions:true}}"
            p:proxyScopingEnforced="%{idp.authn.TOTP.proxyScopingEnforced:false}"
            p:discoveryRequired="%{idp.authn.TOTP.discoveryRequired:false}"
            p:lifetime="%{idp.authn.TOTP.lifetime:%{idp.authn.defaultLifetime:PT1H}}"
            p:inactivityTimeout="%{idp.authn.TOTP.inactivityTimeout:%{idp.authn.defaultTimeout:PT30M}}"
            p:reuseCondition-ref="#{'%{idp.authn.TOTP.reuseCondition:shibboleth.Conditions.TRUE}'.trim()}"
            p:activationCondition-ref="#{'%{idp.authn.TOTP.activationCondition:shibboleth.Conditions.TRUE}'.trim()}"
            p:subjectDecorator="#{getObject('%{idp.authn.TOTP.subjectDecorator:}'.trim())}">
        <property name="supportedPrincipalsByString">
            <bean parent="shibboleth.CommaDelimStringArray"
                c:_0="#{'%{idp.authn.TOTP.supportedPrincipals:}'.trim()}" />
        </property>
    </bean>
 
</util:list>