Configuring Single Sign-On (SAML 2.0)

What does it do?

This article explains how to configure Single Sign-On (SAML 2.0) for your Betterworks instance. These instructions are general guidelines and may change if your IDP updates its processes; as a best practice, confirm these procedures are accurate by reading your IDP’s documentation as well.

Note: Refer to Single Sign-On (SSO) Overview for more details on why SSO is useful and a summary of the types of SSO. Also, see instructions for setting up Configuring Single Sign-On (Google OAuth 2.0).

IDPs

This article explains general SAML configuration steps and has specific instructions on how to configure SAML SSO for the following IDPs:

• Okta

• PingOne (formerly Ping Federate)

• One Login

• ADFS

• Bitium

• Microsoft Azure

Note: We support both AD and FS. The FS configuration is almost exactly the same as the AD configuration so the MSFT support article can be used as a reference. Also, the Microsoft article states that the values for the Reply URL, Identifier and the Sign-On URL are not real values and to contact Betterworks. These are the real values. Also please see the important note about the Sign-On URL if you wish to configure SP initiated mode. If you wish to enable IDP-initiated, simply skip that step regarding the Sign-On URL.

General Configuration Steps

1. Create a Keybase account, here we will securely share your SAML token

   • Keybase is a free message encryption service that is easy to download and use

2. Contact support@betterworks.com and notify us you'd like to enable SSO via SAML 

3. Import the Betterworks metadata/connection data to your IDP.

   • Download the metadata file

   • Note: If your IDP does not let you upload the metadata file directly, the configuration details you need to set up your IDP should be in the metadata file

4. Configure your IDP to pass the user's primary email address as the SAML subject

5. Configure the IDP to pass the attributes listed in the table below. All attributes are case sensitive
   

   Attribute	Description	Dynamic or Literal
   givenName	User's first name	Dynamic
   sn	User's last name	Dynamic
   mail	User's email address	Dynamic
   saml_token	Unique ID assigned by Betterworks	Literal
   employee_id	(Optional) Employee's organization or user ID	Dynamic

6. Provide Betterworks with the XML file containing your IDP’s SAML metadata

   • Your IDP’s documentation should tell you how to generate the metadata file

7. We'll work with you to coordinate a time to enable and test your SAML-based SSO implementation

Using SAML with Okta

If Okta is your IDP, follow these steps to configure your SAML SSO:

1. Create a Keybase account, here we will securely share your SAML Token

   • Keybase is a free message encryption service that is easy to download and use

2. Contact support@betterworks.com and inform them that you'd like to enable SAML SSO 

3. Log in to Okta as an administrator

4. Click on the Admin button, then click Add application

5. Find the Betterworks Verified app

6. When prompted to provide the saml_token, enter the token provided by Betterworks

7. Click Next and confirm that the "SAML 2.0" radio button is selected

8. Select View Setup Instructions additional configuration details

9. Download the Okta Metadata file by clicking on the Identity Provider Metadata link and send the metadata file to Betterworks

10. Our team will work with you to coordinate a time to enable and test your SAML-based SSO implementation

Using SAML with PingOne 

If PingOne is your IDP, follow these steps to configure your SAML SSO:

1. Create a Keybase account, here we will securely share your SAML token

   • Keybase is a free message encryption service that is easy to download and use

2. Contact support@betterworks.com and inform them that you'd like to enable SAML SSO

3. Log into PingOne as an administrator

4. Go to the Applications tab and click Application Catalog

5. Select the Betterworks App

6. Choose the SAML 2.0 configuration option

7. When prompted, upload the Betterworks metadata file

   • Download the metadata file

8. Make sure that you are sending the email as the SAML_SUBJECT

9. Configure the other attributes as follows:
   

   Attribute	Description	Dynamic or Literal
   givenName	User's first name	Dynamic
   sn	User's last name	Dynamic
   mail	User's email address	Dynamic
   saml_token	Unique ID assigned by Betterworks	Literal
   employee_id	(Optional) Employee's organization or user ID	Dynamic

