Setting up SSO with SAML authentication

Overview

SAML authentication is set up in the following three steps.

1. Set the information required for TimeTracker NX and the linked service.
2. Confirm that linkage is possible.
3. Set the user for whom SSO is enabled

Please check the following link for precautions when setting up. : Precautions when using SAML authentication

Supports SAML2.0.

Setting up TimeTracker NX and the linked service

This time, we will use Microsoft Azure AD as an example to set up TimeTracker NX and the linked service.

The setting screen introduced in this chapter is as of May 2023.

The screen may change depending on the provider. Please check with the provider for details.

1. Log in to TimeTracker NX as a user with administrator privileges and open the system administration screen.

2. Go to the screen shown below and click the "Edit" button.

   

3. Check "Enable sign-on with SAML authentication" (① in the figure below).
   

   "URL (Entity ID)" and "Assertion Consumer Service URL" will be displayed, so copy and paste them into the text.
   

   
   Click ② or ③ to copy the value.

4. Log in to the following link with your Microsoft account: Microsoft 365 Admin Center

5. Click "Azure Active Directory" from the side navigation.

   

6. Click "Users" from the side navigation on the screen after the transition.

   

   The user displayed on the screen after clicking is the user to be linked.
   If any users are missing, add them in advance.

   
   Use the "User Principal Name" displayed on this screen in the next link: Setting users for SAML authentication

7. Click "Enterprise Applications" from the side navigation.

   

   Click "New Application" on the screen after the transition.

   

8. On the screen after the transition, perform the following operations and click "Create".

   
   • ②: Enter a name of your choice.
   • ③: Check this box.

9. Click "Assign Users and Groups" on the screen after the transition.
   

   
   

   Click "Add User or Group" on the screen after the transition.

   

10. On the screen after the transition, perform the following operations to add a user.

    
    1. Click ① to display the setting dialog on the right.
    2. Select the target user from ②. Once selected, it will be displayed in ③.
    3. Click "Select" in ④ to enable ⑤. Click ⑤.

11. Select the following on the screen after the transition.

    

12. Click "Settings" on the screen after the transition.

    

    Click "Add Identifier" on the screen after the transition.

    

13. In the displayed dialog, perform the following operations.

    
    1. Click ① and paste the "URL (Entity ID)" noted in "Step 3" into ②.
    2. Click ③ and paste the "Assertion Consumer Service URL" noted in "Step 3" into ④.
    3. Click Save in ⑤.

14. On the screen after the transition, check that the settings you made in the previous step are reflected, and
    ② Click "Edit" under "Attributes and Claims".

    

15. On the screen after the transition, double-click "Unique User Identifier".

    

    In the dialog that appears, enter "user.mail" in "Source Attribute" and click "Save".

    

16. Click "SAML-based Sign-on" on the screen after the transition to move to the next screen.

    

17. Copy the "App Federation Metadata URL" of "③ SAML Certificate" on the screen after the transition.
    

    You can copy it by clicking ① in the image below.

    

18. Open the URL you copied in the previous step in a browser.
    Search for the keyword "<X509Certificate>" and copy the string between "<X509Certificate>" and "</X509Certificate>".

    ~

    Paste the string you copied here into the "X509 Certificate" setting screen of TimeTracker NX.

    
    If the text to be pasted is insufficient, authentication will not be performed correctly. Please check the range to be copied.

19. Return to the Microsoft Azure AD settings screen and paste the values of the following items in "④ Setup for [Set App Name]" into TimeTracker NX.
    

    Microsoft Azure AD items	TimeTracker NX items
    Login URL	SSO URL
    Azure AD Identifier	Entity ID

    

20. In the TimeTracker settings screen, make sure that "Local authentication and SAML authentication" is checked for "Valid range", and click "Save".

    
    If "SAML authentication only" is checked, you will not be able to log in if the authentication settings have failed.

    First, make sure that SSO integration can be performed correctly with "Local authentication and SAML authentication".

The settings are now complete.
Next, check that the settings are correct.

Check the settings

1. Log out of TimeTracker NX once and log in with an account that has administrator privileges.
   If SSO integration is enabled, the following login screen will be displayed.

   

   Select ② and log in with your TimeTracker NX account and password.

