Identity Pools Methods


Identity pools are an identity management tool that uses provisioning and authentication information to enable user access to Tableau Server. Identity pools enable a more centralized and flexible identity management workflow. For more information, see Provision and Authenticate Users Using Identity Pools in the Tableau Server Help.

The identity pools methods allow you to:

  1. Provision users by creating a new local identity store instance. Note: Skip this step to use an existing local identity store or the external identity store you configured in TSM during Tableau Server setup.

  2. Set up an authentication method to authenticate your users to Tableau Server using OpenID Connect (OIDC).

  3. Create an identity pool that uses the identity store and authentication method you configured.

  4. Add users to an identity pool using the Add User to Identity Pool endpoint using the Tableau REST API.

Refer to the Tableau Server Help for testing, managing, and troubleshooting identity pools.

Note: Identity pools do not replace the user provisioning and authentication configurations you made during Tableau Server setup. The purpose of identity pools is to complement and support additional user provisioning and authentication options you might need in your organization.

Prerequisites

Before getting started with identity pools, the following requirements must be met:

  • Integration with an OIDC identity provider (IdP), such as Okta, is already configured

  • You are running Tableau Server 2023.1 or later

  • You have performed the identity migration if you are running Tableau Server after upgrading from version 2021.4 or earlier

  • You have performed the steps described at Step 1: Configure Tableau Server and establish a session in the Tableau Server Help

You can use the Identity Pools Postman collection in the Salesforce Developer's Postman workspace to learn about, develop, and test the methods described.

This functionality relates to the concepts and procedures described in the Set Up and Manage Identity Pools topic in the Tableau Server Help.

Add User to Identity Pool

Add a user to a specified identity pool.

This enables the user to sign in to Tableau Server using the specified identity pool. This method is not available for Tableau Cloud.

For more information about identity pools, see Provision and Authenticate Users Using Identity Pools(Link opens in a new window).

URI

POST /api/api-version/sites/site-id/users/identityPool

Parameter Values

api-version The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id The ID of the site that is associated with the user you want to add to the identity pool.

Request Body

<tsRequest>
   <user
	name="user-name"
	siteRole="site-role"
	id="user-id"
	authSetting="authentication-configuration"
	identityPoolUuid="idpool-uuid"
	identityUuid="identity-uuid" />
</tsRequest>

Attribute Values

user-name

The name of the user to add.

site-role

Site role of the user. You can use one of the following values:

  • Creator
  • Explorer
  • ExplorerCanPublish
  • ServerAdministrator
  • SiteAdministratorExplorer
  • SiteAdministratorCreator
  • Unlicensed
  • ReadOnly
  • Viewer
user-id Required. The ID (not name) of the user to add. You can get the user ID by calling Get Users on Site.
authentication-configuration The authentication configuration instance configured for the identity pool you want to add the user to. You can get the authentication configuration instance by calling List Authentication Configurations(Link opens in a new window) endpoint in Tableau REST OpenAPI.
idpool-uuid The ID of the identity pool that you wan to add the user to. You can get the identity pool ID by calling the List Identity Pools(Link opens in a new window) endpoint in the Tableau REST OpenAPI.
identity-uuid The identifier for the user you want to add. Identifiers are only used for identity matching purposes. For more information about identifiers, see Usernames and Identifiers in Tableau(Link opens in a new window) in the Tableau Server Help.

Permissions

This method can only be called by Tableau Server administrators.

Response Code

200

Response Body

Example response: 

<tsResponse>
  <user
	identityPoolUuid="df47cf24-5ed3-11ed-9b6a-0242ac12000"
	id="7ad8f89e-c2a1-44b4-9413-ac8a62286a7a"
	name="Michele Kim" />
</tsResponse>

Version

Version 3.19 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.
429 429001 User conflict The specified user is already a member of the identity pool.
429 429002 Can't add user There was a problem and the user couldn't be added to the identity pool.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/identityPool" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-idpool.xml

  • MY-SERVER is the name or IP address of your server.
  • 9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d is the ID of the site, as returned by a previous call to Sign In.
  • 12ab34cd56ef78ab90cd12ef34ab56cd is the credentials token returned by a previous call to Sign In.

