# Just-in-time provisioning

> For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt)

Source: https://developers.thoughtspot.com/docs/just-in-time-provisioning

# Just-in-time provisioning

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:

1.  Does the user exist in ThoughtSpot?
    
    1.  If the user does not exist, create the user.
        
    
2.  Is the user in this Org?
    
    1.  If not in the Org, add the user to the Org.
        
    
3.  Update the user’s current provisioning within the Org (ThoughtSpot Group membership).
    
4.  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]({{navprefix}}/{{trusted-auth-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:

1.  `[/users/{user-identifier}/update](https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fupdate-user)` 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.
        
    
2.  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:

```json
{
  "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](https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fupdate-user-group)` 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:

```json
{
  "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](https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fupdate-user-group)` endpoint.

## Group privileges and access control via REST APIs

[Privileges]({{navprefix}}/{{api-user-management}}) are either assigned directly to a group or part of roles if [Role-based access control (RBAC)]({{navprefix}}/{{roles}}) 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](https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fsecurity%2Fshare-metadata)** 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]({{navprefix}}/{{abac_rls-variables}}) pattern, which allows assigning many values to multiple variables via the [Custom Token request]({{navprefix}}/{{abac_rls-variables}}#_create_an_abac_token_request_with_variable_attributes).

There is also a direct [variable values update REST API]({{navprefix}}/{{variables}}#_update_variable_values) 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

> **NOTE:** If your ThoughtSpot cluster uses per-org IdP configuration, ThoughtSpot automatically filters SAML and OIDC group and org claims at login time. Only claims that reference the Org bound to the authenticating IdP are used for JIT provisioning. Claims referencing other Orgs are dropped and logged as security audit events. This behavior ensures that a per-org IdP cannot be used to provision users into Orgs it is not authorized to manage. For more information, see Org isolation for per-org IdP authentication.

For SAML SSO users, you can [enable SAML authentication](https://docs.thoughtspot.com/cloud/latest/authentication-integration#_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](https://docs.thoughtspot.com/cloud/latest/authentication-integration#_configure_the_idp).

For JIT group assignment to [SAML SSO users and group mapping](https://docs.thoughtspot.com/cloud/latest/saml-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](https://docs.thoughtspot.com/cloud/latest/oidc-configure#configure-ts).

JIT group assignment [can be enabled for OIDC via a support ticket]({{navprefix}}/{{configure-oidc}}#group-synchronization).