Configuring Azure AD and Guardrails

This guide details configuring a Guardrails application in Azure as well as the directory in Guardrails. Administrator access in Azure and Turbot/Owner permissions in Guardrails 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 Guardrails is a three-phase process.

Initial configuration in Azure AD
Directory configuration and activation in Guardrails
Finalizing configuration in Azure AD

Phase 1: Create the SAML App in Azure

Add a Non-Gallery Application

Sign in to the Azure Active Directory portal using your Microsoft identity platform administrator account.
Select Enterprise Applications > New application.
Select Create your own application. The Create your own application page appears.
Type Turbot Guardrails as the display name for your new application.
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.
Select Create. The application Overview page opens.

Select Properties to open the Properties pane for editing.
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.
Set the name as Turbot Guardrails (or other appropriate name for your organization).
Homepage URL should be the URI of your Guardrails 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.
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:

Edit SAML Configuration

Sign in to the Azure portal as a cloud application admin or an application admin for your Azure AD tenant.
Navigate to Azure Active Directory > Enterprise applications then select the Guardrails 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.
Under the Manage section, select Single sign-on.
Select SAML. The Set up Single Sign-On with SAML - Preview page appears.

To edit the basic SAML configuration options, select the Edit icon (pencil) in the upper-right corner of the Basic SAML Configuration section.
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 Guardrails.

Configure User Attributes and Claims

When a user authenticates into Guardrails, 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. Guardrails requires specific attributes and claims as described below.

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

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.
To configure group claims, select the Edit icon for the Groups returned in claim field. For details, see Configure group claims.
Delete default claims as they are not formatted correctly for Guardrails. Claim Names starting with http://schemas.xmlsoap.org/ should all be removed. If the default names are not removed and replaced as described below, Guardrails will not be able to get proper data for each user; resulting in blank data fields for each Guardrails profile.
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 Guardrails expects to see in the SAML Assertion.
- Guardrails 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

After

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

Get Certificate

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 Guardrails.

Phase 2: Configure Directory in Guardrails

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

3. Select the blue Directories button at the top.

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

5. 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 Guardrails redirects the user to authenticate. This is the Login URL defined in the Azure AD SAML configuration. Issuer: The base Guardrails 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 Guardrails profile for users authenticated through this directory. The ID MUST be unique for each profile in Guardrails, but it is possible to have multiple directories map users to the same ID. This CANNOT be changed unless the directory is new. 6. Expand the Groups section. If SAML group syncing is desired, follow the Azure AD group sync directions. 7. Name ID Format can generally be left as unspecified. This can be flipped to Email Address as needed. 8. 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. 9. 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.

Phase 3: Update the Callback URL in Azure AD

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 Guardrails. 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

Activate the directory by clicking on the upward point arrow icon next to the new directory.
Open a private browser session. Navigate to the Guardrails 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.
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.
If there are any residual user profiles with incorrect information, delete them before finishing.
Congratulations! Azure AD SAML is now configured and can be used to authenticate users into Guardrails.
Grant user permissions as appropriate.

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