Overview

You can use Single Sign-On (SSO) to access your CleverTap dashboard. You must use an Identity Provider (IdP) or a custom SAML (Security Assertion Markup Language) implementation to use SSO with CleverTap. Note that you must be an account admin to set up an SSO.

📘

Key Benefits of New SSO Configuration

The migration steps for existing SSO customers moving to a new SAML SSO setup are the same as setting up the SSO configuration for the first time.

Listed below are the key benefits of the new SAML SSO setup:

• Streamlined SSO configuration process without needing Account-Role Mapping on IdP.
• Flexibility to manage users entirely on the CleverTap dashboard or by sending account lists through IdP and managing roles on the dashboard.
• Enhanced security and simplified login experience for your team through email domain whitelisting.

Set Up SSO Configuration

The SSO Configuration process includes the following two steps:

1. Set up SSO configuration on CleverTap.
2. Configure CleverTap Application on your IdP

Set Up SSO configuration on CleverTap

To set up the SSO configuration on the CleverTap dashboard:

1. Navigate to Organization > SSO from the CleverTap dashboard.
2. Click Create SAML Connection.

The Create SAML Connection window opens on the right side of the screen after you click Create SAML Connection, as shown in the following figure:

3. Enter the following details:

   • Sign-in URL
   • Organization name
   • IDP Signing certificate (You can either paste the certificate details or upload the .CER file)
   • SAML Eligible Email Domains
     In order to claim ownership of a domain, it is necessary for the organization to have at least one active user associated with that particular domain.

4. Click Create.

📘

Note

• After you configure Sign-in URL and IDP Signing certificate, these details are available from your respective identity providers. For more information about IdP configuration, refer Okta, OneLogin, Azure and Gsuite.
• CleverTap recommends avoiding a word processor for copy-pasting sensitive values like certificates; instead, you can use an IDE or terminal.

After creating the SAML connection successfully, SAML Service Provider details are displayed on the page, as shown in the following figure:

5. Navigate to your respective IdP sections in the document and complete the steps mentioned to configure the connection.

📘

Configuration Updates

The following are the updates related to CleverTap's SSO configurations process:

• The IdP metadata XML is not accepted as a configuration parameter anymore.

• The domain discovery now recognizes email domains. It means you can now log in through an IdP using a specific email address (for example, [email protected]) instead of organization names (for example, CleverTap). All users must provide their email addresses, and the system automatically determines if they use SAML or basic authentication.

• All users must provide an email address on the new login page (the old login page still accepts the organization names).

CleverTap strongly recommends adding your email domains rather than public ones or other organizations. If you encounter errors during configuration, it may be because the email domain is public (for example, gmail.com, outlook.com) or already claimed by another organization. Contact our support team if you encounter an issue and want to claim an email domain.

Configure CleverTap Application on your IdP

To configure CleverTap on your IdP, you must map the attributes. The following are the two methods for attribute mapping:

• Add a list of names and emails only (Recommended)
• Send a list of attributes along with accountList and an array of accountIds.

Based on the selected attribute mapping logic and your IdP, map the attributes as illustrated for specific IdPs:

• Attribute Mapping for Okta
• Attribute Mapping for OneLogin
• Attribute Mapping for Azure
• Attribute Mapping for Gsuite

Identity Service Provider

Identity Provider (IdP) is an authority that verifies and asserts a user's identity and access to a requested resource (the "Service Provider"). Some examples of IdPs are Okta, GSuite, and so on.

Attribute Mapping Logic for IdPs

You can set up your IdP attributes in the following two ways:

Add a List of Names and Emails Only (Recommended)

Users onboarded before SAML SSO activation can continue to access their previous accounts. Users onboarded through SAML SSO for the first time are redirected to the no-access page and cannot access any accounts.

The user is onboarded to new accounts by sending an invitation to any account. Inviting a SAML user to an account may not send an email invite; instead, directly grant them access. However, the user needs to log out and then log in to view the new account assignments.

There are no organization-based checks in this method, as the provision of access is still in the hands of the admin of the target account.

Send a List of attributes Along With accountList and an Array of accountIds

In this case, the user can only access the accounts mentioned in the accountList attribute. The invitation flow does not work for gaining access to any account. The account must be added to the accountList. An additional check is performed on the accounts present in the accountList to validate if they belong to a family of accounts for which the current SAML SSO connection is configured. For example, if a connection is made for customer A and tries to pass the account Ids of customer B, they would be blocked.

The optional attribute accountList must be added in the following manner:
accountList : ["1000000001", "1000000002", "1000000003"].

🚧

Note

• If the user has access to any other account on the system apart from the ones present in the accountList, they would lose access to those accounts.
• You must connect all your accounts to a parent account for which the SSO configuration is created.

Configure IDPs

This section illustrates how to set up access for the following IDPs:

• Okta
• OneLogin
• GSuite
• Azure

📘

Note

You can configure any IdP that supports SAML SSO, following the recommended approach.

Okta Setup

This section provides information about the Okta setup. The process involves the following major steps:

1. Create an application.
2. Map the attributes.
3. Assign the CleverTap application to the user.

