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:

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

  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

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

    SAML configuration screen

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

    SAML configuration screen

  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):

    SAML configuration screen

  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):

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.