SAML setup guide (ADFS)

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 Active Directory Federation Services
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 ADFS

1. Open the ADFS management console
2. Expand the Trust Relationships section and click Relying Party Trusts
3. On the right side select the Add Relying Party Trust action
4. You should see the Add Relying Party Trust Wizard open
5. In the Select Data Source step, choose Enter data about the relying party manually, then click Next
6. In the Specify Display Name step, enter the name of your program in the Display Name box (this is what your users will see so it should be something they will recognise), then click Next
7. In the Choose Profile step, select AD FS profile, then click Next
8. In the Configure Certificate step, click Next
9. In the Configure URL step, tick the Enable support for the SAML 2.0 WebSSO protocol and paste our ACS URL from step 1 into the Relying party SAML 2.0 SSO service URL box, then click  Next
10. In the Configure Identifiers step, enter our Entity ID from step 1 into the Relying party trust identifier box, then click Add
11. Click Next to continue
12. In the Choose Issuance Authorization Rules step, select Permit all users to access this relying party, then click Next
13. In the Ready to Add Trust step, scroll to the Advanced tab and in the Secure hash algorithm drop-down select SHA-256, then click Next
14. In the Finish step, tick Open the Edit Claim Rules dialog for this relying party trust when the wizard closes, then click Next
15. You should see the Edit Claim Rules screen open
16. Click the Add Rule button
17. You should see the Add Transform Claim Rule Wizard open
18. In the Choose Rule Type step, select Send LDAP Attributes as Claims in the Claim rule template drop-down menu, then click Next
19. In the Configure Claim Rule step, type 'Email' in the Claim rule name box
20. In the Attribute store drop-down menu, select Active Directory
21. In the Mapping of LDAP attributes to outgoing claim types section, select E-Mail-Addresses as the LDAP Attribute and Name ID as the Outgoing Claim Type
22. Click Finish

You now need to gather some additional information from your ADFS server:

1. Open the FederationMetadata.xml file from your ADFS server (it is usually located at https://<your-domain>/FederationMetadata/2007-06/FederationMetadata.xml)
2. At the top of the file in the EntityDescriptor tag, find the value of entityID and save a copy (it should be in the format http://<your-domain>/adfs/services/trust), as you will need this in Step 3
3. Towards the bottom of the file, in the SingleSignOnService tag, find the value of Location and save a copy (it should be in the format https://<your-domain>/adfs/ls), as you will need this in Step 3
4. Go back to the ADFS Management Console
5. Expand the Service section and click Certificates
6. Open the certificate under Token-signing
7. In the Details tab, select Copy to File
8. In the wizard, select the Base-64 encoded X.509 option and Save it

Step 3 - Configure sign on to use ADFS

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 Active Directory Federation Services
6. In the SAML SSO URL box, enter the SingleSignOnService > Location value you copied in Step 2
7. In the Identity Provider Entity ID box, enter the EntityDescriptor > entityID value you copied in Step 2
8. Open the x509 Certificate 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-----

9. Copy and paste the file contents into the x509 Certificate box
10. Enter an appropriate URL in the Remote Logout URL box
    • This can be your intranet or other internal dashboard
    • Do not use our login URL as that will log the user back in
    • If you want the user to be logged out of ADFS when they log out of our system, enter your Single Sign Out URL (it is in the format https://<your-domain>/adfs/ls/?wa=wsignout1.0)
11. Leave the NameID as the default Email (We also support EmployeeID, but configuring ADFS is outside the scope of this document, please contact ADFS support)
12. 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 ADFS 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 ADFS 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 ADFS login page and asked to login
  • If you are already logged in, you should be redirected back and logged into our system

Troubleshooting

The SSO process involves the following 3 steps:

1. Initial request to our application (i.e. users visits our login URL)
2. Redirect to your ADFS for authentication
3. User sent back to our application with SAML token

The key is to identify where the transaction has broken down:

1. On our application side on step 1?
2. When redirected over to your ADFS on step 2?
3. Or when being sent back to our application with a token during step 3?

1. Initial request to our application

Check you are using the correct URL. If SAML is enabled you should use your program URL (e.g. https://<your-sub-domain>.workstars.com), if you are testing then you should be using the test URL shown on the SAML setup page (e.g. https://<your-sub-domain>.workstars.com/login/saml). If you see any errors please report them to support. Please ensure they are errors generated by our system, if the URL isn’t your program URL then the error is not in our application.

2. Redirect to your ADFS for authentication

At this stage our system should redirect the user to your ADFS for authentication. You should see the URL bar change to the URL entered in setup. If this doesn’t work there are a few possible reasons:

The SAML SSO URL you entered is incorrect

Login to our administration portal and in the SAML settings check you have entered the correct SingleSignOnService > Location (from your metadata xml file) in the SAML SSO URL field. It should be in the format https://<your-domain>/adfs/ls (note that there is not a trailing / at the end). You should check you can reach this URL by entering it in your browser.

The entity ID is not recognised

Login to the ADFS management console, open our relying party trust, go to the Identifiers tab and check that the Relying party identifier is https://workstars.com

Other

Check the ADFS log for more details about the specific error (open Event Viewer, expand Application and Services Log, expand ADFS and select Admin).

3. Error when the user is sent back to our application

At this stage your ADFS server will create an authorisation request and the users browser should POST it to our login URL.

Please Note - If you receive a message saying something like “Unable to find user please contact HR” then this is not an error. To login you must be using an account in ADFS that has the same email as an account in our application.

If you receive an error there are a few possible reasons:

Incorrect Identity Provider Entity ID

Login to our administration portal and in the SAML settings check you have entered the correct EntityDescriptor > entityID in the Identity Provider Entity ID field. It should be in the format http://<your-domain>/adfs/services/trust (note that there is not a trailing / at the end).

Incorrect certificate

Login to our administration portal and in the SAML settings check that you have entered the correct certificate. It should be the Token-signing one and obviously check that it has not expired.

Incorrect Signing Algorithm

The signing algorithm must be SHA-256. Login to your ADFS management console, go to Relying Party Trusts and open the one for our application. Go to the Advanced tab and ensure the Secure hash algorithm drop-down is set to SHA-256.

Incorrect NameID

By default the NameID should be an email address, please check this has been setup as a claim rule. If you are using a different NameID that we support please contact support for further assistance.

Other

Please install and setup Fiddler to intercept the post request. Once you have a copy of the SAML token you can use an online tool (https://www.samltool.com/online_tools.php) to decode and extract the content. You can then check your token is using the settings correctly (e.g. cert, algorithm, entityID, NameID, etc.)