Single Sign On (SSO) with Azure Active Directory (Azure AD)

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

Overview

This article covers how to configure Azure Active Directory (Azure AD) to allow Single Sign On authentication with TeamDynamix. Note that you will only need to configure at most two Azure AD applications: one for production + sandbox, and another for release preview. This is because Azure AD only allows a Service Provider Identifier to be registered a single time and TeamDynamix only has a single, multi-tenant service provider which covers both production and sandbox. This effectively means you cannot have different Azure AD applications for both production and sandbox. Production and sandbox will be covered by a single Azure AD application with the production/sandbox Service Provider Identifier.

Azure AD Configuration

Note that the Azure AD configuration examples shown below were made using the new Azure AD experience UI. You can perform the same configurations in the old UI (if that is still available to you), but the screens may not align 100% with the screenshots below. If you would like to switch to the new Azure AD experience UI to follow this guide exactly, click the Try out our new experience button at the top of the Single sign-on configuration page.

Create a new Azure Active Directory application

1. In your Azure Portal, navigate to Azure Active Directory > Enterprise Applications and choose + New Application.
   
   
    
2. Select the Non-gallery application option.
   
   
    
3. Enter a Name for the application and click Add to finish.
   
   
    

Configure Application Single sign-on

1) Basic SAML Configuration

1. In the application you just created, go to the Single sign-on tab and choose the SAML box.
   
   
    
2. Choose the edit icon in the Basic SAML Configuration box.
   
   
    
3. In the Identifier (Entity ID) field, enter the TeamDynamix Entity ID.
   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
       
4. In the Reply URL (Assertion Consumer Service URL) field, enter the proper Assertion Consumer URL.
   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
5. If you desire, enter a value for Sign on URL. If entered, this value will be where you are redirected to when you choose this application from Azure or Office 365. Typically this would be to your TDNext or TDClient sign in page so that you are automatically redirected in as authenticated (SP-Initiated authentication).
6. Your setup should now look similar to the image below (Canadian clients will see the Canadian Entity ID and Reply URL). Click Save to complete the basic configuration.
   
   

2) User Attributes & Claims

1. Choose the edit icon in the User Attributes & Claims box.
   
   
    
2. Remove any existing claims except for the default one used by the Name Identifier value.
3. Click the + Add new claim button.
   
   
    
4. In the Name field, enter the value urn:oid:1.3.6.1.4.1.5923.1.1.1.6 . This is the EPPN attribute and 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.
5. Leave the Namespace field blank.
6. Set the Source field to Transformation.
   For most attributes, you would generally only need to use a simple (and direct) Attribute source. 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 via a transform.
7. In the Manage Transformation blade that opens, select ToLowercase() as the Transformation option.
8. Select the Azure AD field from the Parameter 1 dropdown that you would like to release as the value for this attribute. Common choices are user.userprincipalname or user.mail .
9. Your new transformation should look as follows. Click the Add button to save the transformation.
   
   
    
10. Your final attribute setup should look as follows. Click the Save button to create the attribute.
    
    
     
11. Using the related Accepted SAML SSO Attributes TeamDynamix KB article as a guide, repeat steps 3 - 8 to add any other SAML attributes you wish to release to TeamDynamix. Common attributes released include givenName (first name), sn (surname, last name), and mail (email address) since they are the bare minimum SAML attributes needed to perform SSO-based self-registration. When releasing attributes, be sure to always use the urn:oid: format for attribute names from the KB (like EPPN uses) and always leave the Namespace blank.

3) User/Group Access Settings

The organization must decide how they want to grant access to the Azure AD application to their users. There are two general ways to do this, with pros and cons to each approach.

Application Level Access

At the application level properties, do not require user assignment to use the application. This approach lets any user in the Azure AD directory pass through the Azure AD application for authentication to TeamDynamix. This does not, however, implicitly grant them access to TeamDynamix. TeamDynamix still requires an internal user record, with a username value matched to the Azure AD value released in the eppn attribute, to be authorized for TeamDynamix sign in.

To use this method, go to Manage > Properties > User assignment required? and select No. You should read the help text by clicking the icon next to this option to understand the full options for this method.

Explicit User/Group Access Grants

If you want to have more specific control over who is allowed to pass through the Azure AD application for authentication into TeamDynamix, leave the application level setting above set to Yes. Instead, go to Manage > Users and groups and assign specific users and/or groups who can pass through this application. Any user/group not specified in this page will be prevented at the Azure AD side of the SSO authentication flow from continuing on into TeamDynamix! Again, users/groups allowed in this page will not be implicitly granted access to TeamDynamix. TeamDynamix still requires an internal user record, with a username value matched to the Azure AD value released in the eppn attribute, to be authorized for TeamDynamix sign in.

Metadata Exchange

The last step before you can enable and test Azure AD SSO authentication into TeamDynamix is a metadata exchange. Copy the App Federation Metadata Url link from the SAML Signing Certificate box and provide this to the TeamDynamix representative you are working with.

Once TeamDynamix has confirmed that your metadata is registered in their service provider, you may move on to configuring and enabling SSO in TeamDynamix.

TeamDynamix SSO Configuration

1. To enable Azure AD SSO 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. In Azure AD, copy the Azure AD Identifier field from the Set up [application name] box.
   
   
    
4. Paste the value from Step 3. into the Entity ID field in the TeamDynamix SSO Settings page (reached from Step 2.).
5. 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-5 in the above TeamDynamix SSO Configuration section for production to enable things there with no further configuration or changes needed to Azure AD.

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.