Single Sign On (SSO) with Okta

Overview

This article covers how other TeamDynamix clients have configured Okta to allow Single Sign On authentication with TeamDynamix.

Okta Configuration Overview

There are three pieces needed for TDX to integrate with Okta. The first is enabling and configuring SSO in TDX. The second is the building the actual SAML configuration in Okta. The third is create bookmarks in Okta to the TDAdmin, TDNext, and the Client Portal(s). The SAML config must be assigned to every user that will log into TDX in any capacity, including TDAdmin, TDNext, and any/all Client Portal(s).

Okta SAML Application Configuration

First, we set up the SAML application config in Okta.

1. Login to your Okta Admin Apps portal: https://yourcompanydomain-admin.okta.com/admin/apps/active
2. And Click Add Application.
   
    
3. Click Create New App.
   
    
4. Click SAML 2.0 and click Create.
   
    
5. Give the app an appropriate name and tick both boxes to not display the app icon to users. This will confuse the users. Click Next.
   
    

6. For single-sign on URL, Recipient URL, and Destination URL copy and paste the appropriate URL for your 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
7. For Audience Restriction, copy and paste the appropriate value for your 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
8. Under Attribute Statements, copy and paste this name: urn:oid:1.3.6.1.4.1.5923.1.1.1.6
9. Change the Name Format to URI Reference and the Value to String.toLowerCase(user.email). You may use any Okta attribute inside of the String.toLowerCase function if email is not your desired username field mapping.
   
   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 as shown above. 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.
    
10. Your Okta SAML application should now look something like the following image:
    
     
11. Scroll down and click Next.
12. Click I’m an Okta customer adding an internal app and click Finish.
    

Okta Bookmark Applications

The second piece(s) is/are to create links in Okta for all of your TDAdmin, TDNext and Client Portal(s).

1. Login to your Okta Admin Apps portal: https://yourcompanydomain-admin.okta.com/admin/apps/active
2. Click Add Application.
   
    
3. In the search bar, type in bookmark and choose Bookmark App.
   
    
4. Click Add.
   
    
5. Give the Application Label a name (TDAdmin, TDNext, Client Portal name, etc.) and add in the URL for one of your TDX sites. Click Done.
   
    
6. Repeat this second piece for every portal you’d want to grant access to. For example, you might want one bookmark application for TDAdmin, one for TDNext and one for each client portal. Then, assign each app to the appropriate team members. Remember the SAML application must ALSO be assigned to all team members that will be using TDX in any capacity.

Metadata Exchange

The last step before you can enable and test Okta authentication into TeamDynamix is a metadata exchange. Find your Okta metadata URL and provide this to the TeamDynamix representative you are working with.

You can navigate in Okta to the Sign-On tab of the application you've created > Settings > SAML 2.0 to find your metadata URL, which should look like this: https://yourOktaDomainHere/app/yourOktaAppIDHere/sso/saml/metadata

TDX Configuration

Last, we'll need to enable SSO in TDX. 

1. From HOME, click on the Security Tab.
   
    
2. Click Configure SSO.
   
    
3. Paste the entity ID from your Okta 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 Okta metadata URL in a browser. If unsure, have your TeamDynamix representative help you identify it.
   

4. Click Enable SSO.

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-3 in the above TDX 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.