Enforcing SAML Single Sign On Across Your Team

SAML (Security Assertion Markup Language) is the preferred industry standard for implementing single sign-on (SSO) for an enterprise’s multiple applications.

SAML SSO works on the principle of an Identity Provider (IdP), such as Okta, and a Service Provider (SP), such as Hevo. The Identity Provider is an entity providing the identity details of users, including the ability to authenticate them. The IdP typically also stores the user profile, which has additional information about the user such as the first name, last name, job code, phone number, and address. If SSO is enabled, all applications the user tries to log in to request the IdP for authentication and thus one credential (of IdP) works for the different applications.

The Service Provider is an entity providing the service, typically in the form of an application. For example, Hevo is a service provider.

The IdP maintains the identity details of the user. When the user tries to log in to the SP, SAML is used to send the assertion containing user’s information to the SP. The SP validates these against the team configurations stored with it to successfully authenticate the user.

SAML-SSO can be of two types:

  • IdP-initiated: This means that a user may log in to the SAML-enabled IdP and from there, access the app. For example, the user may log in to their IdP’s dashboard and click on the Hevo app to log in.

    IdP-initiated SAML flow

  • SP-initiated: This means that the user may connect directly to the service provider and is authenticated based on the identity configurations stored with the SP. For example, the user may try to log in directly to Hevo, whereby Hevo processes the SAML assertion received from the IdP to authenticate and log in the user.

    SP-initiated SAML flow

To enable SAML-SSO for Hevo, you need to complete the following steps:

  1. Set up Hevo as an App in a SAML-enabled IdP

    1. Retrieve the app connection settings from Hevo. You will provide these in the IdP to set up the Hevo app.

    2. Configure Hevo as an application in your IdP org.

  2. Set up SAML-SSO in Hevo

    1. Copy the SAML settings from the IdP, to configure in Hevo

    2. Configure SAML-SSO in Hevo.

The sections below explain these steps in detail.

Prerequisites

  • You have created a team in Hevo.

Retrieving Hevo App Settings

You need to provide a few settings while configuring Hevo as an app in your IdP org. These settings are used to establish the users’ identity and determine the Hevo instance and team they belong to, when they try to connect to Hevo through their IdP dashboard.

To retrieve the settings:

  1. Log in to Hevo.

  2. Click the drop-down next to your username in the User Info Panel.

  3. Click Team.

    Select Team

  4. Click Authentication in the left navigation pane. This option is visible only to team owners.

  5. Select Require SAML Single Sign-On (SSO).

    Select SAML-SSO option

  6. In the settings that are displayed:

    SAML Settings

    1. Click the Copy icon next to the Relay State field. The relay state includes details such as the team ID and Hevo environment and the indicator that the login is occurring through the IdP.

      Tip: You can decode the text using any online UTF-8 text decoder such as Base64 Decoder to view the details the relay state holds.

    2. Click the Copy icon next to the SP Meta Data field to copy the URL. Access the URL in a new browser window. You will need to provide some of the Hevo metadata from the displayed XML file in your IdP settings.

      SP Metadata

Adding the Hevo App to your SAML-enabled IdP

In your IdP dashboard, you must add all the applications for which you want to enable single sign-on. Then, you must assign users to the app for it to appear on their IdP dashboard. The following section describes the steps for doing this using Okta as the IdP. However, the steps should be very similar for most of the popular IdPs.

Step 1: Add the Hevo app

  1. Log in to your SAML-enabled IdP such as Okta.

  2. In the dashboard, click Add App.

    Add Hevo App to IdP

    If you have configured applications in Okta previously, you may see the following screen. Click Add Application in this:

    Existing apps

  3. In the Add Application page, click Create New App.

  4. In the pop-up dialog that appears, select the Platform as Web and Sign on method as SAML 2.0 and click Create.

  5. In the General tab, specify the following App Settings including the name for the app.

  6. Specify the following SAML Settings:

    • Single Sign-on URL: The URL for accessing the Hevo app. Use the URL from the Location field in the SP metadata that you copied above. For example, https://auth.hevodata.com/auth/saml/assertion.

    • Use this for Recipient URL and Destination URL: Select this check box.

    • Audience URI (SP Entity ID): The URL of the intended recipient of the SAML response. Paste the entity ID mentioned in the SP metadata XML file above. For example, http://samlsp.hevodata.com.

    • Default Relay State: Paste the relay state detail that you copied in Step 6-1 of section Retrieving Hevo App Settings above.

    • Attribute Statements - The attributes that will be included in the SAML assertion response sent by Okta for authenticating the user. At a minimum, you must add an email attribute as that is a mandatory attribute for Hevo. If this information matches what is entered by the user in Hevo, they get directly logged in.

      • Name: Specify the attribute name. For example, user-email to indicate an email ID.

      • Value: The information that the attribute holds. For example, user.email.

        Attribute statement

        In this example, Hevo validates the email ID entered by the user against the user-email field in the SAML assertion response received from Okta.

        Note: While you may select different IdPs such as Okta or OneLogin, Hevo mandatorily requires the users’ Email ID for authentication purposes.

  7. Click Preview the SAML Assertion to view the information that is generated based on the details you entered above. A SAML assertion is the XML document containing the user authorization information that Okta would send to Hevo. For example, the attribute statement you entered above is included as follows:

    SAML assertion

  8. If no further changes are needed, click Next and then, Finish.

Step 2: Assign Users to the Hevo App

  1. In your Okta dashboard, access the Applications page.

  2. Click Assign Users to App.

    Assign users

    Alternatively, in the list of applications, click the Hevo app, and then click the Assignments tab.

    Assign app to users

  3. Click the Assign drop-down and then click, Assign to People.

  4. Search and add the users to the app.

  5. Once all users are added, click Done. The users will now see Hevo in their Okta dashboard.

    View app in dashboard

Step 3: Retrieve IdP Settings

When you add Hevo as an app in the IdP, it generates some configuration settings that you will need for setting up SAML-SSO in Hevo.

Perform the following steps to retrieve these:

  1. In your Okta dashboard, click the Hevo app, and then click the Sign On tab.

  2. Click View Setup Instructions.
    Alternatively, click Identity Provider metadata.

    Access IdP metadata

  3. Copy the information available on the page:

    • Identity Provider Single Sign-On URL

    • Identity Provider Issuer

    • X.509 Certificate. Click Download certificate to save the certificate file.

      You will need to provide these details in Hevo.

Configuring SAML SSO in Hevo

  1. Log in to Hevo

  2. Click the drop-down next to your username in the User Info Panel.

  3. Click Team.

  4. Click Authentication in the left navigation pane. This option is visible only to team owners.

  5. Select Require SAML Single Sign-On (SSO). The page expands to list the configuration settings you must provide:

    SAML settings page

  6. Specify the following settings:

    • Automatic Provisioning: If enabled, any new user who authenticates with Hevo via my IdP, gets added to your team.
      When a new user tries to log in to Hevo, they are directed to your company’s IdP’s login screen. Once they log in successfully, they are added to your Hevo account and are visible in the Team Members list.

      If this setting is disabled, you must invite the new member via the Members page to enable them to log in.

    • The following settings received from the IdP in the previous section:

      • Upload X.509 Certificate for IdP: The certificate that you downloaded from the IdP. This is the signature used to validate any request received by Hevo from the IdP for a user login.

      • IdP Entity ID: The details that identify the user in the IdP.

      • Login URL: The IdP’s Single Sign-On URL. This is the URL to connect to the IdP from Hevo for authenticating the user.

    • Pick Email ID from saml2:NameID Element: When enabled, the field specified in the SAML assertion (received from the IdP) is used to compare the user’s email ID. If disabled, you must provide the IdP Mapping Attributes, of which, the Email field is mandatory.

    Refer to sub-step 7 of section Step 1: Add the Hevo app.

Testing the SAML-SSO Configuration

Once you have configured SAML-SSO, you cannot modify it even as a Team Owner. Therefore, once you log out, you may not be able to log in if configurations are incorrect. You will have to contact Hevo Support in such a situation.

To preempt login difficulties, Hevo recommends that you test the configurations while being logged in to Hevo.

To do this:

  1. Enable login via SAML-SSO settings in Hevo.

  2. Open an incognito browser window and try to log in to Hevo via SAML-SSO.

    • If you can log in successfully, your SAML-SSO configurations are correct.

    • If you face any issue logging in, check your IdP settings to troubleshoot the problem.


Revision History

Refer to the following table for the list of key updates made to this page:

Date Release Description of Change
May-19-2021 1.63 New document.
Last updated on 01 Jun 2021