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
-
PingOne (aka Ping Federate)
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
-
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.
-
-
Contact support@betterworks.com and notify the Support Team that you'd like to enable SSO.
-
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.
-
-
Configure your IdP to pass the user's primary email address as the SAML subject.
-
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
-
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:
- 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.
- Contact support@betterworks.com and notify the Support Team that you'd like to enable SSO.
- Log into Okta as an administrator.
- Click "Admin", then "Add application".
- Find the Betterworks Verified app
- When prompted to provide the SAML token, enter the token provided by the Support Team.
- Click "Next" and select the "SAML 2.0" option.
- Select "View Setup Instructions" for additional configuration details.
- 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:
- 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.
- Contact support@betterworks.com and notify the Support Team that you'd like to enable SSO.
-
Log into PingOne as an administrator.
-
Go to the "Applications" tab and click "Application Catalog".
-
Select the Betterworks App.
-
Select the SAML 2.0 configuration option.
-
Upload the Betterworks metadata file.
- Note: Ensure that you're sending the email as the SAML_SUBJECT.
-
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
-
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:
- 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.
- Contact support@betterworks.com and notify the Support Team that you'd like to enable SSO.
-
Log in to OneLogin as an administrator.
-
Hover over the "Apps" tab and click "Add Apps".
-
Search for the Betterworks App.
-
Select the SAML 2.0 configuration option.
-
In the "Configuration" tab, enter the SAML token provided by the Support Team.
-
Leave the remaining configuration options on their default settings.
-
Locate the "More Actions" drop-down and select the "SAML Metadata" option.
- Download the XML file and provide it to the Support Team.
Microsoft ADFS
If you are using Microsoft ADFS you can follow these steps:
- 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.
- Contact support@betterworks.com and notify the Support Team that you'd like to enable SSO.
-
Upload the Betterworks metadata file.
-
Create a new claim rule for "Email", "Given Name" and "Surname" and configure it according to these guidelines:
-
Create a new claim rule for "Email to NameID Transient" and configure it according to these guidelines:
-
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.
-
- 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.
- Follow the steps outlined in the Microsoft article.
- 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):
- Identifier - https://eu.betterworks.com/saml2/metadata/
- Reply - http://eu.betterworks.com/saml2/acs
- Sign-On - https://eu.betterworks.com
Bitium
Here are the steps to turn on SAML 2.0 for Betterworks in Bitium:
- 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.
- Contact support@betterworks.com and notify the Support Team that you'd like to enable SSO.
-
In Bitium, go to "Manage Apps".
-
Select "Betterworks" from the list of installed apps.
-
Click the "Single Sign-On" tab.
-
Select the SAML authentication option from the drop-down menu:
-
Copy the metadata from Bitium.
-
When prompted to provide the SAML token, enter the token provided by the Support Team:
-
Click "Save Changes".
-
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: