SAML Setup Guide (ADFS)

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

• Login to your Workstars Administrator account (must be the primary account or technical user)
• Click on System Settings at the top
• Then click Sign On from the left-hand menu
• Click the Setup button next to the Single Sign On (SAML) option
• Select Active Directory Federation Services
• 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

• Open the ADFS management console
• Expand the Trust Relationships section and click Relying Party Trusts
• On the right hand side select the Add Relying Party Trust action
• You should see the Add Relying Party Trust Wizard open
• In the Select Data Source step, choose Enter data about the relying party manually and click Next to continue
• 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) and click Next to continue
• In the Choose Profile step, select AD FS profile and click Next to continue
• In the Configure Certificate step, click Next to continue
• 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. Click Next to continue
• In the Configure Identifiers step, enter our Entity ID from step 1 into the Relying party trust identifier box and click Add. Click Next to continue
• In the Choose Issuance Authorization Rules step, select Permit all users to access this relying party and click Next to continue
• In the Ready to Add Trust step, scroll to the Advanced tab and in the Secure hash algorithm drop down select SHA-256. Click Next to continue
• In the Finish step, tick Open the Edit Claim Rules dialog for this relying party trust when the wizard closes and click Next to continue
• You should see the Edit Claim Rules screen open
• Click the Add Rule button
• You should see the Add Transform Claim Rule Wizard open
• In the Choose Rule Type step, select Send LDAP Attributes as Claims in the Claim rule template drop down menu and click Next to continue
• In the Configure Claim Rule step, type “Email” in the Claim rule name box. In the Attribute store drop down menu select Active Directory. 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
• Click Finish

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

• Open the FederationMetadata.xml file from your ADFS server (it is usually located at https://<your-domain>/FederationMetadata/2007-06/FederationMetadata.xml)
• 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)
• 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)
• Go back to the ADFS Management Console
• Expand the Service section and click Certificates
• Open the certificate under Token-signing
• In the Details tab, select Copy to File
• In the wizard select the Base-64 encoded X.509 option and save it

Step 3 - Configure Sign On to use ADFS

• Log back into your Workstars Administrator account:
• In the top bar select System Settings
• On the left hand navigation select Sign On
• Click Setup next to the Single Sign On (SAML) option
• Select Active Directory Federation Services
• In the SAML SSO URL box enter the SingleSignOnService > Location value you copied in Step 2
• In the Identity Provider Entity ID box enter the EntityDescriptor > entityID value you copied in Step 2
• Open the x509 Certificate 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-----

• Copy and paste the file contents into the x509 Certificate box
• 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)
• Leave the NameID as the default Email. We also support EmployeeID but configuring ADFS claims to use these is outside the scope of this document, please contact support.
• 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:

• On the Sign On page, click the Enable button next to Single Sign On (SAML)
• Copy the test link
• Open a Incognito/InPrivate browser tab and paste in the link
• You should be redirected to the ADFS login page
• If you login, you should be redirected back to our system and automatically logged in

• If the test worked, go back to the other browser window and click the Enable button
• 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, to check the login is working:

• Visit your 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 - On our application side on step 1? When redirected over to your ADFS on step 2? 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.)