Skip to main content

Single sign-on with OAuth for Cloud Platform

Overview

Oauth is an authentication protocol which supports Single Sign-On (SSO) that streamline user access across various applications within an organization. SSO with OAuth enables your users to access the yellow.ai platform using their existing application login credentials, eliminating the need to re-enter them. It enhances security by enabling secure third-party access to user data without exposing login details, providing a seamless and efficient authentication process. Benefits of signing in through OAuth:

  • Eliminates the need for direct sharing of login credentials, enhancing security.
  • You can control and limit third-party access to your data.
  • Proves adaptable to various scenarios in large-scale systems.

SSO workflow

image

Basic terminologies

TermDescription
Resource ownerThe organization who wants to log in to Yellow.ai.
ClientYellow.ai
Authorization serverThe server issuing the access token, in this case, your application.
Resource serverThe application that accepts the access token and must verify its validity.
Redirect URIThis URL is where the Authorization Server sends the user back after granting permission to the Yellow.ai client.
Response typeThe type of information the Client (Yellow.ai) expects to receive. For this case, the Response Type will be "code" indicating an Authorization Code.
Grant typeRefers to the way an OAuth application gets the access token. In this case, the authorization code flow will be used.
ScopeGranular permissions the Client (Yellow.ai) wants, such as access to data or to perform actions. For this case, openid, profile, and email are required scopes.
ConsentThe Authorization Server verifies with the Resource Owner (user) whether they want to give the Client (Yellow.ai) permission.
Client IDThis ID is used to identify the Client (Yellow.ai) with the Authorization Server. Provided by Authorization Server to Client (Yellow.ai).
Client secretA secret password known only to the Client (Yellow.ai) and Authorization Server, allowing secure information sharing. Provided by Authorization Server to Client (Yellow.ai).
Authorization codeA short-lived temporary code the Client (Yellow.ai) gives the Authorization Server in exchange for an Access Token (valid for one-time use with a maximum lifetime of 10 minutes).
Access tokenThe key used by the Client (Yellow.ai) to communicate with the Resource Server. Similar to a badge or key card, it grants permission to request data or perform actions with the Resource Server on behalf of the Client (Yellow.ai).
OAuth applicationThe entity created by the Authorization Server containing details (such as Client ID, Client Secret, Redirect URL, etc.) corresponding to a specific OAuth client.

Configure OAuth sign-in

To configure OAuth, follow the steps below:

Step 1: Set Up OAuth in IDP

Ensure the your Identity Provider (IDP) supports OAuth.

