Turbot DocsGetting StartedConceptsGuidesChange WindowConsoleDirectoriesAWS SSOAzure ADGoogleOktaOneLoginLDAP and LDAPSLocalPingIDFilesFirehoseGraphQLIAMImporting AccountsManaging PoliciesNetwork StacksNunjucksQuick ActionsRegionsSearching & FilteringWorking with FoldersIntegrationsMods7-minute LabsFAQsReferenceRelease NotesTurbot.comEnterprise

Configuring PingID and Turbot

This guide details configuring a Turbot application in PingID as well as the directory in Turbot. Administrator access in PingID and Turbot/Owner permissions in Turbot are required for configuration.

Configuring PingID for Turbot is a three-phase process.

  1. Initial configuration in PingID
  2. Directory configuration and activation in Turbot
  3. Finalizing configuration in PingID

Phase 1: Create the SAML App in PingID

In the PingID Admin console create a new application for Turbot.

New PingID Application

Use the below Turbot JPG as the icon for the Turbot application.

turbot

Initial Identity Provider Settings

  • Application Name: Turbot (For customers with multiple environments: TurbotProd/TurbotDev
  • Application Description: SAML integration with Turbot
  • Application Type: SAML Application
  • Protocol Version: SAML v 2.0

SAML Attributes

Required Attributes

Required attributes are case-sensitive.

Attribute Name Source Source Attribute Example
saml_subject Email Address jdoe@company.com
email Email Address jdoe@company.com
nameID Email Address OR sAMAccountName OR UPN jdoe
displayName Formatted John Doe
firstName Given Name John
lastName Family name Doe

PingID will fill in saml_subject for you.

Optional Attributes

Attribute Name Source Example
sAMAccountName sAMAccountName jdoe@company.com
login Email Address jdoe@company.com

Completed Attributes

Download the SAML Metadata File.

Edit SAML Configuration

Set the following parameters:

  • Assertion Consumer Service (ACS): Use https://workspace.turbot.your-company.com/ as a placeholder. This will be updated after the SAML directory has been created and activated in Turbot.
  • Entity ID: A common convention is to use the workspace URL (https://{{workspace-id}}.turbot.company.com), but any unique value should work.
  • Signing Algorithm: RSA_SHA256
  • Force Re-authentication: As required. If True, users will always be forced to re-authenticate in when logging into Turbot, regardless of any active existing SSO session

ACS URL

Get Certificate

Download the X509 PEM (.crt) certificate. The file will start with -----BEGIN CERTIFICATE----- on the first line. This will be required when configuring the directory in Turbot.

certificate-download

Phase 2: Configure Directory in Turbot

  1. Log into Turbot. Turbot/Owner permissions are required at the Turbot resource level.
  2. Click the Permissions tab (designated with a king icon) in the top navigation bar.

permissions-nav

  1. Select the blue Directories button at the top.

directories

  1. Select New Directory then click the SAML option. The Create SAML Directory window will pop up.

new_directory

  1. In the new directory dialog box, enter the following information:

    • Title: Title for the SAML directory. This will display at the login screen. A common title is "{Organization} SSO"
    • Description: A description for the directory.
    • Entry Point: The URL that Turbot redirects the user to authenticate. This is the Single Signon Service URL shown in the PingID SAML configuration. It will have a format similar to https://auth.pingon.com/{hash}/saml20/idp/sso.
    • Issuer: The base Turbot URL, i.e. https://cloud.turbot.company.com for enterprise installations. For SaaS, it will look something like https://turbot-orgid.cloud.turbot.com.
    • Certificate: Retrieve the Base64 certificate from the PingID SAML Configuration page, then paste the entire contents into this field.
    • Profile ID Template: pingid.{{profile.email}} is a common template as this prevents profile name collisions with Turbot Local directories. A template to generate the ID of the Turbot profile for users authenticated through this directory. The ID MUST be unique for each profile in Turbot, but it is possible to have multiple directories map users to the same ID. This CANNOT be changed unless the directory is new. Changing the
  2. Name ID Format can generally be left as unspecified.
  3. The Signature section can be used to sign requests with a private key and signature algorithm. Usually used only as an organizational requirement. This is an uncommon requirement.

  4. The Advanced section allows organizations to allow IdP-Initiated SSO.

    Warning! There are security risks associated with allowing IdP-initiated SSO as the InResponseTo field cannot be used to identify SP-solicited SAML assertions. Please be fully aware of the security impact that not validating the InReponseTo field can have before making this change.
  5. Click the Create button.
  6. On the Directories list page, click the pencil icon next to the new PingID directory.
  7. Scroll all the way to the bottom for a field called "Callback URL". It will be in the form of https://{turbot_console_url}/api/latest/directories/{directoryID}/saml/callback. The {directoryId} will be a 15-digit number. This will be needed when updating the Turbot application in PingID.

The SAML Directory has been created but is not yet active.

Phase 3: Update the ACS URL in PingID

Replace the default Assertion Consumer Service (ACS) URL in the PingID SAML Configuration settings with the callback URL defined in the new directory. This can be found by clicking on the pencil icon next to the new directory in Turbot. The Reply URL will look like https://{turbot_console_url}/api/latest/directories/{directoryID}/saml/callback.

Note: If for some reason the PingID SAML directory is deleted from Turbot, the ACS URL will need to be changed. Each directory in Turbot gets a unique ID. Altering the profile template is the most common reason for deleting an old directory then creating a new one.

Test the Configuration

  1. Activate the directory by clicking on the upward point arrow icon next to the new directory.
  2. Open a private browser session. Navigate to the Turbot URL and select the new directory listed in the drop-down menu. If the directory is not showing, check to see that the directory was successfully activated.
  3. Resolve any error messages that may pop up from PingID or Turbot. Problems with ACS URLs and Callback URLs usually pop up here.
  4. Test logins from the PingID application list.
  5. Test logins directly from the Turbot console login screen.
  6. After successful login, go to the user profile link in the top right corner. Click the Developers tab next to Overview. In the Terraform sidebar, all the profile data for this user will be displayed. If those fields are empty or contain incorrect/improper values then adjust the SAML Claims until fixed. Log out then log in again after each SAML claims adjustment. Getting the letter-casing wrong on SAML attributes is a common cause of empty attributes.
  7. If there are any residual user profiles with incorrect information, delete them before finishing.
  8. Congratulations! PingID SAML is now configured and can be used to authenticate users into Turbot. Grant user permissions as appropriate.

Be aware that deleting a user profile out of Turbot while the user is logged in can do weird things with browser sessions. Log out then delete the profile if at all possible.

As with other directory types within Turbot, an initial login will need to happen in order for the profile to be created, and then permissions can be assigned to the profile. Refer to our Permissions documentation on how to grant permissions to new users.