Just-in-time provisioning

Table of Contents

JIT REST API provisioning (trusted authentication)
User creation or adding to Org
- Create user and update user REST APIs
- autocreate using token request
Group assignment
Group privileges and access control via REST APIs
RLS variable values
IdP assertion provisioning
SAML SSO authentication
OIDC authentication

Just-in-time (JIT) provisioning in ThoughtSpot refers to creating or updating authentication and authorization at the time a user signs in to ThoughtSpot.

Due to the variety of options in ThoughtSpot, there are often several ways to accomplish JIT provisioning.

The steps to JIT provisioning are conceptually:

Does the user exist in ThoughtSpot?
1. If the user does not exist, create the user.
Is the user in this Org?
1. If not in the Org, add the user to the Org.
Update the user’s current provisioning within the Org (ThoughtSpot Group membership).
Update any variable values for the user via token request (token authentication only).

Due to the nature of API capabilities and error responses, along with restrictions around Org separation, the actual order of efficient steps may not follow the order listed above.

JIT REST API provisioning (trusted authentication)🔗

All of the following may be considered for JIT provisioning, using the same REST API capabilities as provisioning ahead of time:

User creation or adding to Org
Group assignment for users
- Group creation and updates
RLS variable values for user

These can all be implemented as part of the token request service in the trusted authentication pattern.

The token request service will need access to both the secret_key for the token requests and a service account with the appropriate administrator privileges to run the other REST API commands.

User creation or adding to Org🔗

For a login token to be requested, the user must exist in ThoughtSpot in the Org the token is being requested for.

Creating a new user requires at minimum the username, email address, display name, and org IDs to create them in.

Create user and update user REST APIs🔗

If you need to update a user’s details, including their group membership, the simplest method is to use:

/users/{user-identifier}/update in the target Org with the operation: REPLACE option.
1. If you receive an error, retry the /users/{user-identifier}/update request with an Administrator service account in the Primary Org to add the user to the desired Org, with operation: ADD.
2. If you still receive an error, the user does not exist in ThoughtSpot. Use /users/create from the Primary Org to create the user and place in the desired Org(s).
3. Retry the original /users/{user-identifier}/update command in the desired Org.
Request the preferred auth token for the user, without using any autocreate= options.

You could instead check for the user’s state with an Org via /users/search. and avoiding unnecessary updates and error handling steps.

Any additional changes to the Groups themselves can be managed with other REST APIs described in the following section.

autocreate using token request🔗

There are several token request endpoints, each with an autocreate=true option for just-in-time provisioning:

/api/rest/2.0/auth/token/full
/api/rest/2.0/auth/token/custom
/api/rest/2.0/auth/token/object

Note	`autocreate=true` creates the user (and any new groups) with default options, which may not be preferred. Using the direct `users` and `groups` endpoints allows full control of their options.

The following details must be included in a request with autocreate=true to allow provisioning the user:

The auto_create: true parameter enables the token for the JIT provisioning of the user.
The display_name and email parameters are also required for JIT user creation.
If Orgs are enabled, specify the org_id parameter to direct ThoughtSpot to assign the user to the specified Org.
Specify the group_identifiers parameter only if you want to enable JIT group assignment. Passing group_identifiers: [] will set the user to be assigned to no groups, while excluding the group_identifiers parameter altogether will leave the user assigned to their existing set of groups.

Users created via autocreate=true are identical to users created manually or via the REST APIs, except they do not have passwords in ThoughtSpot; they cannot access ThoughtSpot other than through the SSO method. You can assign a password to any user later through the UI or a REST API call.

Group assignment🔗

Groups in ThoughtSpot are used to assign a variety of attributes such as content sharing, group-based RLS, roles, and column-level security. JIT provisioning often requires a combination of updates to both the user and the groups they belong to.

Group assignment via Update User REST API🔗

The /users/{user-identifier}/update API can update a user’s Group membership within the Org, determined by the org_id of the auth token used for the REST API request:

{
  "operation": "ADD",
  "group_identifiers": [
    "New Group A"
  ]
}

You can also choose "operation" : "REPLACE" to reset the entire set of Groups for a user.

Note	You cannot set a user’s groups in an Org other than the REST API request’s auth token. If you create a user from the Primary Org, any `group_identifiers` provided at that time will apply only within the Primary Org, even if you add the user to multiple Orgs in the `/users/create` request.

Group assignment via Update Group REST API🔗

Because group membership is a relationship between a user and a group, you can also update the set of users within a group using the /groups/{group_identifier}/update REST API endpoint.

Similarly to the user update endpoint, you can choose between three operations: ADD, REPLACE, and REMOVE to update only the user_identifiers of a group without affecting other properties:

{
  "operation": "ADD",
  "user_identifiers": [
    "new.user@website.com"
  ]
}

Group assignment via token request🔗

The various token requests can set or update a user’s group membership when autocreate=true is set. However, they have slightly different behaviors:

/auth/token/full and /auth/token/object do a full replace of the list of groups on every token request
/auth/token/custom only assigns groups if the user is created

The list of groups should be composed of group_name properties, rather than display_name.

If a group name is provided that does not match any existing group name, a new group will be created during the provisioning process.

Groups created via autocreate=true will have identical group_name and display_name properties but will otherwise be a default ThoughtSpot group, granting no access control, privileges or roles.

However, you can assign privileges or make any other adjustment to the new groups via REST API /groups/{group_identifier}/update endpoint.

Group privileges and access control via REST APIs🔗

Privileges are either assigned directly to a group or part of roles if Role-based access control (RBAC) is enabled on your instance.

Roles must be created first prior to being assigned as part of the /groups/create or /groups/{group_identifier}/update REST API request.

Access control in ThoughtSpot is based on sharing content to groups or directly to users.

Sharing requires that the group or user exist prior to calling the sharing REST API.

RLS variable values🔗

RLS rules can use a user’s username, group membership or variable values to define a filtering clause added to all queries on a table.

If using ts_groups in a RLS Rule, the group names must match exactly with the values in a column in the data warehouse, so the name of the group itself serves as a data entitlement.

Variable values are used as part of the ABAC via RLS variables pattern, which allows assigning many values to multiple variables via the Custom Token request.

There is also a direct variable values update REST API for more complex or bulk updates.

IdP assertion provisioning🔗

Due to the nature of assertions returned from an IdP, the JIT provisioning capabilities are more limited. The REST APIs available within the trusted authentication workflow described above can still be used for provisioning and updates, but must be made prior to IdP assertion.

In general, the IdP assertion can create a user and add them to existing ThoughtSpot groups within existing ThoughtSpot Orgs.

SAML SSO authentication🔗

For SAML SSO users, you can enable SAML authentication and Automatically add SAML users to ThoughtSpot upon first authentication.

For information about how to map username, displayName, email, and orgId properties from the IdP, see Configure the IdP server for SAML authentication.

For JIT group assignment to SAML SSO users and group mapping, contact ThoughtSpot Support.

OIDC authentication🔗

OIDC SSO can be configured for JIT user creation, as the necessary properties should already be configured as part of the claims.

JIT group assignment can be enabled for OIDC via a support ticket.