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

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

Create a Keybase account. 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.

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

2. Upload the Betterworks metadata file. 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.

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 (attributes are case-sensitive):

general_config.png

5. Download the XML file and provide it to the Support Team. Your IDP’s documentation should tell you how to generate the metadata file.

Okta

If you are using Okta, please:

1. Create a Keybase account. 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 verified Betterworks 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 you are using PingOne, please:

1. Create a Keybase account. 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. Ensure that you're sending the email as the SAML_SUBJECT.

8. Configure the other attributes as follows:

pingone_config.png

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

One Login 

If you are using OneLogin, please:

1. Create a Keybase account. 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, please:

1. Create a Keybase account. 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. 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: Although the Microsoft article states that the values for the Reply URL, Identifier, and Sign-On URL are not real values, they are. However, if your organization's instance is on the EU data center, you'll want to use the URLs referenced below. 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.

If you are using Microsoft Azure AD, please:

1. Create a Keybase account. 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. Follow the steps outlined in this Microsoft article.

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

URLs for EU data center:

Bitium 

If you are using Bitium, please:

1. Create a Keybase account. 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:

bitium1.png

7. Copy the metadata from Bitium.

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

bitium2.png

9. Click "Save Changes". 

10. Provide the metadata to the Support Team. 

FAQs

Does a user have to log in with SSO?

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

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

Users can be provisioned via: