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
If you are using email claim to map IdP identities to Tableau Server user accounts. If you are not using
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 alice@gmail.com)
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.