1. Betterworks
  2. How-to
  3. Integrations

Configuring SSO (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 (Identity Provider) updates its processes. As a best practice, confirm these procedures are accurate by reading your IdP’s documentation as well.

Note: Refer to this article for more details on why SSO is useful and a summary of the types of SSO. Also, you'll find information on configuring SSO with Google in this article.

IdPs

Notes:

  • We support both AD and FS. The FS configuration is almost the same as the AD configuration so the Microsoft support article can be used as a reference. Although the Microsoft article states that the values for the Reply URL, Identifier, and Sign-On URL are not real values, they are. Also, be sure to review the important note about the Sign-On URL if you wish to configure SP-initiated mode. If you'd prefer to enable IdP-initiated mode, simply skip that step.
  • At this time, the Betterworks SSO integration does not support SCIM or JIT provisioning. Before a member of your organization can access the Betterworks application, they need to be added as a user.

General Configuration Steps

  1. Create a Keybase account.

    • Note: Keybase is a chat encryption application that is free and easy to download. The application will be needed to receive your organization's SAML token.

  2. Contact support@betterworks.com and notify the Support Team that you'd like to enable SSO. 

  3. Upload the Betterworks metadata file.

    • Note: If your IdP does not allow to 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 (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  

      Employee's organization or user ID (Optional)

    Dynamic

  6. Download the XML file and provide it to the Support Team.

    • Note: Your IdP’s documentation should tell you how to generate the metadata file.

Okta

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

  1. Create a Keybase account.
    • Note: Keybase is a chat encryption application that is free and easy to download. The application will be needed to receive your organization's SAML token.
  2. Contact support@betterworks.com and notify the Support Team that you'd like to enable SSO. 
  3. Log into Okta as an administrator.
  4. Click "Admin", then "Add application".
  5. Find the Betterworks Verified app
  6. When prompted to provide the SAML token, enter the token provided by the Support Team.
  7. Click "Next" and select the "SAML 2.0" option. 
  8. Select "View Setup Instructions" for additional configuration details.
  9. Download the Okta metadata file by clicking on the "Identity Provider Metadata" link and provide it to the Support Team. 

PingOne (aka Ping Federate)

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

  1. Create a Keybase account.
    • Note: Keybase is a chat encryption application that is free and easy to download. The application will be needed to receive your organization's SAML token.
  2. Contact support@betterworks.com and notify the Support Team that you'd like to enable SSO. 

  3. Log into PingOne as an administrator.

  4. Go to the "Applications" tab and click "Application Catalog".

  5. Select the Betterworks App. 

  6. Select the SAML 2.0 configuration option.

  7. Upload the Betterworks metadata file.

    • Note: Ensure that you're sending the email as the SAML_SUBJECT.

  8. 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  

      Employee's organization or user ID (Optional)

    Dynamic

  9. Download the XML file and provide it to the Support Team.

One Login 

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

  1. Create a Keybase account.
    • Note: Keybase is a chat encryption application that is free and easy to download. The application will be needed to receive your organization's SAML token.
  2. Contact support@betterworks.com and notify the Support Team that you'd like to enable SSO. 

  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. Select the SAML 2.0 configuration option.

  7. In the "Configuration" tab, enter the SAML token provided by the Support Team.

  8. Leave the remaining configuration options on their default settings.

  9. Locate the "More Actions" drop-down and select the "SAML Metadata" option.

  10. Download the XML file and provide it to the Support Team.

Microsoft ADFS 

If you are using Microsoft ADFS you can follow these steps:

  1. Create a Keybase account.
    • Note: Keybase is a chat encryption application that is free and easy to download. The application will be needed to receive your organization's SAML token.
  2. Contact support@betterworks.com and notify the Support Team that you'd like to enable SSO. 

  3. Upload the Betterworks metadata file.

  4. 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:

    • Note: When prompted to provide the SAML token, enter the token provided by the Support Team.

      SAML configuration screen

  7. Download the XML file and provide it to the Support Team.

Microsoft Azure AD

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

  1. Follow the steps outlined in the Microsoft article.
  2. Download the XML file and provide it to the Support Team.

Note: If your organization's instance is on our EU data center, you'll want to use the following URLs (as opposed to the URLs referenced in Microsoft's article):

Bitium 

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

  1. Create a Keybase account.
    • Note: Keybase is a chat encryption application that is free and easy to download. The application will be needed to receive your organization's SAML token.
  2. Contact support@betterworks.com and notify the Support Team that you'd like to enable SSO. 

  3. In Bitium, go to "Manage Apps".

  4. Select "Betterworks" from the list of installed apps.

  5. Click the "Single Sign-On" tab.

  6. Select the SAML authentication option from the drop-down menu:

  7. Copy the metadata from Bitium.

  8. When prompted to provide the SAML token, enter the token provided by the Support Team:

  9. Click "Save Changes". 

  10. Provide the metadata (from Step 7) to the Support Team. 

FAQs

Does a user have to sign in with SSO?

Yes. Once the SSO integration is set up, all users with the email domains included in the integration will need to sign in with their IdP credentials. If you have users on a separate email domain, they can still use a password to sign in.

Given that SCIM and JIT provisioning are not supported by the Betterworks application, how can we provision users?

Users can be provisioned via: