SAML-Based SSO from Identity Provider to Sugar Integrate

This guide addresses the prerequisites and steps necessary to initiate a single sign-on (SSO) connection from an Identity Provider (IdP) to Sugar Integrate.

Introduction

Sugar Integrate supports single sign-on via a Security Assertion Markup Language (SAML)-based UI flow. This means that a user can sign in to the Sugar Integrate UI without being required to provide their login credentials to Sugar. Before a user of a Sugar Integrate customer or partner can use SAML-based SSO/authentication, the customer or partner must first complete the setup process as outlined in this guide. You can find the Postman collections referred to in this document here.

Overview

In order for the SAML-based SSO to occur, there must be a trust established between the Identity Provider and the service provider, in this case, Sugar Integrate. This means the SAML metadata from the Identity Provider are entered in Sugar Integrate, and the SAML metadata from Sugar Integrate is entered in the Identity Provider. In some cases, the Identity Provider and the Identity Broker may be the same service.

The SAML-based SSO process is illustrated in the diagram below and explained in the subsequent steps:

  1. A user clicks Go to Sugar Integrate.
  2. Identity Provider creates a user in Sugar Integrate. This user should be present in Identity Provider and/or Broker. The customer signup payload specifies these values:
    • User object, in which the externalId is the email address or GUID of the user in Identity Provider (preferably a persistent token, like GUID). Here, you can also specify the roles the user may have. Currently either org-admin or admin (admin is an account admin). Defaults to org if placed in the default account for their org, otherwise defaults to default-user.
    • Account object, in which the externalId is a unique account ID in the Identity Provider system.
    • Organization object, in which the externalId is the unique organization ID in the Identity Provider system. Here, you can optionally specify role definitions for the organization. The role definitions specify the privileges to define fine-grained access controls.
  3. Identity Provider kicks off the SSO login flow on Sugar Integrate at https://my-staging.cloudelements.io/login/sso?orgExternalId=%3CorgExternalId%3E&customerId=%3CcustomerId%3E&accountExternalId=%3CaccountExternalId%3E
    1. Sugar Integrate looks up the registered Identity Provider
    2. Sugar Integrate sends SAML login request via redirect to Identity Provider
    3. The user logs in. This step may be skipped if the active session is cached. This step is also where additional dialogs occur, such as those for identity confirmation.
  4. Identity Provider sends an assertion request to Sugar Integrate.
    1. Contains nameId token. This is the user token from the Identity Provider, which maps to Sugar Integrate' user.externalId used in customer signup (see step 2).
    2. Sugar Integrate does a lookup based on the nameId token and previous values (orgExternalId, accountExternalId, and customerId) stored in the RelayState) to find the appropriate user.
    3. On update of SAML attributes (FirstName and LastName), Sugar Integrate will update the existing user with the provided attributes.
  5. After finding the active user, Sugar Integrate responds with an authenticated redirect call to the Sugar Integrate UI.
  6. The user is redirected to Sugar Integrate.

Prerequisites

Before you can utilize SAML-based SSO, the customer should have the following:

  • An identity management solution, or at least one selected for potential future use
  • The ability to support SAML-based SSO in their platform

Customer Setup

To enable SAML-based SSO, have a Sugar Integrate Customer Success administrator create a customer administrator privilege for the customer/partner. Once this record is created, the customer will be provided with a customerId  , which is required to allow a user to sign in to the Sugar Integrate UI using SSO. In addition, the customer is provided their admin user credentials, which will allow the customer to manage, among other things, their Identity Provider(s) (IdP) and SSO members.

Additionally, Orgs (a customer’s customer/partner or business unit) and Accounts within Orgs (divisions/departments) can be set up within the Customer record, which in turn allows the Sugar Integrate customer to manage their customer hierarchy, users, and privileges for the user. Orgs/Accounts/Users can be set up using the Sugar Integrate UI, or can be set up using APIs provided in our Postman collections.

The following chart illustrates the Customer/Organization/Account/User structure in Sugar Integrate:


Sugar Integrate can support multi-tenancy via SSO, assuming all parameters are provided. This means that a customer's user can belong to multiple accounts or organizations, depending on the fields sent on an SSO login request, thereby allowing multiple users in the Sugar Integrate system.

Identity Provider Setup

The customer admin is required to setup the IdP that will be utilized by the customer for the SSO process. The IdP can be set up by signing into the Sugar Integrate UI and selecting the Security left navbar item, or via API as provided in our Postman collections.

To set up an IdP using the Sugar Integrate UI, please refer to this video recorded by a Sugar Integrate engineers. The video illustrates setting up an SSOCircle-based IdP and the ensuing SSO process.

Service Provider Registration

In order for the SSO to properly function, the Service Provider (SP), in this case Sugar Integrate, needs to be registered with the IdP. The above video also demonstrates registering the SP with the IdP.

Member Setup

In order to successfully complete the SSO handshake, the user ID/token needs to be registered with Sugar Integrate to ensure that only users with a subscription can SSO to Sugar Integrate from the customer application.

Members can be added either via the Sugar Integrate UI, as demonstrated in the video above or can be added via API using our Postman collections.

Since the video used a local Sugar Integrate setup, i.e. on Tyler’s laptop, some changes to the URLs and endpoints must be made as shown in the video in order to use the Sugar Integrate Staging environment. Complete these steps:

  1. All references to https://*.ngrok.io should be replaced with https://staging.cloud-elements.com.
  2. All references to https://my-localhost.cloudelements.io should be replaced with https://my-staging.cloudelements.io.
  3. For the /authentication/saml/{id}/metadata path in the SP URL, the {id} is that of the IdP registered with Sugar Integrate.
  4. In all of the Postman collections, do the following:
    • The Postman variable 0 should be set up with a value of https://staging.cloud-elements.com/elements/api-v2
    • The Postman variable should be set up with a value of Organization <orgSecret>, User <userSecret>, where the value for <orgSecret> and <userSecret> is set up for the Customer Admin user, and can be obtained from the Sugar Integrate UI by signing into the console with the Customer Admin’s credentials.

SSO Sign In Process

There are two ways to kick off the SSO sign in process:

Method 1: Client-side Route

This method invokes the client-side route, https://my-staging.cloudelements.io/login/sso and has two variations:

Method 2: Server-side Route

This method invokes the server-side route, https://staging.cloud-elements.com/elements/api-v2/authentication/saml/. This method is used to contact the SP directly without going through the UI of the SP.

The video above demonstrates the first method and variation to sign in via SSO.

SSO Sign Out Process

If a logoutUrl and logoutRedirectUrl is configured for the IdP, then upon signing out from the Sugar Integrate UI, the IdP’s logoutUrl is invoked. This closes the session and redirects the user to the logoutRedirectUrl, which could be the home of the original application.