Create an Application

Start the setup by creating a CleverTap app in your IdP setup. All IdPs allow you to create an app you want to access using SSO. Consider the following example of setting up an app with Okta:

1. Navigate to your Okta admin dashboard.
2. Select Applications from the left navigation and click Create App Integration.

3. After the Sign-in method box appears, select SAML 2.0.

4. Enter your application details as shown in the image below and click Next:

5. Add the Single sign-on URL and Audience URI(Entity ID) values. (You can find these credentials on the Create SAML connection page of the CleverTap dashboard).

Map Attributes

In continuation of the above configuration, ensure that the correct values are passed to CleverTap. To do so, you must map the attributes:

1. Add three attributes - name, email
 and accountList appropriately, and map the attributes accordingly as shown in the image below:

📘

Note

If you proceed further with the recommended method, add only two attributes - name, email
 in the attribute mapping section appropriately. You need not add any custom attributes and hence you must skip step 2.

2. For the accountList attribute, you must create a custom attribute:

   i. Navigate to Directory > Profile editor > Select your application (CleverTap).
   ii. Click + Add Attributes.

iii. Define all the attribute values for accountList.

iv. Click Save

Assign CleverTap Application to User

To assign your CleverTap application to users:

1. Navigate to Applications > Select your application.
2. Select Assign to People from the Assign dropdown.

3. Select the user you want to assign and click Assign

4. Ensure that the accountList value is populated against the accountList attribute in the dropdown.

5. Click Save and Go Back and then click Done.

To find the credentials for setting up SAML connection on the CleverTap dashboard:

1. Navigate to Applications > Sign on
2. Click View SAML Setup instruction available at the bottom right of the page. You can find the credentials as shown in the following figure:

4. Use these credentials to create a SAML connection on the CleverTap dashboard.

OneLogin Setup

This section provides information about the OneLogin setup. The process involves the following major steps:

1. Create an application.
2. Map Attributes.
3. Assign the CleverTap application to the user.

Create an Application

To create an application:

1. Select Applications tab and select Applications from the menu.

2. Click Add App and search for SAML Custom Connector (Advance) in the search bar.

3. Select SAML Custom Connector (Advance) and enter the Display Name.

4. Click Save.

5. From the left panel, navigate to the Configuration section and enter the ACS (Consumer) URL and Audience (EntityID). (You can find these credentials on the Create SAML connection page of the CleverTap dashboard).

Map Attributes

After configuring the application, ensure that correct values are passed to CleverTap by mapping the attributes:

1. From the left menu under Applications tab, navigate to the Parameter section and click the + sign to add new fields and ensure that the Configured by admin button is selected.

2. Add three attributes - name, email
 and accountList appropriately, and map the attributes accordingly as shown below:

📘

Note

If you proceed further with the recommended method, add only two attributes - name, email
 in the attribute mapping section appropriately. You do not need to add any custom attributes and hence you must skip step 4.

3. Add value as FirstName and Email for Name and Email, respectively, and click Save.

4. a. Add accountList as Name and click Save.

   b. Select Value as Macro from the dropdown and pass the account ID.

📘

Note

Ensure that you select the Include in SAML assertion when adding all three attributes as shown in the figure above.

Assign CleverTap Application to User

To assign your CleverTap application to users:

1. Navigate to Users from the top panel and click Users.

2. Select the user you want to assign to the CleverTap application.

The User Info page opens:

3. Navigate to applications from the left panel, click +, and select CleverTap from the dropdown.
4. Click Continue
5. Verify all the values passed for that user from the Edit CleverTap Login page and click Save

Now, you have successfully assigned the CleverTap application to the user.

To create a SAML connection on the CleverTap dashboard, you need two credentials, as mentioned in the beginning. To find your Sign-in URL and IDP Signing certificate:

1. Navigate to the Applications tab from the top panel, and select the CleverTap application
2. Navigate to SSO from the left navigation and copy the SAML 2.0 Endpoint(HTTP) for the SAML connection on CleverTap.

3. Click View Details for the IDP signing certificate as shown below:

4. Use these credentials to create a SAML connection on the CleverTap dashboard.

Azure Setup

This section provides information about the Azure setup. The process involves the following major steps:

• Create an application.
• Map the attributes.
• Assign the CleverTap application to the user.

Create an Application

1. Start the setup by signing up and creating a CleverTap app on the Azure Portal
2. From the left navigation panel, select Azure Active Directory.

3. Click + Add and select Enterprise application

5. Click + Create your application.
6. Enter the name of the application.
7. Select the Non-gallery application option as shown in the following image and click Add.

5. Click Set up single sign on.

The Single sign-on page opens.

6. Click SAML.

7. Click the Edit icon available next to Basic SAML configuration.

8. Add the ACS and Entity ID. You can find these credentials on the Create SAML connection page on CleverTap. To get these credentials:
   1. Navigate to Organization > SSO from the CleverTap dashboard.
   2. Copy the Entity ID and Assertion Consumer Service URL>Create SAML Connection.
9. Paste the respective values into the SAML configuration section as shown in the following screenshot and click Save.

