--- schema_version: "1" id: 92e72e8b4f5198110bac243634ebf2db4d19fb7ad9b0c038be86fcfeb72b221f title: Requirements for Using OpenID Connect collection: tableau version: next locale: en-gb portal_url: https://docs.salesforce.com/tableau/next/en-gb/server-linux/openid_auth_requirements.md canonical_url: https://help.tableau.com/v0.0/server-linux/en-gb/openid_auth_requirements.htm source_site: help.tableau.com content_type: documentation content_hash: 888ce6e83203f8fd84dc5cc708bd23a2ddba6edeb60f989a749bace8d2f7e4f3 description: Understand the requirements for using OpenID Connect with Tableau Server. --- [Skip to main content](#main-content) # 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](https://help.tableau.com/current/api/rest_api/en-us/REST/TAG/index.html#operation/AuthnService_UpdateAuthConfiguration) 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](https://help.tableau.com/v0.0/server-linux/en-gb/identity_pools.htm), 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](https://help.tableau.com/v0.0/server-linux/en-gb/openid_auth.htm#Authenti). 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 username 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 username in Tableau Server 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 username, 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 usernames 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 organisation, 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 ](https://help.tableau.com/v0.0/server-linux/en-gb/cli_authentication_tsm.htm#TSMOIDC). 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](https://help.tableau.com/v0.0/server-linux/en-gb/openid_auth.htm#Authenti), 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 organisations, 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`. ![A form to add a new user on Tableau Server.](/tableau/next/en-gb/server-linux/en-gb/Img/users_add_srvruser.png) 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 ](https://help.tableau.com/v0.0/server-linux/en-gb/cli_authentication_tsm.htm#TSMOIDC). ### 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 ](https://help.tableau.com/v0.0/server-linux/en-gb/cli_authentication_tsm.htm#TSMOIDC). 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](https://help.tableau.com/v0.0/server-linux/en-gb/cli_configuration-set_tsm.htm).