Configure OAuth settings in the client's IDP:

  1. Create a new OAuth client application.
  2. Whitelist the following redirect URLs on your IDP's OAuth app:
  3. Obtain client ID, client secret or other necesary details (step #2).

Steps to retrieve details from a few common identity providers are outlined below:

Identity providerValues required to set up SSO for yellow.aiStep-by-step guide
OktaOkta domain
Client ID
Client Secret
Click here
Red HatRealm
Client ID
Click here
GoogleClient ID
Client Secret
Click here

Note: Select openid, userinfo.email and userinfo.profile under scopes on the Create Consent Screen.
Microsoft AzureADClient ID
Client Secret
Tenant ID
Tenant Domain
Click here
1. Sign in to Azure AD. Click on App Services and select Manage Azure Active Directory.

2. In the left navigation, go to App registrations and click New registration.

3. On the registration page, provide application details. Choose web as the Redirect URI and input the redirect URLs.

4. Click Register. Azure AD will assign a unique Application ID (Client ID) to your application. Copy the Application ID and Directory ID (Tenant ID).

5. Navigate to Certificates and Secrets, click New Client Secret. Enter a description, set expiration, and click ADD. This will be your Client Secret key.

Watch this video on how configure your identity provider (Microsoft AzureAD) and fetch details for yellow.ai SSO configuration:

note

If your identity provider isn't configured in yellow.ai for SSO, share OAuth details directly with [yellow.ai's support team]((mailto:[email protected]).

Step 2: Share OAuth setup details

Once you have set up your IDP, share the following details (fetched from your identity provider) with our support team at [[email protected]]((mailto:[email protected]) :

FieldDescription
EmailYour email address associated with the platform.
API VersionThe version of the OAuth API being used. Ensures compatibility between the platform and the OAuth service.
ScopeThe extent of access requested. Specifies resources or actions the application seeks permission to access.
DomainThe domain name configured for OAuth, used to identify and access the platform.
Client IDA unique identifier assigned by the OAuth provider to recognize and authorize the application.
Tenant IDIdentifies the instance or organization within the OAuth provider, relevant for multi-tenant systems.
Auth URLURL where users are redirected for authentication and authorization.
Token URLURL where the platform obtains the OAuth access token after user authentication.
Token scopeDefines the level of access the access token has.
User Info URLURL to retrieve additional information about the authenticated user.
Client SecretA secret known only to the application and the OAuth provider for authentication during token requests.

After verifying your details, SSO will be enabled for your domain by the yellow.ai team.

Step 3: Sign-in using OAuth

  1. Login to cloud.yellow.ai
  2. Enter the domain name configured for OAuth by the Yellow support team. Click on the Sign with OAuth button. image
  3. You will be redirected to the third-party tool, where you can log in using its credentials to log in to the Yellow platform. image

Step 4: Create your bot

Once OAuth is enabled, create a bot. In the URL, locate and copy the botId (separate for live/production). This botId is required for providing access and assigning roles.

image


Role-based access through OAuth

Yellow.ai platform supports various user roles, such as developer, agent and admins. You can configure different roles within your OAuth app and assign users to each role as per your requirement.

To enable role-based access for your OAuth set-up, follow these steps:

Prerequisite: Configure OAuth sign-in and fetch your bot ID.

Step 1: Add user roles in IDP

Add roles in your respective identity provider app. Following are the supported user roles in the yellow.ai platform:

  • Admin (Bot Admin)
  • Agent (Inbox (Agent))
  • Developer (Developer)
  • InsightsUser (Insights user)
  • EchoAdmin (Inbox admin)
  • Approver
  • Tester
  • Database (Database viewer)
  • EngagementAdmin (Engage admin)
  • EngagementUser (Engage viewer)
note

Super admin role is automatically created and assigned to the primary email address of the bot when the bot is created. It cannot be assigned through role mapping or the yellow.ai UI. Learn more about other user roles here.

Syntax to add user roles in the identity provider app: botId.{role}

Example: x1599503999999.admin

Syntax to provide table and read/write access to database users:

  • For App and Cloud (legacy tables):botId.database.{tableName}.{accessType}
  • For Cloud (v2 tables): botId.database.{tableName}:v2.{accessType}
info

accessType can have one of the following values:

  • read for viewing the respective tableName. Ex: x1599503999999.database.feedback.read, x1599503999999.database.users.write
  • write for performing editing operations on the respective tableName. Ex: x1599503999999.database.users:v2.read, x1599503999999.database.feedback:v2.write

Step 2: Assign users to roles in IDP

Once the roles are added to your IDP, you can assign users to each role. Steps to add user roles differ for each identity provider, follow the steps mentioned by the provider itself. For example, this guide is for Microsoft AzureAD.

The following video demonstrates how to assign users to a user role in Microsoft AzureAD.

note

If your identity provider isn't configured in yellow.ai for SSO, share OAuth details directly with yellow.ai's support team.

Step 3: Share user role details with yellow.ai

Share the following information with the support team at [email protected]:

  • OAuth details if the identity provider is not configured in yellow.ai for SSO.
  • Roles or groups created in user details (retrievable on yellow platform through the /userinfo endpoint). Also, share the key associated with passing role values. Refer to the legend below for the correct role attribute based on your identity provider:
Identity Provider TypeRole Attribute
Azure Active DirectoryRoles
OktaGroups
Auth0As configured on the identity provider (dynamic value)
Ping IdentityAs configured on the identity provider (dynamic value)

Testing what user details are retrieved from your OAuth using /userinfo endpoint

To know what user details are retrieved by the SSO, make an API request to the GET /userinfo API.

The JSON response includes the following data - email, roleAttribute, given_name, and roleAttribute. If a user is assigned to multiple roles across various bots, you will observe the list of role attributes along with their associated bots presented as an array within the roleAttribute field, as demonstrated in the following response.

{
"email": "[email protected]",
"family_name": "Steve",
"given_name": "Smith",
"roleAttribute": ["x1597777777777.admin", "x1597777777777.agent", "x1607777777777.admin", "x1607777777777.developer"]
}
note

Once OAuth role mapping is enabled, the role update UI (Bot setting > Access control) on the yellow.ai platform will be disabled. Roles can only be updated from the identity provider, and users will be assigned updated roles at the time of login.