Single Sign On (SSO) with Apereo Central Authentication Service (CAS)

This how-to article will help Administrators to review the set up of Single Sign On with Apereo CAS. The user must have the “Modify Authentication Settings” Admin permission.

Overview

This article covers how to configure Apereo CAS to allow Single Sign On authentication with TeamDynamix, based upon version 5.1.5.

Note that you will only need to configure at most two Apereo CAS setups: one for production + sandbox, and another for release preview. This is because TeamDynamix only has a single, multi-tenant service provider which covers both production and sandbox. Production and sandbox will be covered by a single Apereo CAS setup with the production/sandbox Service Provider Identifier.

General

These were the instructions provided to TeamDynamix by a customer utilizing CAS 5.1.5:

Here are a few notes regarding how we got TeamDynamix working with our CAS 5.1.5 servers.

Initial setup:
I won't go into too much detail with how to setup CAS. The salient items are that we are using a CAS Overlay:
https://apereo.github.io/2017/03/28/cas5-gettingstarted-overlay/

...we setup CAS to do SAML2:
https://unicon.github.io/cas/5.1.x/installation/Configuring-SAML2-Authentication.html

...and we added the following lines to our /etc/cas/config/cas.properties file to make the server a SAML2 Identity Provider:

cas.authn.samlIdp.entityId=https://ourEntityID/idp/shibboleth
cas.authn.samlIdp.scope=ourscope.edu
cas.authn.samlIdp.metadata.cacheExpirationMinutes=30
cas.authn.samlIdp.metadata.failFast=true
cas.authn.samlIdp.metadata.location=file:/etc/cas/saml

Setting up the TeamDynamix service:
First, we removed the TeamDynamix entityID from our InCommon service definition in /etc/cas/services. 
Then we set up TeamDynamix. This was simply a matter of creating a metadata file that only has the TeamDynamix endpoints, and putting it in /etc/cas/metadata/teamdynamix-metadata.xml

NOTE FROM TEAMDYNAMIX: Retrieve metadata from the Obtaining the TeamDynamix SP SAML Metadata article in the Related Articles section. Be sure to use the appropriate type of metadata based on region/environment/vanity domain status.

After that was done, we created a TD service definition in /etc/cas/services/TeamDynamix-1018.json - I have also attached this file. The most important aspect of this file was to send the needed user attributes, and to send both the friendly name as well as the OID identifier. For example, to send givenName, we had to configure it thusly:

givenName: urn:oid:2.5.4.42

At this point, everything worked just fine.

NOTE FROM TEAMDYNAMIX: The referenced TeamDynamix-1018.json file is attached to this article in the Attachments section.

TeamDynamix Basic SAML Information

Entity ID

This will be the TeamDynamix Entity ID from the TeamDynamix SP metadata for the appropriate region and environment.

1. For United States SaaS Customers:
   1. Production and Sandbox: https://www.teamdynamix.com/shibboleth
   2. Release Preview: https://shib.teamdynamixpreview.com/shibboleth
2. For Canadian SaaS Customers:
   1. Production and Sandbox: https://shib-cac.teamdynamix.com/shibboleth
   2. Release Preview: https://shib-cac.teamdynamixpreview.com/shibboleth
3. For Installed (on-prem) Customers: Get this from your Service Provider software

Assertion Consumer URLs

This will be the main Assertion Consumer URL from the TeamDynamix SP metadata for the appropriate region and environment.

1. For United States SaaS Customers:
   1. Production and Sandbox: https://shib.teamdynamix.com/Shibboleth.sso/SAML2/POST
      
      Note: If you have a vanity URL, and only for production/sandbox, replace shib.teamdynamix.com in the URL with your custom domain. If you are unsure whether or not you have a vanity URL, see if the domain in your normal TeamDynamix URL ends with teamdynamix.com. If it does, you do not have a vanity URL. Any URL in *.teamdynamix.com format is not a vanity URL
      
      Vanity URL Example: https://my.customdomain.edu/Shibboleth.sso/SAML2/POST
       
   2. Release Preview: https://shib.teamdynamixpreview.com/Shibboleth.sso/SAML2/POST
2. For Canadian SaaS Customers:
   1. Production and Sandbox: https://shib-cac.teamdynamix.com/Shibboleth.sso/SAML2/POST
      
      Note: If you have a vanity URL, and only for production/sandbox, replace shib.teamdynamix.com in the URL with your custom domain. If you are unsure whether or not you have a vanity URL, see if the domain in your normal TeamDynamix URL ends with teamdynamix.com. If it does, you do not have a vanity URL. Any URL in *.teamdynamix.com format is not a vanity URL
      
      Vanity URL Example: https://my.customdomain.edu/Shibboleth.sso/SAML2/POST
       
   2. Release Preview: https://shib-cac.teamdynamixpreview.com/Shibboleth.sso/SAML2/POST
3. For Installed (on-prem) Customers: Get this from your Service Provider software

EPPN Attribute Release

You will need to create at least one claim for the EPPN urn:oid:1.3.6.1.4.1.5923.1.1.1.6 attribute. This is the SAML attribute TeamDynamix will use as the username value for authentication. This value must be a scoped, or fully qualified value in the format of user@domain. You should lowercase this value if at all possible (perhaps via some sort of transform?) to ensure standard casing of values in TeamDynamix. For most attributes, you would generally not need to lowercase the value. However, TeamDynamix only allows specific username domains through for usage during the SAML metadata exchange, and domain checking is case-sensitive. Due to this, it is highly recommended to transform values outbound from the IdP to lowercase if at all possible.

Metadata Exchange

The last step before you can enable and test Apereo CAS SAML authentication into TeamDynamix is a metadata exchange. Find your Apereo CAS metadata URL and provide this to the TeamDynamix representative you are working with. It is not clear to TeamDynamix where this typically resides.

TeamDynamix SSO Configuration

1. To enable Apereo CAS authentication in TeamDynamix, log into the TeamDynamix Admin application or navigate there from the TDNext application menu option.
2. From your organization details page, click the Security tab and then click the Configure SSO button.
3. Paste the entity ID from your Apereo CAS metadata into the Entity ID field in the TeamDynamix SSO Settings page (reached from Step 2.. Your entity ID will be in the top node of the XML file produced by navigating to your Apereo CAS metadata URL in a browser. If unsure, have your TeamDynamix representative help you identify it.
4. You may now Save and Enable SSO for testing at your convenience. Do not close your TeamDynamix Admin window or browser tab yet! Proceed on to the Testing SSO Authentication section below for testing strategies.

Testing SSO Authentication

TeamDynamix strongly recommends testing this in your sandbox environment first! Once you are satisfied that all is working in the sandbox, you may simply repeat steps 1-4 in the above TeamDynamix SSO Configuration section for production to enable things there with no further configuration or changes needed to Apereo CAS.

When testing, a recommended approach is to use one browser (for instance Google Chrome) to have the TeamDynamix SSO Settings page open in. Use a second browser (such as Firefox) to actually test that SSO authentication is in fact working. With this approach, if SSO authentication is not working or is in some way broken, you may quickly toggle SSO off back in the first browser with the TeamDynamix SSO Settings page. You can then safely troubleshoot the issues found and not be locked out of the system until you are ready to test again.