Mapping a Client Certificate to a User During Mutual Authentication
When you use mutual (two-way) SSL authentication, the client presents its certificate to Tableau Server as part of the authentication process. Tableau Server then maps user information in the client certificate to a known user identity. The strategy that Tableau Server uses to perform client mapping depends on the content of your organisation’s client certificates.
This topic discusses the ways information in a client certificate can map to a user identity, and how to change the way Tableau Server performs that mapping. To understand how the mapping happens and whether you need to change it, you must know how client certificates are structured in your organisation.
User-name mapping options
Tableau Server uses one of the following approaches to map a client certificate to a user identity:
Active Directory. If Tableau Server is configured to use Active Directory for user authentication, when Tableau Server receives a client certificate, it passes the certificate to Active Directory, which maps the certificate to an Active Directory identity. Any explicit user name information in the certificate is ignored.
Note: This approach requires client certificates to be published for the user accounts in Active Directory.
User principal name (UPN). A client certificate can be configured to store the user name in the user principal name field. Tableau Server reads the UPN value and maps it to a user in Active Directory or to a local user.
Common name (CN). A client certificate can be configured to store the user name in the common name field of the certificate. Tableau Server reads the CN value and maps it to a user in Active Directory or to a local user.
If you configure the server for Active Directory authentication and UPN or CN user-name mapping, put the user name in one of the following formats:
username, domain/username or username@domain.
For example: jsmith, example.org/jsmith or jsmith@example.org.
If the server uses local authentication, the format of the name in the UPN or CN fields is not predetermined, but the name in the field must match a user name on the server.
Change the certificate mapping
You use the tsm authentication mutual-ssl <commands> commands to map a client certificate to a user identity in Tableau Server:
tsm authentication mutual-ssl configure -m <value>
Possible values are ldap for Active Directory mapping, upn for UPN mapping, or cn for CN mapping.
When you first install and configure Tableau Server, the server sets the default user-name mapping to match the server’s authentication type:
If the server is configured to use Active Directory, it also uses Active Directory to map the certificate to the user identity.
If the server is configured to use local authentication, the server gets the user-name value from the UPN field in the certificate.
If the default behaviour for how Tableau Server maps a user name to an identity is not correct for your server configuration, run the following set of commands to change the mapping to use the CN value:
tsm authentication mutual-ssl configure -m cn
tsm pending-changes apply
If the pending changes require a server restart, the pending-changes apply command will display a prompt to let you know a restart will occur. This prompt displays even if the server is stopped, but in that case, there is no restart. You can suppress the prompt using the --ignore-prompt option, but this does not change the restart behaviour. If the changes do not require a restart, the changes are applied without a prompt. For more information, see tsm pending-changes apply.
Address user-name mapping ambiguity in multi-domain organisations
In some circumstances, the user name in a certificate’s UPN or CN field can be ambiguous. This ambiguity can lead to unexpected results when the user name is mapped to a user identity on the server.
For example, if Tableau Server is presented with a user name that does not include a domain, the server maps the user name to an identity using the default domain. This can cause an incorrect user-name mapping, potentially assigning a user a different user’s identity and permissions.
This can occur particularly in environments where the following conditions apply:
Your organisation supports multiple Active Directory domains.
The server is configured to use Active Directory authentication.
The server is configured to use UPN or CN mapping.
Some users have the same user name but different domains. For example,
jsmith@example.organdjsmith@example.com.The user name in the certificate’s UPN or CN fields does not include the domain as part of the user name – for example, it shows
jsmith.
To avoid incorrect user-name mapping, make sure the client certificates include fully qualified user names with the domain, using the format jsmith@example.org or example.org/jsmith.