How to setup Single Sign On (SAML)

Step 1 - Get Service Provider (SP) information

To configure your Identity Provider you will need to get some information from Workstars:

1. Login to the Administrator Portal (you must be the primary account or technical user)
2. Click on System Settings in the top right
3. Click the Sign In tab
4. In the Single Sign On (SAML) section, click the "add an identity provider" link
5. Select your Identity Provider (or Generic if its not listed)
6. The information you need to configure your Identity Provider (e.g. ACS URL, Entity ID, etc.) will be displayed. Please save these values as they will be needed in Step 2.

Step 2 - Configure your Identity Provider

Login to your Identity Provider and follow the process for adding a Service Provider (might be called an Application or similar). You will need the details from Step 1.

Once configured, you must find and save a copy of the the following values:

• Sign on URL
• Issuer
• Signing Certificate (signature algorithm must be SHA256)

The above values might have different names based on which Identity Provider you are using. We have a few guides based on the most popular Identity Providers:

• Microsoft Entra ID
• OKTA
• Google Workspaces
• OneLogin

Step 3 - Add your Identity Provider

Once your Identity Provider has been setup you need to add it to Workstars:

1. Login to the administrator portal (you must be the primary account or technical user)
2. Click on System Settings in the top right
3. Click the Sign In tab
4. In the Single Sign On (SAML) section, click the "add an identity provider" link
5. Select your Identity Provider (or Generic if its not listed)
6. Click the Continue button
7. In the Sign on URL box, enter the value you saved from Step 2
8. In the Issuer box, enter the value you saved from Step 2
9. Paste your x509 Certificate into the Signing Certificate box
   • If you downloaded a file, open it in Notepad and copy the contents
   • It must be in PEM format and the signature algorithm must be SHA256
10. Click the Continue button

Step 4 - Configure Domains

If like most customers, you want to enable Single Sign On (SAML) for all your employees then:

• Leave the default option of "All employees (Default)"
• Click the Continue button

We also support enabling Single Sign On (SAML) only for employees with specific email domains, in this case:

• Select the option "Only employees with a matching email domain"
• Enter the domains that you want to use Single Sign On (SAML) - this should match the employees email address (i.e. it should never start with "www")
• Click the Continue button

Step 5 - Confirmation

• Please review the details you have entered
• Click the Add Identity Provider button

Step 6 - Testing

Before you can use your Identity Provider, you must test it.

• Click the [...] button next to your Identity Provider and select "Test"
• Copy the Test URL
• Paste the URL in a Private/Incognito browser window
• Try and login with your test user
• If you see any of the following, the test has SUCCEEDED:
  • You are logged in and can access the system
  • You see a message that says "SAML sign on successful, however we cannot log you in because XYZ" (i.e. if you program has not yet launched or login is disabled)
• If you see any other error messages, the test has FAILED and you should do the following:
  • View the Identify Provider settings you have entered (click the [...] button next to your Identity Provider and select "View Settings") and check they are correct.
  • Login to your Identity Provider and check its configured correctly.
  • Take a look at the Troubleshooting section

When the tested has succeeded, the Identity Provider status will change from "Ready to test" to "Ready" (you may need to refresh the page). 

You cannot complete the next step "Enable Single Sign On" until the test has succeeded.

Step 7 - Enable Single Sign On

When the status is showing as "Ready", you can enable Single Sign On (SAML):

• Click the slider next to the "Single Sign On (SAML)" option
• Review the modal and click the Confirm button

Step 8 - Final Checks

• 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 your Identity Provider's login page and asked to login (if you have configured it for specific domains, you will need to first enter your email address).
  • If you are already logged in to your Identity Provider, you will be redirected back and you will be logged in.

• Depending on your Identify Provider, your employees may be able to login directly from the Identify Provider dashboard/gallery. To test this:
  • Go to your Identify Provider dashboard and click the appropriate app/integration
  • You should be redirected to our site and logged in

Troubleshooting

If you have any issues, see How to troubleshoot Single Sign On (SAML) errors

Frequently Asked Questions

How do I change the settings on my Identity Provider?

To change the settings, you must add a new Identity Provider. You can then enable the new one and disable the old one. This prevents you from accidentally breaking all employee logins.

Do you support multiple Identity Providers?

Yes, you can configure different Identity Providers for different email domains. When the employee logins in they will have to enter their email address, we will then redirect to the appropriate Identity Provider.

Can I use Single Sign On (SAML) with other login options?

Yes, you can use it with Email & Password and/or 3rd Party Cloud.

WARNING - you should only do this if you have a group of employees that are not in your Identity Provider.