10. Download the SAML Metadata file and email it to Betterworks

11. Our team will work with you to coordinate a time to enable and test your SAML-based SSO implementation

Using SAML with One Login 

If One Login is your IDP, follow these steps to configure your SAML SSO:

1. Create a Keybase account, here we will securely share your SAML Token

   • Keybase is a free message encryption service that is easy to download and use

2. Contact support@betterworks.com and notify us you'd like to enable SSO via SAML 

3. Log in to OneLogin as an administrator

4. Hover over the Apps tab and click Add Apps

5. Search for the Betterworks App

6. Choose the SAML 2.0 configuration option.

7. In the Configuration tab, enter the saml_token provided by Betterworks

8. Leave the remaining configuration options on their default settings

9. Find the More Actions drop-down and select the SAML Metadata option to download the OneLogin metadata and email the file to Betterworks

10. Our team will work with you to coordinate a time to enable and test your SAML-based SSO implementation

Using SAML with ADFS 

If you are using ADFS you can follow these steps:

1. Create a Keybase account, here we will securely share your SAML Token

   • Keybase is a free message encryption service that is easy to download and use

2. Contact support@betterworks.com and notify us you'd like to enable SSO via SAML 

3. Upload the Betterworks metadata file

   • Download the metadata file

4. In ADFS, create a new Claim Rule for "Email", "Given Name" and "Surname" and configure it according to these guidelines:
   
   
   

5. Create a new Claim Rule for "Email to NameID Transient" and configure it according to these guidelines:
   
   
   

6. Create a new Claim Rule for "saml_token" and configure it according to these guidelines (when prompted to provide the saml_token enter the token provided by Betterworks):
   
   
   

7. Download the ADFS SAML metadata file and email it to BetterWorks

8. Our team will work with you to coordinate a time to enable and test your SAML-based SSO implementation

Using SAML with Microsoft Azure Active Directory

Note: You do not need a SAML token with using Microsoft Azure Active Directory.

1. Follow the steps outlined in Microsoft's article
2. Once complete, send over the metadata XML to Betterworks and ask them to set up the SAML connection on your account
3. Our team will work with you to coordinate a time to enable and test your SAML-based SSO implementation 

Note: If your organization's instance is on our EU datacenter, you'll want to use the following URLs (instead of the URLs referenced in Microsoft's article):

• Identifier - https://eu.betterworks.com/saml2/metadata/
• Reply - http://eu.betterworks.com/saml2/acs
• Sign-On - https://eu.betterworks.com 

Using SAML with Bitium 

Here are the steps to turn on SAML 2.0 for Betterworks in Bitium:

1. Create a Keybase account, here we will securely share your SAML Token.

   • Keybase is a free message encryption service that is easy to download and use

2. Contact support@betterworks.com and notify us you'd like to enable SSO via SAML 

3. In Bitium, go to "Manage Apps"

4. Select Betterworks from the list of installed apps

5. Click the "Single Sign-On" tab

6. Click the drop-down menu and select SAML authentication:

   

7. Copy the Metadata XML from Bitium

8. When prompted to provide the saml_token, enter the token provided by Betterworks:
   

   

9. Click Save Changes

10. Send over the Metadata XML you copied in Step 5 to Betterworks and ask them to set up the SAML connection on your account

11. Our team will work with you to coordinate a time to enable and test your SAML-based SSO implementation

FAQs

Does a user have to sign in with SSO?

Yes. Once SSO is set up, any user with the email domains included in SSO will need to use SSO to sign in. If you have users on a separate email domain not included in your SSO setup, then they can use a password to sign in. You will need to let Betterworks know what the additional domains are before these users can be created.

Can we auto-provision users via SSO?

No, users can be provisioned via HRIS, API or CSV.