SAML setup guide (Office 365/AzureAD)

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 Office 365
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 Office 365

1. Login to Office 365 as an Administrator
2. Click Admin either on the landing page or from the App Launcher menu in the top left
3. At the bottom of the left-nav menu, expand Admin centers and select Azure Active Directory
4. On the left menu click Enterprise applications
5. At the top of the right window click + New application
6. You should see a list of categories, ensure All is selected
7. In the right window Add from the gallery section, type Workstars in the search box and select it
8. In the new window that opens, scroll down and click the Add button
9. In the Workstars - Overview window, under the Manage heading, click the Single sign-on option
10. Select SAML
11. In the first section Basic SAML Configuration, click the edit (pen) icon
12. In the Identifier (Entity ID) box, enter or Entity ID from Step 1
13. In the Reply URL (Assertion Consumer Service URL) box, enter our ACS URL from Step 1
14. Click the Save button at the top and close that window using the X in the corner
15. Leave the default settings in the second section User Attributes & Claims
16. In the third section SAML Signing Certificate, download the Certificate (Base64) to your desktop
17. In the fourth section Set up Workstars, save a copy of the Login URL, Azure AD Identifier and the Logout URL as you will need them in Step 3
18. In the toolbar under the Manage heading, click the Users and groups option
19. Click + Add user
20. Select the appropriate users or groups and press Assign (you can add just the user you want to test with and add everyone else later, or you can add everyone now)

The app should now be available to the users you specified.

Step 3 - Configure sign on to use Office 365

1. Log back into your Workstars Administrator account
2. In the top bar, select System Settings
3. In the left-nav menu, select Sign On
4. Click Setup next to the Single Sign On (SAML) option
5. Select Office 365
6. Scroll down to the Identity Provider Settings section
7. In the SAML SSO URL box, enter the Login URL from Step 2
8. In the Identity Provider Entity ID box, enter the Azure AD Identifier from Step 2
9. Open the Certificate (Base64) that you downloaded in Step 2 with a text editor (e.g. Notepad); It should be in PEM format, which looks like the following:
   

   • -----BEGIN CERTIFICATE-----
       MIIDjDCCAvWgAwIBAgIBATANBgkqhkiG9w0BAQQFADCBgjELMAkGA1UEBhMCREUx
       DDAKBgNVBAgTA05SVzESMBAGA1UEBxMJU3RlaW5mdXJ0MRcwFQYDVQQKEw5TcGVu
       bmViZXJnLmNvbTEUMBIGA1UEAxMLUm9vdENBIDIwMDMxIjAgBgkqhkiG9w0BCQEW
       E3JhbGZAc3Blbm5lYmVyZy5uZXQwHhcNMDMwNDMwMDYwODU2WhcNMDQwNDI5MDYw
       ODU2WjCBgjELMAkGA1UEBhMCREUxDDAKBgNVBAgTA05SVzESMBAGA1UEBxMJU3Rl
       aW5mdXJ0MRcwFQYDVQQKEw5TcGVubmViZXJnLmNvbTEUMBIGA1UEAxMLVlBOLUdh
       dGV3YXkxIjAgBgkqhkiG9w0BCQEWE3JhbGZAc3Blbm5lYmVyZy5uZXQwgZ8wDQYJ
       KoZIhvcNAQEBBQADgY0AMIGJAoGBAMU7nDY6GWyp8rrp0u2EMzZIB7KjLVmSsIZM
       gSzqXO3zuusXTrM6zLdbXcqzBO37WTzFJT7z/7AiEPvecgruQkua0yfTtvvpiBDI
       R7cmT3FA5HXEwO5rh7hvyV5mz7vnrXJouG39j0wfOqINQyUGuZLnIGyGFaDrf/cL
       mpldFIibAgMBAAGjggEOMIIBCjAJBgNVHRMEAjAAMCwGCWCGSAGG+EIBDQQfFh1P
       cGVuU1NMIEdlbmVyYXRlZCBDZXJ0aWZpY2F0ZTAdBgNVHQ4EFgQUy1wZm+aKiv4O
       xP1e3/e/PagYfAgwga8GA1UdIwSBpzCBpIAUAbvGM771ml6wDF29Qel4bFStZo6h
       gYikgYUwgYIxCzAJBgNVBAYTAkRFMQwwCgYDVQQIEwNOUlcxEjAQBgNVBAcTCVN0
       ZWluZnVydDEXMBUGA1UEChMOU3Blbm5lYmVyZy5jb20xFDASBgNVBAMTC1Jvb3RD
       QSAyMDAzMSIwIAYJKoZIhvcNAQkBFhNyYWxmQHNwZW5uZWJlcmcubmV0ggEAMA0G
       CSqGSIb3DQEBBAUAA4GBAG+JK5Wv8Y1Nt9/obfeS+0iMxBpDaGWXAYemhLWhOL1i
       dHDbnngZ2QyvGK0Td1Z9Pxlh2rp0MI7FUA7j6/+VzY3WfsMOq1s0lLwWD+/c3kC7
       fbqiuF35dOcoWHWgZtKNhbo4gggQM+++KckxnWOp9+CZ6qfttrUzGxxKpAVAbkB7
       -----END CERTIFICATE-----

10. Copy and paste the file contents into the x509 Certificate box
11. Enter an appropriate URL in the Remote Logout URL box
    • If you want the user to logout of Office 365 when they logout of Workstars, enter the Logout URL from Step 2
    • If you want the user to just logout of Workstars, enter https://login.microsoftonline.com to return them to the Office 365 landing page
12. Leave the NameID as the default Email (We also support EmployeeID, but configuring Office 365 is outside the scope of this document, please contact Office 365 support)
13. 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 Office 365 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 Office 365 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 Office 365 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 Office 365 portal
  • To test this, open the App Launcher menu and click the app (you may need to find it in the All tab)
  • You should be redirected to our site and logged in

Troubleshooting

The Microsoft Sign in says “Sorry, but we’re having trouble signing you in”

If the reason says something like “The signed in user ‘xxx@yyy.zzz’ is not assigned to a role for the application ‘abfe9cf8-907c-4077-ba5a-552a85ed279b’(Workstars).”, this is usually because you have not assigned all your employees to the app in the AzureAD administration portal.

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.