Map Attributes

In continuation of the above configuration, ensure that the correct values are passed to CleverTap. To do so:

1. Under the Attribute & Claims section, you must map the following two attributes: name and email appropriately and click Save (see following figure image below).

📘

Note

If you proceed further with the recommended method, you need not add any custom attributes and hence you must skip step 2.

2. Refer to this Azure support document to create a accountList custom attribute.

Assign CleverTap Application to User

To assign your CleverTap application to users:

1. Navigate to the Azure Active Directory > Enterprise applications.

2. Select the CleverTap application.

3. Select Users and groups under the Manage section from the left navigation.

3. Click + Add user/group and assign the respective user and groups to the application using the options available at the top of the screen.

4. Select the user and click Select.

5. Click Assign to assign that user or group to the SAML application as shown in the following figure:

To find the credentials for setting up SAML connection on the CleverTap dashboard:

1. Navigate to the Azure Active Directory > Enterprise applications.
2. Select the CleverTap application.
3. Select Single Sign On.
4. You can upload the Certificate (.CER )file directly after downloading it using the Download button, as shown in the image below.
5. Copy the Login URL(also known as the Sign-in URL) from the Set up CleverTap section.

4. Use these credentials to create a SAML connection on the CleverTap dashboard.

GSuite Setup

Log in to https://admin.google.com/ and log in as Admin for your app. The GSuite setup involves the following two major steps:

1. Create a SAML app.
2. Map attributes.
3. Assign the CleverTap application to the user.

Create a SAML App

To create a SAML app:

1. From the Gsuite admin dashboard, navigate to Home > Apps > Web and Mobile apps.
2. From the Add app dropdown, select Add custom SAML app.

3. Enter the App name (here, CleverTap) and Description on the App details page and click Continue.

4. Click Continue on the next screen (IdP metadata page).
5. Add the ACS URL and Entity ID. (You can find these credentials on the Create SAML connection page on the CleverTap dashboard)
6. Select Signed Response.

7. Select EMAIL as the Name ID Format for the default Name ID (Basic Information > Primary email).
8. Click Continue.

Map Attributes

In continuation of the above configuration, ensure that the correct values are passed to CleverTap. To do so, you must map the attributes:

1. Click ADD MAPPING after the Attribute mapping screen appears.
2. Under the Attribute mapping section, you must appropriately map three attributes - name, email
 , and accountList and click FINISH (see figure below).

📘

Note

If you proceed with the recommended method, add only two attributes - name, email
 in the attribute mapping section appropriately. You need not add any custom attributes and hence you must skip step 3.

📘

Adding accountList Attribute

To populate accountList in Google directory attribute, you must add a custom attribute.

3. To create a custom accountList attribute:

   i. From the left panel, navigate to Directory > Users > More options > Manage custom attributes.

ii. Click ADD CUSTOM ATTRIBUTES.

iii. In the Category field, enter the value as accountList and add the Description as per your understanding.

iv. Under Add custom fields, enter accountList as the Name.

v. Set Info Type as Text, Visibility as Visible to the organization and No. of values as Single value.

vi. Click Add.

Assign CleverTap Application to User

To assign your CleverTap application to users,

1. Navigate to the Users screen from the left panel.
2. From the list of users, select the user name you want to assign.
3. Click the User Information dropdown.

4. In the accountList custom attribute, pass the accountID and click Save, as shown in the following image:

5. From the left panel, navigate to Apps > Web and mobile apps and select your app.
6. Click the User access dropdown and set the service status to ON for everyone.

To find the credentials for setting up SAML connection on the CleverTap dashboard:

1. Navigate to Apps > Web and mobile apps from the left navigation menu
2. Select the CleverTap application.
3. Click DOWNLOAD METADATA to display the SSO URL, Entity ID, and Certificate, as shown in the following figure.

4. Use these credentials to create a SAML connection on the CleverTap dashboard.

Sign In Using SSO

After you complete the setup, your SSO is activated from the subsequent login.

When you click Continue after entering the email, you are redirected to your IdP login page. After completing your authentication, you are redirected to your CleverTap dashboard again.

Non-SSO users must enter their password after clicking Continue.

🚧

Revoke Users and Delete Connection

• To revoke a user from a project, you must remove the account list for the user from the IdP. If the account list is not removed from the IdP, the user continues to have access to the project. The revoking action on the dashboard only works if the account list for the user is updated on the IdP.

• When a SAML connection is deleted, users must reset their password by clicking Forgot Password on the login screen and creating a new password. They can use this new password for future login.

FAQs

How can I set up Single Sign-On (SSO) across different regions for my projects in CleverTap?

To set up SSO across regions for your projects in CleverTap, follow these steps:

1. Make sure you have an SSO connection for the parent project in any one region.
2. Contact CleverTap support to assist you in configuring this feature.
3. Provide the support manager with a list of all parent accounts for the additional regions where you intend to activate SSO.

Note that you can not configure SSO for multiple regions directly through the dashboard.
To set this up, CleverTap will use your existing SSO connection to enable Single Sign-On for all the other accounts in different regions.