SAML-Based SSO from Identity Provider to Cloud Elements

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

Note that we do not support SSO for element authentication or instantiation; rather, this article addresses SSO for the Cloud Elements platform.

Introduction

Cloud Elements supports single sign-on via a Security Assertion Markup Language (SAML)-based UI flow. This means that a user can sign in to the Cloud Elements UI without being required to provide their login credentials to Cloud Elements. Before a user of a Cloud Elements 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, Cloud Elements. This means the SAML metadata from the Identity Provider are entered in Cloud Elements, and the SAML metadata from Cloud Elements 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 Cloud Elements.
2. Identity Provider creates a user in Cloud Elements. 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 Cloud Elements at https://my-staging.cloudelements.io/login/sso?orgExternalId=%3CorgExternalId%3E&customerId=%3CcustomerId%3E&accountExternalId=%3CaccountExternalId%3E
   1. Cloud Elements looks up the registered Identity Provider
   2. Cloud Elements 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 Cloud Elements.
   1. Contains nameId token. This is the user token from the Identity Provider, which maps to Cloud Elements' user.externalId used in customer signup (see step 2).
   2. Cloud Elements 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), Cloud Elements will update the existing user with the provided attributes.
5. After finding the active user, Cloud Elements responds with an authenticated redirect call to the Cloud Elements UI.
6. The user is redirected to Cloud Elements.

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 Cloud Elements 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 Cloud Elements 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 Cloud Elements customer to manage their customer hierarchy, users, and privileges for the user. Orgs/Accounts/Users can be set up using the Cloud Elements UI, or can be set up using APIs provided in our Postman collections.

The following chart illustrates the Customer/Organization/Account/User structure in Cloud Elements:

Cloud Elements 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 Cloud Elements 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 Cloud Elements UI and selecting the Security left navbar item, or via API as provided in our Postman collections.

To set up an IdP using the Cloud Elements UI, please refer to this video recorded by a Cloud Elements 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 Cloud Elements, 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 Cloud Elements to ensure that only users with a subscription can SSO to Cloud Elements from the customer application.

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

Since the video used a local Cloud Elements 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 Cloud Elements 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 Cloud Elements.
4. In all of the Postman collections, do the following:
   • The Postman variable0 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 Cloud Elements 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:

• The first variation specifies lookup values in the query parameter (accountExternalId, customerId, and orgExternalId) to find and invoke the requisite IdP. This is primarily used when the developer cannot store the Cloud Elements IdP ID or intends to offer multiple IdP services to their users. This first variation uses the following URL: https://my-staging.cloudelements.io/login/sso?accountExternalId=<accountExternalId>&customerId=<customerId>&orgExternalId=<optionalOrgId>. In this variation, the accountExternalId and customerId can be provided as query parameters to the login URL above.
• The second variation directly invokes the IdP that has been registered in Cloud Elements via the IdP ID. This is primarily used when a developer is only offering a single IdP service to their users. This second variation uses the following URL: https://staging.cloud-elements.com/elements/api-v2/authentication/saml/%7BidentityProviderId/login

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 Cloud Elements 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.