Overview
When implementing SSO in TeamDynamix, we recommend using an immutable username strategy.
This is due to the system requirements for implementing SAML SSO to the core Work Management product:
- A fully qualified (user@domain.com) username value must be sent to TeamDynamix in a SAML AttributeStatement via the EPPN attribute.
- The EPPN attribute is scope validated.
- This means that the domain portion of the username is verified against a list of allowed domains for the TDX tenant.
- Username scope/domain validation is performed in a case-sensitive manner.
- Transforming the value to all lowercase is recommended whenever possible.
- SSO logins containing usernames with a scope that is not explicitly trusted by TeamDynamix are rejected.
Currently, it's not possible to change username values in bulk. There are no APIs or imports that can be leveraged to update these fields if a mass username format change is needed.
Immutable Username Strategy
While many online products and systems recommend using email addresses as a username, this is problematic in TeamDynamix Work Management due to the above requirements. Email addresses tend to be values that update when things like legal name changes or preferred name changes occur.
Instead, we recommend leveraging the transformation capabilities that most identity systems have to construct an unchanging username value on the fly, based off of a unique identifier for your organization. This might be a value such as (but not limited to):
- Employee ID
- Banner / Colleague ID (for Higher Education clients)
- ERP System unique ID (ex: PeopleSoft ID)
- Microsoft Entra (Azure) object ID
Using Employee ID as an example, the resulting TeamDynamix Work Management username value would end up being constructed by concatenating a static domain string with the existing identity system attribute value for employee ID.
This formula might be something like:
employeeID_Attribute + "@mydomain.com"
The resulting value might be as follows:
11234@mydomain.com
Identity System Examples
Below are a few specific examples of how to implement a constructed immutable username strategy with common identity systems.
The examples below are models to help users get started.
- We do not have examples for every identity platform and you will likely need to modify the examples to some degree to best fit the needs of your organization.
- For example, you may need to chose a different attribute for the identifier value.
Microsoft Entra ID (formerly Azure Active Directory)
In this example, we will be using user.employeeid as the basis of constructing a claim for username (eppn) in the application's Attributes & Claims > Additional claims section. The claim will also be transformed to all lower-case to ensure a consistent casing for scope validation values.
Claim Screenshots:
Note that in the second image above, you are able to type in the Attribute name choice box for Parameter 2. Instead of choosing a value, type your domain the textbox, then select it from the resulting choice this creates.
Okta
In this example, we will be using an imaginary Okta attribute called user.employeeID. TeamDynamix is not as familiar with Okta's out-of-the-box attributes to suggest a recommendation as to what to pick. Presumably you would need to have some employee ID-type attribute available for selection via Okta's user attributes. Use whatever that value would be in your case as needed.
The claim value for the Okta Attribute Statements item named urn:oid:1.3.6.1.4.1.5923.1.1.1.6 attribute would be something like the following:
String.toLowerCase(user.employeeID + "@mydomain.com")
Refer to the Okta Expression Language guide for more detailed information on how to construct and format values.