Configuring Okta and Guardrails

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

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

Create the SAML App in Okta

1. Log into the Okta console with an account that has sufficient privileges to add applications.
2. Click the Admin button in the top right to go to the developer console.
3. At the developer console, hover over Developer Console and click Classic UI.
4. From the top menu, select Applications.
5. Select Add Application.
6. Click on Create New App.
7. In the New App dialog, select Web as the platform and SAML 2.0 as the sign on method. Click Create.
8. Enter an appropriate app name (such as turbot-guardrails-okta) and click Next.
9. Enter any value in the Single Sign on URL and Audiance URI (SP Entity ID) text boxes. These will be updated with values obtained from Guardrails after creating the directory. Click Next then Finish to create the app.
10. The new Okta application will appear in your list of applications. Click the new application, go to the sign on tab, then click View Setup Instructions.
11. The following information will be needed to set up the directory in Guardrails:
    • Identity Provider Single Sign-On URL - this will be the Entry point for the Guardrails directory
    • Identity Provider Issuer - this will be the Issuer for the Guardrails directory
    • X.509 Certificate - this will be the Certificate for the Guardrails directory

Create the directory in Guardrails

1. In Guardrails, navigate to the Turbot resource, then click on the Permissions tab (designated with a user icon), and finally on the Directory button.
2. Click New Directory and select SAML.
3. Enter the following information:
   • Title: The title for this directory that will display in the login screen
   • Description: A description for this directory
   • Entry Point: This is the identity provider's single sign on URL - In Okta, it's the Identity Provider Single Sign-On URL you obtained from the View Setup Instructions screen
   • Issuer: This is the identity provider issuer URL - In Okta, the Identity Provider Issuer obtained from the View Setup Instructions screen
   • Certificate: This is the Certificate from the identity provider - In Okta, it's the X.509 Certificate you obtained from the View Setup Instructions screen
   • The Profile ID Template can generally be left to the default value, {{profile.email}}. This is the unique ID that will be mapped to the Guardrails profile.
   • Under the Advanced tab, there is an option to Enable or Disable IdP-initiated SSO logins. If checked, IdP-initiated SSO will be allowed. 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. Often, however, this configuration is set by an organizations security team, and can be verified prior to directory creation.
     • If a user attempts to log in using SAML and gets an InResponseTo is missing from response error, the IdP-initiated SSO box will need to be checked.
4. Click Create.
5. The directory is now created and will appear in the list of directories. The directory can be activated immediately, but it will not function correctly until the SAML app is configured within the SAML application.
6. Click the Edit pencil next to the new directory. Scroll to the bottom of the window and copy the Callback URL.

Re-configure SAML App in Okta

1. In Okta, navigate to the application created in the first part of this guide.

2. In the General tab, click Edit next to SAML Settings.

   • For the Single sign on URL, paste the Callback URL that was copied from the Guardrails directory.
   • For the Audience URI (SP Entity ID), paste the Issuer URL that was entered into the Guardrails directory.
   • In the Attribute Statements (Optional) section, add the following:

   Name	Name Format	Value
   email	unspecified	user.email
   firstName	unspecified	user.firstName
   lastName	unspecified	user.lastName
   login	unspecified	user.login
   displayName	unspecified	user.displayName

   • NOTE: In Okta, there are two Attribute Statement sections: Attribute Statements and Group Attribute Statements. If Guardrails is not properly pulling in user data, verify that the Attribute Statements, not Group Attribute Statements, have the above parameters and values.

At this point, the directory setup is complete. If the directory is not activated, this can be done via the Directory screen in Guardrails. The directory should be selectable via the Guardrails login screen. 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.