The Shibboleth V2 IdP and SP software have reached End of Life and are no longer supported. This documentation is available for historical purposes only. See the IDP v4 and SP v3 wiki spaces for current documentation on the supported versions.

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

Configuring Duo authentication for use upon request

Triggering Duo, or any authentication method, by request involves naming that method, including that method in the IdP configuration and then requesting it from the SP.

Naming the method

This is the default name of the authentication method which is generally for normal username/password authentication:

urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

This name is part of a standard namespace.  When selecting your own name, don't just change the ending because your selected name won't actually be part of the standard.

This is the method selected for use at USC:

urn:usc.edu:ac:classes:PasswordProtectedTransport:duo

Modifying this name for your own purposes could be as simple as changing the usc.edu part into an identifier representing your own institution.

Next, configure this into the Duo login handler in the handler.xml of the IdP.  After following their instructions to achieve a basic install, you should have a LoginHandler of type two factor:TwoFactorLogin.  This would normally be configured with this:

<ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</ph:AuthenticationMethod>

Change that to:

<ph:AuthenticationMethod>urn:usc.edu:ac:classes:PasswordProtectedTransport:duo</ph:AuthenticationMethod>

But, of course, using the name you selected.

Modify servlet parameters:

The default configuration in web.xml looks like this:

  <servlet>
    <servlet-name>TwoFactorLoginHandler</servlet-name>
    <servlet-class>com.duosecurity.shibboleth.idp.twofactor.TwoFactorLoginServlet</servlet-class>
    <load-on-startup>4</load-on-startup>
  </servlet>

To configure this servlet to handle only the specific method intended, add the authnMethod init param like so:

  <servlet>
    <servlet-name>TwoFactorLoginHandler</servlet-name>
    <servlet-class>com.duosecurity.shibboleth.idp.twofactor.TwoFactorLoginServlet</servlet-class>
      <init-param>
          <param-name>authnMethod</param-name>
          <param-value>urn:usc.edu:ac:classes:PasswordProtectedTransport:duo</param-value>
      </init-param>
    <load-on-startup>4</load-on-startup>
  </servlet>

SP Request for particular authentication method

There are several ways to cause the SP to cause its initial request to contain the parameter of the desired authentication method.  The easiest way to make this the default is to configure this on the SessionInitiator element for the app in the shibboleth2.xml file.

The SessionInitiator is extremely configurable and can allow for many customizations and different ways of using it.  In the latest releases, this element is not configured by default and the software automatically configures it to the defaults.  The following line can be added to the Sessions element, or it can be used inside of another SessionInitiator of type="Chaining" if you have multiple ways to initiate a session.  In any case, the key attribute is authnContextClassRef.  This attribute is configured on the SessionInitiator of type SAML2.  For example:

              <SessionInitiator type="SAML2" Location="/Login" isDefault="true" template="bindingTemplate.html" authnContextClassRef="urn:usc.edu:ac:classes:PasswordProtectedTransport:duo" forceAuthn="true"/>

It is good practice to use forceAuthn as well in this scenario of increased security so that the IdP will not allow the reuse of an existing authentication.

Ref: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSessionInitiator

Query string session initation

Many of the configurable options on the SessionInitiator can be invoked by a login from a specially crafted query string.  This method can be used as a redirect from within the app when login is needed.  For example:

 https://sp.example.org/Shibboleth.sso/Login?

  forceAuthn=true&authnContextClassRef= urn:usc.edu:ac:classes:PasswordProtectedTransport:duo&target=https%3A%2F%2Fsp.example.org%2Fresource.asp

Ref: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSessionCreationParameters

IdP default authentication method

It is more reliable to make sure the SP requests the method each time, whenever appropriate, but you can also specify a default at the IdP.  This is not enforced, but only used as a suggestion when no specific method was requested.  To configure this default suggested authentication method, edit the relying-party.xml definition for the application.  You may need to make a custom entry separate from the default definition or definitions that cover a group of applications in a metadata file. Once this definition is in place, use the following attribute on the RelyingParty element:

defaultAuthenticationMethod="urn:usc.edu:ac:classes:PasswordProtectedTransport:duo"

Ref: https://wiki.shibboleth.net/confluence/display/SHIB2/IdPRelyingParty

  • No labels