BetterWorks

Configuring SAML single sign-on

This article explains how to configure SAML SSO 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. 

Need to get started with SSO? Read the BetterWorks single sign-on overview.

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

General configuration steps

  1. Contact your Customer Success Manager and tell them you want to enable SAML SSO. They’ll create a saml_token and give it to you to use when you configure the SSO.
  2. Import the BetterWorks metadata / connection data to your IDP. Download the metadata file here.
    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.
  3. Configure your IDP to pass the user’s primary email address as the SAML subject.
  4. 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

  5. Provide your BetterWorks Customer Success Manager with the xml file containing your IDP’s SAML metadata. Your IDP’s documentation should tell you how to generate the metadata file.
  6. Your Customer Success Manager will 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. Contact your Customer Success Manager and tell them you want to enable SAML SSO. They’ll create a saml_token and give it to you to use when you configure the SSO.
  2. Log in to Okta as an administrator.
  3. Click on the Admin button, then click Add application.
  4. Find the BetterWorks Verified app.
  5. When prompted to provide the saml_token enter the token provided by your Customer Success Manager.
  6. Click Next and confirm that the “SAML 2.0” radio button is selected.
  7. Select View Setup Instructions additional configuration details.
  8. Download the Okta Metadata file by clicking on the Identity Provider Metadata link.
  9. Send the metadata file to BetterWorks by emailing it to your Customer Success Manager or BetterWorks Support.
  10. Your Customer Success Manager 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. Contact your Customer Success Manager and tell them you want to enable SAML SSO. They’ll create a saml_token and give it to you to use when you configure the SSO.
  2. Log into PingOne as an administrator.
  3. Go to the Applications tab and click Application Catalog.
  4. Select the BetterWorks App.
  5. Choose the SAML 2.0 configuration option.
  6. When prompted, upload the BetterWorks metadata file. Download the metadata file here.
  7. Make sure that you are 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     (Optional) Employee's organization or user ID   Dynamic
  9. Download the SAML Metadata file and email it to your BetterWorks Customer Success Manager.
  10. Your Customer Success Manager will work with you to coordinate a time to enable and test your SAML based SSO implementation. 

Using SAML with One Login

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

  1. Contact your Customer Success Manager and tell them you want to enable SAML SSO. They’ll create a saml_token and give it to you to use when you configure the SSO.
  2. Log in to OneLogin as an administrator.
  3. Hover over the Apps tab and click Add Apps.
  4. Search for the BetterWorks App.
  5. Choose the SAML 2.0 configuration option.
  6. In the Configuration tab, enter the saml_token provided by your BetterWorks Customer Success Manager.
  7. Leave the remaining configuration options on their default settings.
  8. Find the More Actions drop down and select the SAML Metadata option to download the OneLogin metadata.
  9. Email the metadata file to your Customer Success Manager.
  10. Your Customer Success Manager 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 to send the correct attributes:

  1. Contact your Customer Success Manager and tell them you want to enable SAML SSO. They’ll create a saml_token and give it to you to use when you configure the SSO.
  2. Upload the BetterWorks metadata file. Download the metadata file here.
  3. In ADFS, create a new Claim Rule for “Email, Given Name, and Surname” and configure it according to these guidelines:
    SAML configuration screen
  4. Create a new Claim Rule for “Email to NameID Transient” and configure it according to these guidelines:
    SAML configuration screen
  5. Create a new Claim Rule for “saml_token” and configure it according to these guidelines:
    SAML configuration screen
  6. Download the ADFS SAML metadata file and email it to your BetterWorks Customer Success Manager.
  7. Your Customer Success Manager will work with you to coordinate a time to enable and test your SAML based SSO implementation.

Using SAML with Bitium

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

  1. Contact your Customer Success Manager and tell them you want to enable SAML SSO. They’ll create a saml_token and give it to you to use when you configure the SSO.
  2. In Bitium, go to “Manage Apps."
  3. Select BetterWorks from the list of installed apps.
  4. Click the “Single Sign-On” tab.
  5. Click the dropdown menu and select SAML authentication.
  6. Copy the Metadata XML from Bitium.
  7. Obtain your organization-specific saml_token from your Customer Success Manager at BetterWorks. Paste this into the SAML Token field in Bitium.
  8. Click Save Changes.
  9. Send over the Metadata XML you copied in Step 5 to your Customer Success Manager and ask them to setup the SAML connection on your account. JIT provisioning is also available upon request.
  10. Your Customer Success Manager will work with you to coordinate a time to enable and test your SAML based SSO implementation.
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments