diff --git a/modules/ROOT/pages/common/nav-embedding.adoc b/modules/ROOT/pages/common/nav-embedding.adoc index dbcec8c9d..82bbeab9d 100644 --- a/modules/ROOT/pages/common/nav-embedding.adoc +++ b/modules/ROOT/pages/common/nav-embedding.adoc @@ -61,6 +61,7 @@ Authentication and data security ** link:{{navprefix}}/saml-sso[SAML SSO authentication] ** link:{{navprefix}}/oidc-auth[OpenID Connect authentication] ** link:{{navprefix}}/just-in-time-provisioning[Just-in-time provisioning] +** link:{{navprefix}}/jit-provisioning-best-practices[JIT provisioning best practices] * link:{{navprefix}}/security-settings[Security settings] * link:{{navprefix}}/embed-object-access[Authorization] diff --git a/modules/ROOT/pages/jit-provisioning-best-practices.adoc b/modules/ROOT/pages/jit-provisioning-best-practices.adoc new file mode 100644 index 000000000..3038058f0 --- /dev/null +++ b/modules/ROOT/pages/jit-provisioning-best-practices.adoc @@ -0,0 +1,235 @@ += JIT provisioning best practices +:toc: true +:toclevels: 2 + +:page-title: Best practices for just-in-time provisioning +:page-pageid: jit-provisioning-best-practices +:page-description: Recommendations and best practices for implementing just-in-time user provisioning in ThoughtSpot embedded and SSO deployments + +This page provides recommendations for implementing xref:just-in-time-provisioning.adoc[just-in-time (JIT) provisioning] in production deployments. It is intended for solutions engineers, embed developers, and platform administrators designing SSO-driven user lifecycle management in ThoughtSpot. + +== Overview + +JIT provisioning refers to creating or updating a user's authentication and authorization state *at the moment they sign in*, rather than provisioning users ahead of time. Conceptually, every JIT flow answers four questions in the following order: + +. Does the user exist in ThoughtSpot? +.. If the user does not exist, create the user. +. Is the user in the target Org? +.. If not in the Org, add the user to the Org. +. Is the user's group membership, and therefore privileges, sharing, and row-level security (RLS) entitlements, current? +.. Update the membership if required. If a group passed in the request does not exist, the group is created in its respective Org. +. Do any RLS or attribute-based access control (ABAC) variable values need setting? +.. Variable values are set at the user level. + +In practice, API error-handling behavior and Org-separation rules mean the most efficient implementation does not always follow this exact order. + +The sections on this page build up a complete JIT implementation in layers: onboarding a new user (Use case 1), adding group provisioning (Use case 2), and adding ABAC and RLS variable values (Use case 3). These are layers of one login flow, not alternatives. See xref:jit-provisioning-best-practices.adoc#combine-use-cases[Combining the use cases]. + +== When and where to use JIT provisioning + +[cols="3,4", options="header"] +|===== +|Scenario|Recommended approach + +|Embedded analytics, per-tenant Orgs, dynamic entitlements +|Trusted authentication with provisioning inside the token request service + +|Embedded analytics, simple setup, entitlements fully known at login +|Trusted authentication with `auto_create: true` on `/api/rest/2.0/auth/token/full`, accepting the full group replace on each login + +|Entitlements set once at first login only +|`/api/rest/2.0/auth/token/custom` with `auto_create: true`, plus periodic reconciliation + +|Row-level security driven by user attributes +|`/api/rest/2.0/auth/token/custom` with ABAC variables + +|Direct SSO login (non-embedded) with autocreated users +|Security Assertion Markup Language (SAML) or OpenID Connect (OIDC) JIT with attribute mapping. A ThoughtSpot Support ticket is required for group mapping. +|===== + +== When not to use JIT provisioning + +JIT provisioning is not the right tool for every lifecycle task. Do not rely on JIT for the following: + +* *Deprovisioning*: JIT creates and updates users, but it does not remove them. Define a deprovisioning process by pairing JIT with System for Cross-domain Identity Management (SCIM) or periodic REST API reconciliation to deactivate or remove users who no longer require access. +* *Role creation*: Roles must exist before they can be referenced in `/api/rest/2.0/groups/create` or `/api/rest/2.0/groups/{group_identifier}/update` calls. Pre-create the role catalog, and never attempt role creation inline in the login path. +* *Non-default user or group properties*: Autocreated users and groups are created with default options. If the defaults are not acceptable, use the explicit `/users` and `/groups` endpoints instead. +* *Complex or bulk variable updates*: Use the dedicated variable values update REST API outside the login path. +* *An incomplete group list*: With `/api/rest/2.0/auth/token/full`, every login replaces the full group set, so a partial list silently strips access. +* *Dynamic entitlements, per-tenant Org routing, or ABAC on IdP-assertion JIT*: These require trusted authentication. IdP-assertion JIT is best suited for simple scenarios in which users are autocreated on first login. + +== Supported authentication mechanisms + +ThoughtSpot supports two JIT provisioning paths with different capabilities. Decide which path your deployment uses before you design your provisioning logic: + +[cols="2,3,4", options="header"] +|===== +|Path|Mechanism|Capability + +|Trusted authentication (token request) +|Token request service and REST API v2 +|Full control over user creation, Org assignment, group creation and updates, privileges, and RLS variables. + +|IdP assertion (SAML or OIDC) +|IdP claims at login +|Limited: creates a user and adds them to existing groups in existing Orgs. Group mapping requires a ThoughtSpot Support ticket. +|===== + +If your deployment requires dynamic entitlements, per-tenant Org routing, or ABAC variables, use trusted authentication. For IdP-assertion configuration details and considerations, see xref:just-in-time-provisioning.adoc[Just-in-time provisioning]. + +You can also use the explicit `/users` and `/groups` REST APIs to create users and groups and assign group membership. These APIs give you full control over every property. For JIT provisioning, however, token-based provisioning is the recommended approach. + +=== Secure the token request service + +All REST API-based JIT operations should live inside your xref:trusted-auth-token-request-service.adoc[token request service], the backend component in the trusted authentication pattern that exchanges your `secret_key` for user tokens. + +* *Isolate credentials.* The token request service requires two sets of credentials: the `secret_key` for token requests, and a service account with administrator privileges for the provisioning REST API calls. Keep both server-side only, and never expose them to the browser or embed code. +* *Scope the service account minimally.* The account needs only enough privilege to create and update users and groups in the target Orgs. Audit what the account actually requires instead of defaulting to full administrator access everywhere. +* *Complete provisioning before requesting the token.* Unless you use `auto_create: true`, the user must exist in ThoughtSpot, in the Org the token is requested for, before a login token can be issued. + +[#use-case-1] +== Use case 1: Dynamic onboarding of a new user + +A user authenticates through SSO for the first time and needs to exist in ThoughtSpot, in the correct Org, before a login token can be issued. + +Three token endpoints support JIT via `auto_create: true`: + +* `/api/rest/2.0/auth/token/full` +* `/api/rest/2.0/auth/token/custom` +* `/api/rest/2.0/auth/token/object` + +Required parameters for JIT creation are `auto_create: true`, plus `display_name` and `email`. With Orgs enabled, pass `org_id` to place the user in the right Org. + +Autocreated users are identical to manually created users except that they have no password; they can only log in via the SSO method. A password can be assigned later via the UI or API if needed. Users and groups are created with default options; if the defaults are not acceptable, use the explicit `/users` and `/groups` endpoints instead. + +=== Best practices + +Recommended practices: + +* Provision the user before requesting the token, or use `auto_create: true` on the token request itself. +* Pass `org_id` explicitly whenever Orgs are enabled. +* Keep the `secret_key` and the administrator service account server-side only, inside the token request service. +* Expect SSO-only login for autocreated users, and assign a password afterwards only if a non-SSO path is genuinely needed. + +Steps to avoid: + +* Don't rely on autocreate when you need non-default user properties. Autocreate applies defaults that may not match your requirements. +* Don't assume the token request is cheap. Token request latency can increase depending on the number and complexity of RLS rules. +* Don't expect JIT to remove users. Creation is in scope, but deprovisioning is not. + +[#use-case-2] +== Use case 2: Dynamic onboarding with group provisioning + +Groups drive content sharing, group-based RLS, roles, and column-level security, so your JIT group logic is effectively your entitlement engine. The token-based mechanism is the recommended path. + +Group behavior differs by endpoint when `auto_create: true` is set: + +[cols="2,4", options="header"] +|===== +|Endpoint|Group behavior with `auto_create: true` + +|`/api/rest/2.0/auth/token/full` +|Full replace of the group list on every token request. + +|`/api/rest/2.0/auth/token/custom` +|Assigns groups only during new user creation; no impact on groups for existing users. +|===== + +Implications: + +* With `/api/rest/2.0/auth/token/full`, your backend becomes the source of truth for group membership on every login. This keeps entitlements synced, but if the group list is ever incomplete, you silently remove the user's access. +* With `/api/rest/2.0/auth/token/custom`, group membership can drift after first login. Pair it with the explicit group update APIs if entitlements change over time. + +The `group_identifiers` parameter is a common pitfall: + +* `group_identifiers: []` (an empty array) strips the user to no groups. +* Omitting `group_identifiers` entirely leaves existing group membership untouched. + +Privileges attach to groups directly, or via roles if RBAC is enabled on the instance. Access to content is granted by sharing to groups or users. Sharing requires the group or user to already exist, so the sequence matters: create, then assign, then share. Autocreated groups grant nothing until you explicitly configure them via `/api/rest/2.0/groups/{group_identifier}/update`. + +=== Multi-Org considerations + +* You can set a user's groups only in the Org that matches the authentication token used for the request. +* If you create a user from the Primary Org, any `group_identifiers` in that request apply only within the Primary Org, even if the user is added to multiple Orgs in the same request. +* Multi-Org group assignment therefore requires per-Org update calls with per-Org tokens. + +=== Best practices + +Recommended practices: + +* Treat group names as stable, code-reviewed identifiers because they double as data entitlements. For more information, see xref:jit-provisioning-best-practices.adoc#use-case-3[Use case 3]. +* Pre-create groups with the right privileges, roles, and sharing, so that JIT logic only assigns membership and never creates groups implicitly. +* Pre-create the role catalog before JIT go-live; roles must exist before they can be referenced. +* Use `group_name`, not `display_name`, in group lists. +* Validate group names against a known-good allowlist before passing them, and monitor for unexpected group creation. +* Choose the endpoint deliberately: `/api/rest/2.0/auth/token/full` for continuous sync, `/api/rest/2.0/auth/token/custom` for create-time-only assignment plus periodic reconciliation. +* For multi-Org deployments, account for per-Org group assignment via per-Org tokens. + +Steps to avoid: + +* Don't send an empty `group_identifiers` array unless you genuinely intend to remove all group-based access. +* Don't pass unvalidated group names. A non-matching name creates a new group with identical `group_name` and `display_name` and no privileges, roles, or access. Typos therefore fail silently: the user lands in an empty group and loses the expected access. +* Don't use `/api/rest/2.0/auth/token/full` with a group list that may be partial. +* Don't attempt role creation inline in the login path. +* Don't assume a group set in one Org applies in another. + +[#use-case-3] +== Use case 3: Dynamic onboarding with ABAC and RLS + +Row-level security rules can filter on username, group membership (`ts_groups`), or variable values. Setting variable values is step 4 of the conceptual JIT flow and works only with token authentication. + +* If an RLS rule uses `ts_groups`, group names must exactly match the values in the data warehouse column they filter on. The group name literally is the data entitlement, so a misspelled JIT-created group both grants no ThoughtSpot access and breaks RLS matching. +* For ABAC, pass variable values through the custom token request (`/api/rest/2.0/auth/token/custom`), which supports multiple values per variable. For more information, see xref:abac-via-rls-variables.adoc[ABAC via RLS with variables]. +* For complex or bulk variable updates outside the login path, use the dedicated variable values update REST API. + +=== Best practices + +Recommended practices: + +* Use `/api/rest/2.0/auth/token/custom` when RLS is driven by user attributes; it is the only path that carries ABAC variables. +* Verify that `ts_groups` names exactly match the values in the warehouse column they filter on. +* Set variable values at the user level as part of the login flow, and keep bulk corrections on the dedicated REST API. +* Budget for latency: token request time can increase with the number and complexity of RLS rules. + +Steps to avoid: + +* Don't attempt ABAC variables through IdP-assertion JIT. Only token authentication supports them. +* Don't treat group names as cosmetic once they appear in RLS rules. A typo silently removes data access as well as ThoughtSpot access. +* Don't run complex or bulk variable updates inside the login path. + +[#combine-use-cases] +== Combining the use cases + +[NOTE] +==== +The three use cases above are layers of one login flow, not alternatives. A full implementation runs them in sequence inside the token request service: create the user and place them in the target Org (xref:jit-provisioning-best-practices.adoc#use-case-1[Use case 1]), assign group membership (xref:jit-provisioning-best-practices.adoc#use-case-2[Use case 2]), then set RLS or ABAC variable values (xref:jit-provisioning-best-practices.adoc#use-case-3[Use case 3]). +==== + +Two constraints govern how the layers combine: + +* *Endpoint choice is made once, for all three layers.* `/api/rest/2.0/auth/token/custom` is the only endpoint that carries ABAC variables, but it assigns groups only at user-creation time, so combining Use cases 2 and 3 means group drift must be handled by explicit group-update APIs or periodic reconciliation. `/api/rest/2.0/auth/token/full` keeps groups in sync on every login but does not carry variables. Pick the endpoint from the use case that constrains you most, then compensate for the other. +* *Org scoping applies across all three layers.* Group assignment and variable values are scoped to the Org matching the authentication token used for the request. In multi-Org deployments, layering Use cases 2 and 3 onto Use case 1 therefore requires per-Org calls with per-Org tokens, even when the user was created in a single request. + +Sequence matters throughout: create, then assign, then share. Groups and roles must already exist with the right privileges, and sharing requires the group or user to exist first. The only work JIT should do at login is assignment, not definition. + +== Operational checklist + +Before enabling JIT provisioning in production, verify the following: + +* The token request service holds the `secret_key` and administrator service account credentials server-side only. +* Token request latency is measured. It can increase depending on the number and complexity of RLS rules. +* Groups and roles are pre-created with the correct privileges before JIT go-live. +* Group names are validated against an allowlist before any token or update call, because typos silently create empty groups. +* The token endpoint is chosen deliberately: `/api/rest/2.0/auth/token/custom` assigns groups at creation time only, while `/api/rest/2.0/auth/token/full` performs a full group replace on each login. +* Multi-Org deployments account for per-Org group assignment via per-Org tokens. +* For SAML or OIDC JIT, the Support ticket for group mapping is raised early in the project timeline. +* RLS `ts_groups` names are verified to exactly match warehouse column values. +* A deprovisioning process is defined; pair JIT with SCIM or periodic API reconciliation. +* Token-based provisioning is used for JIT. The explicit `/users` and `/groups` REST APIs are reserved for cases that need full control over user and group properties. + +== Related information + +* xref:just-in-time-provisioning.adoc[Just-in-time provisioning] +* xref:trusted-auth-token-request-service.adoc[Token request service] +* xref:abac-via-rls-variables.adoc[ABAC via RLS with variables] +* xref:api-user-management.adoc[User management via REST API] \ No newline at end of file diff --git a/modules/ROOT/pages/just-in-time-provisioning.adoc b/modules/ROOT/pages/just-in-time-provisioning.adoc index db73a3fca..3c406d225 100644 --- a/modules/ROOT/pages/just-in-time-provisioning.adoc +++ b/modules/ROOT/pages/just-in-time-provisioning.adoc @@ -8,48 +8,37 @@ 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? - .. If the user does not exist, create the user. - . Is the user in this Org? - .. 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. - +[TIP] +==== +For production deployment recommendations, including a decision guide, security guidance, and an operational checklist, see xref:jit-provisioning-best-practices.adoc[JIT provisioning best practices]. +==== == 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 *xref:trusted-auth-token-request-service.adoc[token request service]* in the trusted authentication pattern. +* User creation or adding to Org +* Group assignment for users +** Group creation and updates +* RLS variable values for user -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. +These can all be implemented as part of the *xref:trusted-auth-token-request-service.adoc[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. +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: -. `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fupdate-user[/users/{user-identifier}/update]` in the target Org with the `operation: REPLACE` option. +. link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fupdate-user[/users/{user-identifier}/update] in the target Org with the `operation: REPLACE` option. .. 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`. .. 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). .. 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. +Alternatively, check the user's state within an Org via `/users/search` first, avoiding unnecessary update and error-handling steps. Any additional changes to the Groups themselves can be managed with other REST APIs described in the following section. @@ -58,7 +47,7 @@ There are several token request endpoints, each with an `autocreate=true` option * `/api/rest/2.0/auth/token/full` * `/api/rest/2.0/auth/token/custom` -* `/api/rest/2.0/auth/token/object` +//* `/api/rest/2.0/auth/token/object` To be deprecated [NOTE] ==== @@ -70,7 +59,7 @@ The following details must be included in a request with `autocreate=true` to al * 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. +* Specify the `group_identifiers` parameter only if you want to enable JIT group assignment. Passing `group_identifiers: []` sets the user to be assigned to *no groups*, while excluding the `group_identifiers` parameter altogether leaves 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. @@ -78,7 +67,7 @@ Users created via `autocreate=true` are identical to users created manually or v 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: +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] ---- @@ -90,7 +79,7 @@ The `/users/{user-identifier}/update` API can update a user's Group membership w } ---- -You can also choose `"operation" : "REPLACE"` to reset the entire set of Groups for a user. +You can also choose `"operation": "REPLACE"` to reset the entire set of Groups for a user. [NOTE] ==== @@ -98,7 +87,7 @@ You cannot set a user's groups in an Org other than the REST API request's auth ==== === 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 `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fupdate-user-group[/groups/{group_identifier}/update]` REST API endpoint. +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 link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fupdate-user-group[/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: @@ -115,7 +104,7 @@ Similarly to the user update endpoint, you can choose between three operations: === 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/full` does 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`. @@ -124,7 +113,7 @@ If a group name is provided that does not match any existing group name, a new g 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 `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fupdate-user-group[/groups/{group_identifier}/update]` endpoint. +However, you can assign privileges or make any other adjustment to the new groups via REST API link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fupdate-user-group[/groups/{group_identifier}/update] endpoint. == Group privileges and access control via REST APIs @@ -137,7 +126,7 @@ Access control in ThoughtSpot is based on *link:https://developers.thoughtspot.c 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. +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__. @@ -146,23 +135,17 @@ Variable values are used as part of the xref:abac_rls-variables.adoc[ABAC via RL There is also a direct xref:variables.adoc#_assign_or_update_variable_values[variable values update REST API] for more complex or bulk updates. - - - //// === JIT provisioning and authentication token generation via REST APIs Both REST API V1 and V2 tokens support just-in-time provisioning of users. === REST API v2 (Recommended) -//// -//// === REST API v1 The `/tspublic/v1/session/auth/token` API endpoint can provision a new user by setting the `autocreate` property to `true`. For more information, see xref:session-api.adoc#session-authToken[Session API]. -//// -//// + == Org IDs If the Orgs feature is enabled on your instance, you do need to specify the Org ID when creating a user. Org IDs are integers that are created automatically when a cluster administrator creates an Org. Administrators can get the Org IDs configured on a ThoughtSpot instance via `/tspublic/v1/org/search` or `/api/rest/2.0/orgs/search` API endpoint. @@ -172,14 +155,26 @@ For more information about Org APIs, see xref:org-manage-api.adoc[Org administra //// == 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. +=== Considerations for IdP-assertion provisioning + +* The IdP assertion can create a user and add them to existing groups within existing Orgs. It cannot create groups or Orgs. Any REST API provisioning must happen before the assertion arrives. +* JIT group assignment (group mapping) for SAML requires contacting ThoughtSpot Support; it is not self-serve. Plan lead time for this in your rollout. +* JIT group synchronization for OIDC also requires a Support ticket to enable. +* With per-Org IdP configuration (IAMv2): +** Group and Org claims referencing the IdP's authorized Org are processed. +** Claims referencing other Orgs are dropped. They result in no access and no provisioning. +** Group claims without an Org suffix are automatically scoped to the authorized Org. +** Login through a per-Org IdP also reconciles the user's existing Org memberships against the claims. Factor this into your deprovisioning expectations. + == SAML SSO authentication + [NOTE] ==== -// SOURCE: SCAL-291968 — OIDCClient.java, OrgUtils.java 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 xref:configure-saml.adoc#per-org-idp-org-isolation[Org isolation for per-org IdP authentication]. @@ -194,6 +189,26 @@ For JIT group assignment to link:https://docs.thoughtspot.com/cloud/latest/saml- == OIDC authentication OIDC SSO can be configured for JIT user creation, as the necessary properties should already be link:https://docs.thoughtspot.com/cloud/latest/oidc-configure#configure-ts[configured as part of the claims, window=_blank]. -JIT group assignment xref:configure-oidc.adoc#group-synchronization[can be enabled for OIDC via a support ticket]. +JIT group assignment xref:configure-oidc.adoc#_group_synchronization[can be enabled for OIDC via a support ticket]. + +== Troubleshooting issues + +=== Duplicate user account created after username change + +*Possible cause:* A user's username was changed via the REST API, but the IdP still sends the original username in the assertion. With JIT enabled, ThoughtSpot creates a new account for the unrecognized username. + +*Resolution:* Update the username in the IdP to match the new ThoughtSpot username. If JIT is disabled, the user cannot log in until the IdP username matches. + +=== Groups created via autocreate have no permissions + +*Possible cause:* Groups created by `autocreate=true` are default groups with no privileges, roles, or shared content. + +*Resolution:* After a group is auto-created, use the `/groups/{group_identifier}/update` REST API to assign privileges, roles, and sharing. Alternatively, pre-create groups before users are provisioned. + +=== User provisioned into wrong Org + +*Possible cause:* The `org_id` parameter was not specified or was set incorrectly in the token request, or the user was created from the Primary Org without being added to the target Org. + +*Resolution:* Verify the `org_id` in the token request matches the target Org. Use the `/orgs/search` endpoint to retrieve available Org IDs. To move a user to a different Org, use the `/users/{user-identifier}/update` endpoint from the Primary Org.