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. 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. Click the Continue button
6. In the Name box, enter an appropriate name (e.g. Microsoft EntraID)
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. Leave the default value for What are you sending as the Name ID in the SAML request? Unless you are using an employeeID instead of an email as your NameID.
11. 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 to a new browser tab
• Login to your Identity Provider (if not already logged in)
• Review the SAML Request Test results page
• Many common issues are reported on this page (e.g. incorrect EntityID, Certficates, etc.)
• If the test fails, make the necessary changes.
• If the test passes, close the window.

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

• Log back in to the administrator portal
• Click on System Settings in the top right
• Click the Sign In tab
• The status for your Identity Provider should now be "Ready"
• To enable SSO, 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.app
  • 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. 

If you are only using SSO for some domains, you can edit those domains without creating a new Identity Provider.

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 but you should only do this if you have a group of employees that are not in your Identity Provider.