SAML setup guide (OKTA)

Step 1 - Get Service Provider (SP) information from Workstars

1. Login to your Workstars Administrator account (must be the primary account or technical user)
2. Click on System Settings at the top
3. Click Sign On from the left-nav menu
4. Click the Setup button next to the Single Sign On (SAML) option
5. Select OKTA
6. From the Service Provider section, save a copy of the ACS URL and Entity ID as you will need these in the Step 2

Step 2 - Add Workstars app to OKTA

1. Login to OKTA as an administrator
2. Click Admin in the top right
3. In the right side shortcuts menu, choose Add Applications
4. In the search box, enter 'Workstars' and click the Add button
5. In the Application label box, enter the name you want to show on the dashboard or leave the default
6. In the Subdomain box, enter your Workstars subdomain (e.g if your program URL is https://something.workstars.com then your subdomain is 'something')
7. Select the appropriate Application visibility options or leave the defaults
8. Click Next
9. Assign a test user (you can return to this process later and assign your users and groups) and click Next
10. Click Done
11. Click the Sign On tab
12. Click the View Setup Instructions button
13. Scroll down and copy the SAML SSO URL, Identity Provider Entity ID, x.509 Certificate and Remote Logout URL, as you will need them in Step 3

Step 3 - Configure sign on to use OKTA

1. Log back into your Workstars Administrator account
2. In the top bar select System Settings
3. On the left-nav menu, select Sign On
4. Click Setup next to the Single Sign On (SAML) option
5. Select OKTA
6. In the SAML SSO URL box, enter the SAML SSO URL you copied in Step 2
7. In the Identity Provider Entity ID box, enter the Identity Provider Entity ID you copied in Step 2
8. In the x509 Certificate box, enter the x.509 Certificate you copied in Step 2
9. In the Remote Logout URL box enter the Remote Logout URL you copied in Step 2
10. Leave the NameID as the default Email (We also support EmployeeID, but configuring OKTA is outside the scope of this document, please contact OKTA support)
11. Click Confirm to save the settings

Step 4 - Test & enable

The setup is now complete, but it is NOT yet visible for employees on the login page.

When you are ready, you must enable it:

1. On the System Settings Sign On page, click the Enable button next to Single Sign On (SAML)
2. Copy the test link
3. Open an Incognito/InPrivate browser tab and paste in the link
4. You should be redirected to the OKTA login page
5. If you login, you should be redirected back to our system and automatically logged in

   Note

   If you haven’t already done so, we recommend that you log back into OKTA and assign all your users and groups at this time

6. If the test worked, go back to the other browser window and click the Enable button
7. If you experience any errors please check the settings are correct; If you need further assistance, please capture any error message screens and contact support

You have now enabled Single Sign On (SAML) for all employees; Check the login is working:

• Visit your Workstars login URL (not the test one), it should be something like: https://<your-sub-domain>.workstars.com
  • You should be redirected to the OKTA login page and asked to login
  • If you are already logged in, you should be redirected back and logged into our system
• Employees can also login directly from the OKTA dashboard
  • To test this, go to the dashboard and click the app
  • You should be redirected to our site and logged in

Troubleshooting

On our login page it says “Sorry we could not find your account, please contact your HR Team”

Strictly speaking this isn't an error. The reason is that you have tried to login via SAML but the account you have used does not have a matching account in our system. To resolve it simply create an account in our system with the same details. If you are not using email as the nameID please check that the alternative is the same in both systems (e.g. employeeID, extnernaID, etc.) and that it is being correctly sent in the SAML request.

On our login page it says “There is a problem with Single Sign On, please contact your IT department”

This is a general error and means that there is something wrong with the setup. Please check it is setup as described above, if you have followed a different guide (some providers also have their own guides) please start again using this document as a guide. If you have checked everything and cannot find any issues please contact support and we will help you resolve the problem.

I can login from the Identity Providers portal but when I try and login from the Workstars login page it redirects me to a message that says “page not found” or another error

This is usually because you have entered an incorrect SAML SSO URL, please check it is correct. If you have checked and cannot find any issues please contact support and we will help you resolve the problem.