Configuring SAML SSO

Avatar
by Fred Pukay
Follow

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:

  • Okta
  • PingOne (Ping Federate)
  • One Login
  • ADFS
  • Bitium
  • Microsoft Azure (Links out to MSFT support article)
  • 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.

Scheduling enablement of SAML SSO

  • If possible, please give us at least 1 week's notice for scheduling by emailing support@betterworks.com.  We will be happy to coordinate a time during our normal business hours (M-F) when we can help you.
  • Please see the specific steps for your configuration and the note about sending us metadata below.

Sending us metadata

  • Please do not send us the metadata in the same support ticket that the SAML token is listed in.  Please instead send a separate email to support@betterworks.com with the metadata.

General configuration steps

  1. Contact either support@betterworks.com or your Engagement 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 betterworks with the xml file containing your IDP’s SAML metadata. Your IDP’s documentation should tell you how to generate the metadata file.
  6. 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. Contact either support@betterworks.com or your Engagement 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 betterworks.
  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 and send the metadata file to betterworks 
  9. 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. Contact either support@betterworks.com or your Engagement 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 betterworks.
  10. 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. Contact either support@betterworks.com or your Engagement Manager and tell them you want to enable SAML 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 betterworks.
  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 and email the file to betterworks.
  9. 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 to send the correct attributes:

  1. Contact either support@betterworks.com or your Engagement Manager and tell them you want to enable SAML 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 betterworks
  7. 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. Contact either support@betterworks.com or your Engagement Manager and tell them you want to enable SAML 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 either support@betterworks.com or your Engagement 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 betterworks and ask them to setup the SAML connection on your account. JIT provisioning is also available upon request.
  10. Our team will work with you to coordinate a time to enable and test your SAML based SSO implementation. 

Comments

0 comments
Article is closed for comments.