Configuring Single Sign-On

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: Please refer to Single Sign-On Overview for more details on why SSO is useful and a summary of the types of SSO. Also, see instructions for setting up Google Apps SSO.

IDPs

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

• Okta
• PingOne (Ping Federate)
• One Login
• ADFS
• Bitium
• Microsoft Azure 
  
  Note for Microsoft Azure: 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 says 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 and 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, please 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 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 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.
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 use.
2. Contact support@betterworks.com and tell them you want 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 use.
2. Contact support@betterworks.com, your CSM, or your Program Architect and tell them you want 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 here.
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 use.
2. Contact support@betterworks.com, your CSM, or your Program Architect and tell them you want to enable SAML 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. 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 use.
2. Contact support@betterworks.com, your CSM, or your Program Architect and tell them you want to enable SAML SSO.
3. Upload the betterworks metadata file. Download the metadata file here.
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 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 use.
2. Contact support@betterworks.com, your CSM, or your Program Architect and tell them you want to enable SAML 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. 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. JIT provisioning is also available upon request.
11. Our team will work with you to coordinate a time to enable and test your SAML based SSO implementation.

FAQs