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

• Okta

• PingOne (formerly Ping Federate)

• One Login

• Microsoft ADFS

• Microsoft Entra ID (formerly Microsoft Azure AD)

• Bitium

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 [e-mail] 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):

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 [e-mail] 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".

• If you are a customer using app.betterworks.com, please follow the below instructions for app customers.
• If you are a customer using eu.betterworks.com, please follow the instructions for EU customers. 

For organizations on the US data center

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. 

For organizations on the EU data center

5. Click "Create App Integration": 

6. Select "SAML 2.0" and click "Next":

7. Enter a name for the new integration (i.e. "Betterworks-eu") and click "Next":

8. Set Single Sign-On URL to https://eu.betterworks.com/saml2/acs/.

9. Set Audience Restriction to https://eu.betterworks.com/saml2/metadata/:

10. Creates Attribute statements:

• givenName - user.firstName
• sn - user.lastName
• email - user.email
• saml_token

11. Click "Next":

12. Select "I’m an Okta customer adding an internal app":

13. Select "Sign On":

14. Save the metadata:

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 [e-mail] 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:

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 [e-mail] 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 [e-mail] 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:

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 the Support Team.

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

Microsoft Entra ID (formerly 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 Entra ID, 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 [e-mail] 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:

• Identifier - https://eu.betterworks.com/saml2/metadata/
• Reply - http://eu.betterworks.com/saml2/acs/
• Sign-On - https://eu.betterworks.com 

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 [e-mail] 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 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:

• Individual Update
• CSV Upload
• HRIS Integration (automated file feed)
• API Integration