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.
- Initial configuration in PingID
- Directory configuration and activation in Turbot
- Finalizing configuration in PingID
Phase 1: Create the SAML App in PingID
In the PingID Admin console create a new application for Turbot.
Use the below Turbot JPG as the icon for the Turbot application.
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 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 |
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
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.
Phase 2: Configure Directory in Turbot
- Log into Turbot.
Turbot/Owner
permissions are required at the Turbot resource level. - Click the Permissions tab (designated with a king icon) in the top navigation bar.
- Select the blue Directories button at the top.
- Select New Directory then click the SAML option. The Create SAML Directory window will pop up.
-
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 likehttps://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
- Name ID Format can generally be left as
unspecified
. - 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.
-
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. - Click the Create button.
- On the Directories list page, click the pencil icon next to the new PingID directory.
- 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
- Activate the directory by clicking on the upward point arrow icon next to the new directory.
- 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.
- Resolve any error messages that may pop up from PingID or Turbot. Problems with ACS URLs and Callback URLs usually pop up here.
- Test logins from the PingID application list.
- Test logins directly from the Turbot console login screen.
- After successful login, go to the user profile link in the top right corner. Click the
Developers
tab next toOverview
. In theTerraform
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. - If there are any residual user profiles with incorrect information, delete them before finishing.
- 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.