Content of add-user-to-idpool.xml: 

<tsRequest>
  <user id="7ad8f89e-c2a1-44b4-9413-ac8a62286a7a" />
</tsRequest>

Example response:

<?xml version="1.0" encoding="UTF-8" ?>
<tsResponse version-and-namespace-settings>
  <user identityPoolUuid="7b54b6a8-6095-11ed-9b6a-0242ac120002"
     id="7ad8f89e-c2a1-44b4-9413-ac8a62286a7a" name="Michele Kim" />
</tsResponse>

Remove User from Identity Pool

Remove a user from a specified identity pool.

This method is not available for Tableau Cloud.

Version: Available in API 3.19 and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Tableau Server administrators only. Permissions Overview(Link opens in a new window)

JWT Access Scope: Not available. Access Scopes Overview: Server(Link opens in a new window)

URI

DELETE /api/api-version/sites/site-id/users/user-id/identityPool/idpool-uuid

Parameter Values

api-version The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id The ID of the site that is associated with the user you want to remove from the identity pool.
user-id The ID of the user to remove from the identity pool.
idpool-uuid The ID of the identity pool to remove the user from. You can get the identity pool ID by calling the List Identity Pools(Link opens in a new window) endpoint in the Tableau REST OpenAPI.

Request Body

None

cURL Request Example

curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/7ad8f89e-c2a1-44b4-9413-ac8a62286a7a/identityPool/" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

  • MY-SERVER is the name or IP address of your server.
  • 9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d is the ID of the site, as returned by a previous call to Sign In.
  • 7ad8f89e-c2a1-44b4-9413-ac8a62286a7a is the ID of the user to remove.
  • df47cf24-5ed3-11ed-9b6a-0242ac12000 is the ID of the identity pool.
  • 12ab34cd56ef78ab90cd12ef34ab56cd is the credentials token returned by a previous call to Sign In.

The response contains no body (data) if the user is successfully removed from the identity pool. The HTTP response code is 204 if the delete operation succeeded.

Permissions

This method can only be called by Tableau Server administrators.

Response Code

204

Response Body

None

Version

Version 3.19 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not DELETE.
429 429003 Can't remove user There was a problem and the user couldn't be removed from the identity pool.

For more information, see Handling Errors.

Delete Authentication Configuration

Delete an authentication instance.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

DELETE {server}/api/-/authn-service/auth-configurations/{id}

view details

Delete Identity Pool

Delete an identity pool.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

DELETE {server}/api/-/authn-service/identity-pools/{uuid}

view details

Delete Identity Store

Delete an identity store.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

DELETE {server}/api/-/authn-service/identity-stores/{id}

view details

Get Identity Pool

Get information about an identity pool.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

GET {server}/api/-/authn-service/identity-pools/{uuid}

view details

List Authentication Configurations

List information about all authentication instances.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

GET {server}/api/-/authn-service/auth-configurations

view details

List Identity Pools

List all identity pools.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

GET {server}/api/-/authn-service/identity-pools

view details

List Identity Stores

List information about all identity store instances used to provision users.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

GET {server}/api/-/authn-service/identity-stores

view details

Create Authentication Configuration

Create an instance of OpenID Connect (OIDC) authentication.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

POST {server}/api/-/authn-service/auth-configurations

view details

Create Identity Pool

Create an identity pool.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

POST {server}/api/-/authn-service/identity-pools

view details

Configure Identity Store

Configure a new local identity store to provision users.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

POST {server}/api/-/authn-service/identity-stores

view details

Update Authentication Configuration

Update an authentication instance.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

PUT {server}/api/-/authn-service/auth-configurations/{id}

view details

Update Identity Pool

Update information about an identity pool.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

PUT {server}/api/-/authn-service/identity-pools/{uuid}

view details


Back to top
Thanks for your feedback!Your feedback has been successfully submitted. Thank you!