Requirements for Using OpenID Connect
This topic describes the requirements to use OpenID Connect with Tableau Server.
Note: The TSM authentication configuration commands apply only to OIDC authentication configured in TSM during Tableau Server setup. To make OIDC authentication configuration changes for identity pools, you can use the Update Authentication Configuration(Link opens in a new window) endpoint using Tableau REST OpenAPI.
You must have access to an identity provider (IdP) that supports the OpenID Connect (OIDC) protocol. You must also have an account with the IdP. OpenID Connect is supported by many identity providers. The OIDC protocol is an open and flexible standard, and as such, not all implementations of the standard are identical. As you configure Tableau Server for OIDC, work with your IdP.
The Google IdP implementation has been extensively tested with Tableau Server and is the model IdP for the configuration documented in these topics.
Local identity store
To use OpenID Connect on Tableau Server, one of the following must be true:
- If configuring OIDC in TSM during Tableau Server setup, Tableau Server must be configured to use a local identity store. The server must be configured so that you explicitly create users on the Tableau Server, rather than importing them from an external directory such as Active Directory. Managing users with an external identity store is not supported with OpenID.
- If configuring OIDC using identity pools(Link opens in a new window), OIDC can be configured with 1) a local identity store or 2) AD or LDAP is the identity store configured in TSM during Tableau Server setup.
IdP claims: mapping users
To sign in successfully to Tableau Server, a given user must be provisioned in OpenID and then mapped to a user account on Tableau Server. OpenID uses a method that relies on claims to share user account attributes with other applications. Claims include user account attributes such as email, phone number, given name, etc. To understand how Tableau Server maps IdP claims to user accounts, see Authentication overview.
Tableau Server relies on the IdP claims to map user accounts from the IdP to those hosted on Tableau Server. By default, Tableau Server expects the IdP to pass the email claim. Depending on your IdP, you may need to configure Tableau Server to use a different IdP claim.
If you are using Google as an IdP, then use the default,
By default, the user's user name in Tableau Server must match the
email@example.com). Using a complete email address helps to guarantee the uniqueness of the user name in Tableau Server, even when two users have the same email but are on different email hosts.
Note: When you create a user identity in Tableau Server, you specify a user name, password, and optionally an email address. For using OpenID Connect in the default configuration, the user name (expressed as an email address) is the value that must match the user's name in the IdP. The optional email address in the Tableau Server user identity is not used for OpenID authentication.
Ignoring the domain name
You can configure Tableau to ignore the domain portion of an email address when matching the IdP
firstname.lastname@example.org, but this will match a user named
alice in Tableau Server. Ignoring the domain name might be useful if you already have users defined in Tableau Server that match the user names portion of the
Important: We do not recommend ignoring the user domain name without taking precautions. Specifically, verify that user names are unique across the configured domains that you've created in your IdP.
Setting Tableau Server to ignore the user domain name has the potential to result in unintended user log on. Consider the case where your IdP has been configured for multiple domains (
tableau.com). If two users with the same first name, but different user accounts (
email@example.com) are in your organization, then the first one to complete the OpenID provisioning sequence will claim the
sub mapping in the IdP. If the wrong user is mapped, then the other user will be unable to log on until the associated
sub value is reset.
To configure Tableau Server to ignore domain names in user names from the IdP, set
tsm authentication openid configure --ignore-domain to
true. For more information, see tsm authentication openid <commands>.
When you change the tsm authentication openid configure
--ignore-domain option to ignore the domain in user names, all user names in Tableau Server must have a domain name.
Using custom claims to map users
As referenced in Authentication overview, the
sub claim is often included in IdP claims. Typically, the
sub claim is a unique string that identifies a given user account. The benefit of using a
sub claim is that it will not change, even if you or another admin updates other user attributes or IdP claims (email, phone number, etc) associated with that account. By default, Tableau Server identifies and verifies OpenID users according to the
sub claim in the IdP ID token.
sub claim value must be mapped to the corresponding user in Tableau Server. Since the
sub claim is an arbitrary string, a different claim is used to associate accounts during the first sign-in session. The first time a user signs in to Tableau Server with OpenID, Tableau will match the OpenID user account to a corresponding user account on Tableau. By default, Tableau will use the IdP claim,
sub claim from OpenID. Since the ID token always includes the
sub claim along with other claims, on subsequent sessions, Tableau will identify that user with the
sub claim only.
For some organizations, mapping user names with the email address is not reliable or not supported by the IdP. Beginning with Tableau Server 10.2, you can map user accounts from any arbitrary IdP claim to the Tableau Server username.
The IdP claim you are using must map exactly to a corresponding Tableau Server username. In the example below, the username is
To change the IdP claim that is used to map identity on Tableau Server, use the
tsm authentication openid map-claims --user-name command. For more information, see tsm authentication openid <commands>.
As described above, the
sub claim is the identifier that Tableau Server uses to identify users after the initial mapping session. The
sub claim is written to the corresponding user account in Tableau Server. If your IdP does not provide a
sub claim, then you can specify an arbitrary claim to use instead. Like
sub, the claim value you specify must be unique and should not change when other user claims are updated.
To specify a different IdP claim for default sub claim, use the use the
tsm authentication openid map-claims --id command. For more information, see tsm authentication openid <commands>.
arbitraryClaim is the name of the IdP claim that you want to use as the replacement for the
If your OpenID Connect IdP requires a specific authentication context, you can specify a list of essential and voluntary ACR values using the
vizportal.openid.voluntary_acr_values configuration keys. For more information, see tsm configuration set Options.