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

Configuring Azure AD and Turbot

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

If SAML group syncing is desired, check out our Azure AD Group Sync guide after the SAML application has been verified to allow authentication.

Configuring Azure AD for Turbot is a three-phase process.

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

Phase 1: Create the SAML App in Azure

  1. Sign in to the Azure Active Directory portal using your Microsoft identity platform administrator account.
  2. Select Enterprise Applications > New application.
  3. Select Create your own application. The Create your own application page appears.
  4. Type Turbot as the display name for your new application.
  5. Under What are you looking to do with your application? choose Integrate any other application you don't find in the gallery. This option is typically used for SAML and WS-Fed applications.
  6. Select Create. The application Overview page opens.

Configure User Sign-In Properties

  1. Select Properties to open the Properties pane for editing.

  2. Set the following options to determine how users who are assigned or unassigned to the application can sign into the application and if a user can see the application in the access panel.

    • Enabled for users to sign-in determines whether users assigned to the application can sign in.
    • User assignment required determines whether users who aren't assigned to the application can sign in.
    • Visible to user determines whether users assigned to an app can see it in the access panel and O365 launcher.
  3. Set the name as Turbot (or other appropriate name for your organization).
  4. Homepage URL should be the URI of your Turbot Console. For enterprise installations, the hostname may look like: https://console.turbot.company.com. For SaaS, it will look something like https://turbot-orgid.cloud.turbot.com.
  5. Optional: To use a custom logo, create a logo that is 215 by 215 pixels, and save it in PNG format. Then browse to your logo and upload it. We have attached a graphic of appropriate size here:

turbot

Edit SAML Configuration

  1. Sign in to the Azure portal as a cloud application admin or an application admin for your Azure AD tenant.

  2. Navigate to Azure Active Directory > Enterprise applications then select the Turbot application from the list.

    • To search for the application, in the Application Type menu, select All applications, and then select Apply. Enter the name of the application in the search box and then select the application from the results.
  3. Under the Manage section, select Single sign-on.
  4. Select SAML. The Set up Single Sign-On with SAML - Preview page appears.

saml-preview

  1. To edit the basic SAML configuration options, select the Edit icon (pencil) in the upper-right corner of the Basic SAML Configuration section.
  2. Enter the following settings:
Basic SAML Configuration setting SP-Initiated Description
Identifier Required https://{turbot_console_url}
Reply URL Required https://{turbot_console_url}/api/latest/directories/123456/saml/callback
Sign-on URL Required https://{turbot_console_url}/login
Reply State Optional Not Needed
Logout URL Optional Not Needed
  • Note that the Reply URL provided above is a placeholder. The final value will be available after the directory has been created in Turbot.
Configure User Attributes and Claims

When a user authenticates into Turbot, Azure AD issues a SAML token with information (or claims) about the user that uniquely identifies them. By default, this information includes the user's username, email address, first name, and last name. Turbot requires specific attributes and claims as described below.

  1. In the User Attributes and Claims section, select the Edit icon (pencil) in the upper-right corner.

attributes

  1. Choose the Name Identifier Value. The default value is user.principalname. The user identifier uniquely identifies each user within the application. If the email address is both the username and the unique identifier, set the value to user.mail. If you use AD user names then the appropriate value might also be sAMAccountName.
  2. To configure group claims, select the Edit icon for the Groups returned in claim field. For details, see Configure group claims.
  3. Delete default claims as they are not formatted correctly for Turbot. Claim Names starting with http://schemas.xmlsoap.org/ should all be removed. If the default names are not removed and replaced as described below, Turbot will not be able to get proper data for each user; resulting in blank data fields for each Turbot profile.

  4. To add a claim, select Add new claim at the top of the page. Enter the Name and select the appropriate source from the table below. These are the required values that Turbot expects to see in the SAML Assertion.

    • Turbot requires all fields listed below.
    • Please note that the Attribute names are CASE SENSITIVE.
    • There may be some variations in which source attributes are used for which claim, dependent on the configuration of the organization's Active Directory. The most common configuration is provided in the below table.
Attribute Name Source Source Attribute Example
email Email Address user.mail jdoe@company.com
nameID userPrincipalName, email or sAMAccountName user.userprincipalname, user.mail, or user.samaccountname jdoe
displayName userPrincipalName or displayName user.userprincipalname or user.displayname John Doe
firstName Givenname user.givenname John
lastName Surname (sn) user.surname Doe

Before

claims-before

After

claims-after

  1. Select Save. The new claims will appear in the table.

Get Certificate

  1. Download the Base64 encoded 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. 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 Login URL defined in the Azure AD SAML configuration.
    • 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 Azure AD SAML Configuration page, then paste the entire contents into this field.
    • Profile ID Template: 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.
  2. Expand the Groups section. If SAML group syncing is desired, follow the Azure AD group sync directions.
  3. Name ID Format can generally be left as unspecified. This can be flipped to Email Address as needed.
  4. The Signature section can be used to sign requests with a private key and signature algorithm. This is usually used only as an organizational requirement.

  5. 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.
  6. Click the Create button.

Phase 3: Update the Callback URL in Azure AD

  1. Be sure to replace the default Reply URL in the Azure AD 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. The {directoryId} will be a 15 digit number.

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.
  4. 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.
  5. If there are any residual user profiles with incorrect information, delete them before finishing.
  6. Congratulations! Azure AD SAML is now configured and can be used to authenticate users into Turbot.
  7. Grant user permissions as appropriate.

As with other directories 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.