A Shibboleth IdP v5.X plugin for delegating authentication to an external SSO Server using the CAS protocol

This is a Shibboleth IdP external authentication plugin that delegates primary authentication to an external Single Sign On Server using the Central Authentication Server protocol. The biggest advantage of using this component over the plain REMOTE_USER header solution provided by Shibboleth is the ability to utilize a full range of native CAS protocol features such as renew and gateway, plus the ability to share with CAS the EntityID of the relying application.

The plugin takes advantage of and extends the Shibboleth IdP's external authentication flow, and consists of a number of JAR artifacts that bridge the gap between Shibboleth and CAS.

Maintenance Status

Please note that Unicon will no longer be upgrading nor maintaining this plugin any longer. That decision is based on best practices concerning the modern Shibboleth and CAS Server software packages. The Shibboleth IdP and the CAS Server support the same SSO protocols, and the best strategy is to decide which of those two SSO packages best meets your needs and only keep that one, migrating all services to it. If,for whatever reason, both SSO solutions are still required, the recommended approach is to use SAML (authentication) delegation to achieve the same results that this plugin provides now.

Software Requirements

This minimum supported version of Shibboleth Identity Provider is 5.2.1. See releases to find the the appropriate version.

Installation

Overview

• Download and extract the "latest release" zip or tar from releases.
• Copy the no-conversation-state.jsp file (also found inside this repo in IDP_HOME/edit-webapp) to your IdP's IDP_HOME/edit-webapp
• Copy two included jar files (cas-client-core-x.x.x.jar and shib-cas-authenticator-x.x.x.jar) into the IDP_HOME/edit-webapp/WEB-INF/lib.
• Copy and Update the IdP's web.xml.
• Update the IdP's authn.properties file.
• Rebuild the war file.

NOTE: You should ALWAYS refers to the README.md file that is packaged with the release for instructions.

Update the IdP's authn.properties file

In the IDP_HOME/conf/authn/authn.properties file, ensure the context path points to Authn/External as shown below.

#### Update the IdP's authn.properties file

1. Set the `idp.authn.flows` to `External` in `IDP_HOME/conf/authn/authn.properties`. Or, for advance cases, add `External` to the list if you have others.
2. Add new properties for the ShibCas plugin.

```properties
...
idp.authn.flows = External

idp.authn.External.externalAuthnPath = contextRelative:Authn/External

shibcas.casServerUrlPrefix = https://cassserver.example.edu/cas
shibcas.casServerLoginUrl = ${shibcas.casServerUrlPrefix}/login

shibcas.serverName = https://shibserver.example.edu

# By default you always get the AuthenticatedNameTranslator, add additional code to cover your custom needs.
# Takes a comma separated list of fully qualified class names
# shibcas.casToShibTranslators = com.your.institution.MyCustomNamedTranslatorClass
# shibcas.parameterBuilders = com.your.institution.MyParameterBuilderClass

# Specify CAS validator to use - either 'cas10', 'cas20' or 'cas30' (default)
# shibcas.ticketValidatorName = cas30


# Specify if the Relying Party/Service Provider entityId should be appended as a separate entityId query string parameter
# or embedded in the "service" querystring parameter - `append` (default) or `embed`
# shibcas.entityIdLocation = append

# Specify if you decide to embed entityId in querystring, CAS can decide MFA based on entityId.
# In that case you do not want to cache the result (when 'true')
# Otherwise when 'false' (default), the first successful CAS login will be kept
# (alternative is to use "idp.session.enabled = false" but you loose SLO)
#shibcas.doNotCache = false

# Specify the default Authentication Context Class in the MFA context,
# It is useful when there is no authentication context class provided by CAS or no requested principal context available in the authentication context
# Default is the IdP AuthnContext.PPT_AUTHN_CTX ('urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport')
# (it will be for example 'https://refeds.org/profile/sfa' when only the REFEDS profiles are used)
#shibcas.defaultAuthnContextClass = urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

...

Rebuild the war file

From the IDP_HOME/bin directory, run ./build.sh or build.bat to rebuild the idp.war. Redeploy if necessary.

OPTIONAL EntityId / CAS Service Passing

By setting shibcas.entityIdLocation=embed, shib-cas-authn will embed the entityId in the service string so that CAS Server can use the entityId when evaluating a service registry entry match. Using serviceIds of something like: https://shibserver.example.edu/idp/Authn/External\?conversation=[a-z0-9]*&entityId=http://testsp.school.edu/sp or https://shibserver.example.edu/idp/Authn/External\?conversation=[a-z0-9]*&entityId=http://test.unicon.net/sp will match as two different entries in the service registry which will allow as CAS admin to enable MFA or use access strategies on an SP by SP basis.

OPTIONAL Handling REFEDS MFA Profile

The plugin has native support for REFEDS MFA profile. The requested authentication context class that is https://refeds.org/profile/mfa is passed along from the Shibboleth IdP over to this plugin and is then translated to a multifactor authentication strategy supported by and configured CAS (i.e. Duo Security). The CAS server is notified of the required authentication method via a special authn_method parameter by default. Once a service ticket is issued and plugin begins to validate the service ticket, it will attempt to ensure that the CAS-produced validation payload contains and can successfully assert the required/requested authentication context class.

The supported multifactor authentication providers are listed below:

• MFA Simple (Requesting authn_method=mfa-simple and expecting validation payload attribute authnContextClass=mfa-simple)
• Duo Security (Requesting authn_method=mfa-duo and expecting validation payload attribute authnContextClass=mfa-duo)
• FIDO2 WebAuthn (Requesting authn_method=mfa-webauthn and expecting validation payload attribute authnContextClass=mfa-webauthn)
• Google Authenticator (Requesting authn_method=mfa-gauth and expecting validation payload attribute authnContextClass=mfa-gauth)
• Yubikey (Requesting authn_method=mfa-yubikey and expecting validation payload attribute authnContextClass=mfa-yubikey)
• Radius (Requesting authn_method=mfa-radius and expecting validation payload attribute authnContextClass=mfa-radius)
• Inwebo / Trustbuilder (Requesting authn_method=mfa-inwebo and expecting validation payload attribute authnContextClass=mfa-inwebo)
• ESUP-OTP (Requesting authn_method=mfa-esupotp and expecting validation payload attribute authnContextClass=mfa-esupotp)

REFEDS MFA Profile Configuration

In the IDP_HOME/conf/authn/authn.properties file, ensure the following settings are set:

shibcas.casToShibTranslators = net.unicon.idp.externalauth.CasMFARefedsAuthnMethodTranslator
shibcas.parameterBuilders = net.unicon.idp.authn.provider.extra.CasMultifactorRefedsToXXXXXAuthnMethodParameterBuilder

Finally add the authn context refs in the supported principals property list to in IDP_HOME/conf/authn/authn.properties as shown below.

idp.authn.External.supportedPrincipals = \
    saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport, \
    saml2/https://refeds.org/profile/sfa, \
    saml2/https://refeds.org/profile/mfa

Release Notes

See here.

Developer Notes

The project distributables can be built using ./gradlew clean build. The artifacts will be in build/distributions.

This project includes a Docker environment to assist with development/testing.

To build and execute: ./gradlew clean; ./gradlew up Then browse to: https://idptestbed/idp/profile/SAML2/Unsolicited/SSO?providerId=https://sp.idptestbed/shibboleth

You'll need a hosts file entry that points idptestbed to your Docker server's IP address.

The IdP only has a session of 1 minute (to test expired session/conversation key issues), so login into CAS Server quickly.