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.

Summary of requirements

  • IdP account

  • Local identity store

  • IdP claims - mapping users

  • Authentication context

IdP account

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 OpenID Connect.

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, email claim to map IdP identities to Tableau Server user accounts. If you are not using Google as an IdP, then work with your IdP to determine the claim for which you should configure Tableau Server.

Default: using email claim to map users

By default, the user's user name in Tableau Server must match the email claim in the IdP ID token. Therefore, in the default configuration, you must use email addresses (also referred to as UPN) as the username in Tableau Server. If you use Google as the IdP, the user name in Tableau Serverr must be the user's Gmailaddress (alice@gmail.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 email claim to a user account on Tableau Server. In this scenario, the email claim in the IdP might be alice@example.com, 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 email claim, but not the domain portions.

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 (example.com and tableau.com). If two users with the same first name, but different user accounts (alice@tableau.com and alice@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 OpenID Connect, 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.

The OpenID 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 in Tableau Server. By default, Tableau will use the IdP claim, email, to identify the Tableau user. Tableau will then update that user's record with the 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 kwilliams.

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>.

Changing the sub claim

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>.

Where arbitraryClaim is the name of the IdP claim that you want to use as the replacement for the sub claim.

Authentication context

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.essential_acr_values and vizportal.openid.voluntary_acr_values configuration keys. For more information, see tsm configuration set Options.

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