Single Sign On (SSO) with PortalGuard by BIO-key

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

Overview

This article covers how to configure PortalGuard by BIO-key to allow Single Sign On authentication with TeamDynamix.

Note that you will only need to configure at most two PortalGuard 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 PortalGuard setup with the production/sandbox Service Provider Identifier.

General Tab

While we do not have a complete new setup walkthrough, set the following sections as follows. Fields not explicitly called out can be modeled after the screenshot below (or however PortalGuard recommends).

Identifiers

This will be the TeamDynamix Entity ID from the TeamDynamix SP metadata for the appropriate region and environment. You should only put in a single identifier.

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 URL

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

Example Screenshot

The following is an example PortalGuard General tab setup provided by a client.

Claims Tab

When you create a claim in PortalGuard, set the following fields as follows:

• Name: A friendly name for the attribute to release to TeamDynamix. This does not change how PortalGuard sends claims, it simply makes it easier to identify what each claim is for in PortalGuard administration.
• Schema Type: Put the TeamDynamix SAML attribute name, in urn:oid format, here (from the Accepted SAML Attributes article in the Related Articles section).
• Value Type: Set to String Field
• Convert Case: If you need to standardize casing of an attribute, change this as necessary. You should set this to to lowercase for the EPPN claim!
• Set the value source as needed from the Direct Field or AttributeValue Attributes section. In the client-provided example, they sourced EPPN from the PortalGuard mail field.

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 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. To accommodate that, this guide will recommend that you release EPPN as a lowercased value.

Example EPPN Claim Screenshot

The following is an example PortalGuard EPPN claim setup provided by a client.

Metadata Exchange

The last step before you can enable and test PortalGuard by BIO-key authentication into TeamDynamix is a metadata exchange. Find your PortalGuard metadata URL and provide this to the TeamDynamix representative you are working with. It is not clear to TeamDynamix where this resides, but typically it is in this format:
https://yourportalguardservername.domain.com/sso/metadata.ashx

TeamDynamix SSO Configuration

1. To enable PortalGuard 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 PortalGuard 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 PortalGuard 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 PortalGuard.

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.