Personal Access Tokens

Personal access tokens (PATs) provide you and your Tableau Server users the ability to create long-lived authentication tokens. PATs enable you and your users to sign in to Tableau REST API without requiring hard-coded credentials (i.e., username and password) or interactive sign in. For more information about using PATs with Tableau REST API, see Signing In and Out (Authentication)(Link opens in a new window) in the Tableau REST API Help.

We recommend creating PATs for automated scripts and tasks that are created with the Tableau REST API:

• Improve security: Personal access tokens reduce risk in the event credentials are compromised. In the case where Tableau Server uses Active Directory or LDAP as an identity store, you can reduce the impact of credential compromise by using a personal access token for automated tasks. If a token gets compromised or is used in automation that is failing or posing a risk, you can just revoke the token. You do not need to rotate or revoke the user's credentials.

• Audit and track: As an administrator, you can review Tableau Server logs to track when a token is used, what sessions are created from that token, and the actions that are performed in those sessions. You can also determine if a session and the related tasks were performed from a session that was generated from a token or from an interactive signin.

• Manage automation: A token can be created for each script or task that is run. This allows you to silo and review automation tasks across your organization. Additionally, by using tokens then password resets or metadata changes (username, email, etc.) on user accounts will not disrupt automation as it would when credentials are hard-coded into the scripts.

Understand personal access tokens

When a personal access token (PAT) is created, it is hashed then stored in the repository. After the PAT is hashed and stored, the PAT secret is shown once to the user and then no longer accessible after the users dismisses the dialog. Therefore, users are instructed to copy the PAT to a safe place and to handle it as they would a password. When the PAT is used at run-time, Tableau Server compares the PAT presented by the user to the hashed value stored in the repository. If a match is made, then an authenticated session is started.

In the context of authorization, the Tableau Server session that is authenticated with a PAT has the same access and privileges as the PAT owner.

Note: Users can't request concurrent Tableau Server sessions with a PAT. Signing in again with the same PAT, whether at the same site or a different site, will terminate the previous session and result in an authentication error.

Server administrator impersonation

Beginning with version 2021.1, you can enable Tableau Server PAT impersonation. In this scenario, PATs that are created by server administrators can be used for user impersonation(Link opens in a new window) when using the Tableau REST API. Impersonation is useful in scenarios where you are embedding end-user-specific Tableau content within your application. Specifically, impersonation PATs allow you to build applications that query as a given user and retrieve content that the user is authorized for within Tableau Server, without hard-coding any credentials.

For more information, see Impersonating a User(Link opens in a new window) Tableau REST API Help.

Enable Tableau Server to accept personal access tokens during impersonation sign-in requests

By default, Tableau Server does not allow impersonation for server administrator PATs. You must enable the server-wide setting by running the following commands.

tsm authentication pat-impersonation enable [global options]

tsm pending-changes apply

Important: After you have run the commands, all PATs created by server administrators (including preexisting PATs) can be used for impersonation. To bulk-revoke all existing server administrator PATs, you can post the DELETE /api/{api-version}/auth/serverAdminAccessTokens URI. For more information, see Impersonating a User(Link opens in a new window) in the Tableau REST API Help.

Create personal access tokens

Users must create their own PATs. Administrators cannot create PATs for users.

Users with accounts on Tableau Server can create, manage, and revoke personal access tokens (PATs) on the My Account Settings page. See ManageYour Account Settings(Link opens in a new window) in the Tableau User Help for more information.

Note: A user can have up to 10 PATs.

Change personal access tokens expiry

Personal access tokens (PATs) expire if they are not used after 15 consecutive days. If they are used more frequently than every 15 days, PATs expire after one year. After a year, new PATs must be created. Expired PATs will not display on the My Account Settings page.

You can change PATs expiration period by using the refresh_token.absolute_expiry_in_seconds option with the tsm configuration set command.

Revoke a personal access token

As an administrator, you can also revoke a user's PAT. A user can also revoke their own personal access tokens (PATs) on the My Account Settings page using the procedure described in the Manage Your Account(Link opens in a new window) topic in the Tableau User Help.

1. Sign in to Tableau Server as a server or site administrator.

2. Locate the user whose PAT you want to revoke. For more information about navigating Server Admin pages and locating users, see View, Manage, or Remove Users.

3. Click the user's name to open their profile page.

4. On the user's profile page, click the Settings tab.

5. In the Personal Access Tokens section, identify the PAT that you want to revoke and then click Revoke.

6. In the dialog box, click Delete.

Track and monitor personal access token usage

All personal access token (PAT)-related actions are logged in the Tableau Server Application Server (vizportal) service. To locate PAT-related activities, filter log entries containing the string, RefreshTokenService.

A PAT is stored in this format :Token Guid: <TokenID(Guid)>, where the TokenID is a base64 encoded string. The secret value is not included in the logs.

For example:

Token Guid: 49P+CxmARY6A2GHxyvHHAA== (e3d3fe0b-1980-458e-80d8-61f1caf1c700).

The following is an example snippet of two log entries. The first entry shows how a user is mapped to a PAT. The second entry shows a refresh event for the same PAT:

RefreshTokenService - Issued refresh token to the following user: jsmith. Token Guid: 49P+CxmARY6A2GHxyvHHAA== (e3d3fe0b-1980-458e-80d8-61f1caf1c700)
RefreshTokenService - Redeemed refresh token. Token Guid: 49P+CxmARY6A2GHxyvHHAA== (e3d3fe0b-1980-458e-80d8-61f1caf1c700)

To locate key operations, filter log entries containing the string, OAuthController.