2. Set the key for integration in the user information for which you are attempting SSO integration.
   

   This trial should be performed by the user who operated the Microsoft Azure AD screen in the procedure "Setting up TimeTracker NX and the linked service".
   

   1. Open the user list on the system administration screen.

   2. Enter the "User Principal Name" of the linked Microsoft Azure AD in the "Email" field of the user.

      
      "User Principal Name" is the item displayed on the following screen of Microsoft Azure AD.
      

      

   3. Click the "Test" button of "⑤ Test single sign-on with [set app name]" on the Microsoft Azure AD setting screen.

   

If you can log in to TimeTracker NX, the setup is successful.

This confirms that SSO has been set up.
You can also log in by clicking "Log in with organizational account" on the TimeTracker NX login screen.
You can also close the Microsoft Azure AD screen.

If you cannot log in, check that there are no errors in the setup procedure.

Then, switch the "Valid range" to "SAML authentication only" on the TimeTracker settings screen to disable local authentication.
Next, enable SSO for each user.

Set the user for whom SSO is enabled

Set up SSO for each user.
Set up in the following two steps.

Please check the contents of the following link in advance. : "User setting notes"

1. Set the information for the authentication service.
   Authentication is performed using email addresses as the key.
   For each user, edit "Email" in the same way as in the following link. : "Step 2 of checking the settings"

2. Select the users for whom you want to enable local authentication and enable them.
   Select the target from the user list and check "Allow local authentication" on the editing screen.

   

How to set up multiple users at once

Setting up each user one by one from the settings screen is time-consuming.
You can set up multiple users at once by using the function in the following link. : Export/Import User Information

Notes on user settings

• You cannot set the same email address for multiple users.
• Users who have left "Email" blank and have not checked "Allow local authentication" will not be able to log in.
  Be sure to set one of these.

About users who allow local authentication

• If communication with the SSO authentication destination becomes impossible, SSO authentication may not be possible due to some kind of problem.
  In that case, users who do not have this item enabled will not be able to log in, so
  Please allow local authentication for at least one user.
• On the other hand, if "Allow local authentication" is enabled for many accounts, password management becomes a hassle and security risks arise.
  For example, consider an operation such as "Allow local authentication only for users with system administration privileges."

How to log in with local authentication

When SSO authentication is enabled, the following screen will be displayed when logging in.

Click the red frame above to log in with the account and password you set in TimeTracker NX.

Notes on SSO authentication

Here are some points to note when enabling SSO authentication.
(There is no problem if you do not use the SSO function)

Enable HTTPS access

To use this function, the URL must be SSL authenticated.
Make sure that the URL to access TimeTracker NX starts with "https".

Functions that cannot be used by specifying the login name for users with "SAML authentication only"

Users with "SAML authentication only" cannot specify the login name and password for the following functions.

• Excel integration add-in
• Web API
• TimeTracker Reporting
• TimeTrakcer Analytics

Please use the "API key" for authentication instead of your account name and password.
For details on the API key, please refer to "Generate an API key".

Operational suggestions when using the above functions

There are three methods below.

1. Enable local authentication.
   1. Enable local authentication for all users.
      In the TimeTracker settings screen, set "Valid range" to "Local authentication and SAML authentication".
   2. Enable local authentication only for those who want to use the function.
      Check "Allow local authentication" for the target user in the user settings.
2. Prepare a dedicated account that allows local authentication, and use that account to use the above functions.

Prepare for problems with not being able to connect to the authentication server

If SSO is no longer possible due to some problem, disable SSO using one of the following methods.

1. A user who can also perform local authentication logs in and disables SSO.

2. Forcibly disable SSO.

In the case of 2, the TimeTracker NX server must be restarted.

We recommend that you set it up so that it can be handled using 1.

1. A user who can also perform local authentication logs in and disables SSO

Log in using the procedure in the following link: "How to log in using local authentication"

In the single sign-on settings screen, uncheck "Enable sign-on using SAML authentication".

If another user has forgotten their TimeTracker NX account

Initialize using the procedure in the following link. : "Change password"

2. Forcefully disable SSO

This method updates the configuration file stored on the TimeTracker NX server PC to disable SSO.
Please follow the steps below to resolve the issue.

1. Open "appsettings.json" located directly under the TimeTracker NX installation folder.
2. Search for the keyword "sso" and set the following value to "true".
   

   "Saml": { 
   "ForceDisableSamlSso": false, ←Change this 
   "UseIdpSession": true 
       }, 
3. Reopen the TimeTracker NX login screen.
   

If it is already open, refresh your browser.

You can log in with the login account and password you set in TimeTracker NX.
After the problem is resolved, restore the value you changed in step 2.

If you change the value in step 2, you will see that single sign-on is disabled, as shown in the screen below.