Understanding Keytab Requirements

Kerberos authentication relies on credentials that are stored in specially formatted files called keytab files. You may need to generate keytab files for your Tableau Server deployment. This topic describes the keytab files that Tableau Server uses to access various services in a typical organization. You may need to generate keytabs for Tableau Server to integrate into the following services:

  • User authentication (SSO) in Windows Active Directory
  • Data source delegation
  • Operating system
  • Directory service

Important: Beginning in Tableau Server 2021.2.25, 2021.3.24, 2021.4.19, 2022.1.15, 2022.3.7, and 2023.1.3 (or later), ensure keytab files are created with AES-128 or AES-256 ciphers. RC4 and 3DES ciphers are no longer supported. For more information, see "Tableau Server could not authenticate you automatically"(Link opens in a new window) in the Tableau Knowledge Base.

If your organization includes IT professionals who handle identity, authentication, and/or security, then you should work with them to create a plan for generating appropriate keytabs for your Tableau Server deployment.

User authentication (SSO) in Windows Active Directory

If you will be using Active Directory as the identity store for Tableau Server, and you want users to authenticate with Kerberos SSO, then you will need to generate a keytab file for Tableau Server.

Tableau is running on... Need to manually generate a keytab?
Windows in Active Directory domain Yes
Linux in Active Directory domain Yes
Windows or Linux in non-Active Directory environment Kerberos SSO is not a supported scenario.

Follow these recommendations (for Windows and Linux versions of Tableau Server):

  • Create a service account in your directory for Tableau Server.

  • Create a keytab specifically for the Tableau Server service account. Do not reuse the keytab file that the computer account/OS uses to authenticate. You may use the same keytab for Kerberos SSO as you use for the directory authentication in the scenario above.

  • You must create service principal names (SPN) in Active Directory for the Tableau Server service.

  • Use the batch file in the next section to create the SPNs and the keytab file.

  • After you have created the SPNs, upload the keytab file as described in Configure Kerberos.

Batch file: Set SPN and create keytab in Active Directory

You can use a batch file to set the service principal names (SPN) and create a keytab file. These operations are a part of the process to enable Kerberos SSO for Tableau Server (on Windows or Linux) running in Active Directory.

In previous versions of Tableau Server (before 2018.2), the configuration script was generated from the Tableau Server Configuration utility.

To generate a configuration script, copy and paste the following batch file contents into a text file. The batch file creates service principal names (SPN) for Tableau Server and will create a keytab file for the user you specify in the file.

Follow the directions in the file contents. After you have finished customizing the file, save it as a .bat file.

This file must be run in an Active Directory domain by a Domain admin, who will be prompted for the service account password of the account you specify in the file.

The batch file uses the Windows set(Link opens in a new window), setspn(Link opens in a new window), and ktpass(Link opens in a new window) commands.

Note: The batch file below is self-documented. However, if you do not have experience with Kerberos and generating keytab files, we recommend that you read the Microsoft blog post, All you need to know about Keytab files(Link opens in a new window), before proceeding. Environmental details in your organization may require additional configuration of the ktpass command. For example, you must determine what to set for the /cryptoparameter. We recommend specifying a single /crypto value that is required by your KDC. See the Microsoft article, ktpass(Link opens in a new window) for the full list of supported values for the /crypto parameter.

SPN and keytab batch file contents

Beginning in Tableau Server 2022.3, 2022.1.8, 2021.4.12, 2021.3.17, 2021.2.18, 2021.1.20, and 2020.4.23

@echo off
setlocal EnableDelayedExpansion

REM ******* 

REM This script generates the Service Principal Names (SPNs) and keytab files required for 
REM Kerberos SSO with Apache.
REM This script executes set, setspn, and ktpass commands included in any Windows Server 
REM Operating System from 2003 on.
REM Before running this script you must enter configuration information for the setspn and 
REM ktpass commands. 
REM Elements that require your configuration information are enclosed in as such:
REM  ! -- and --!. 
REM After you customize this file, save it as a .bat file, and run on a domain-joined 
REM computer. 
REM This script must be run by a Domain admin.

REM **********

REM The following set command will prompt the domain admin for credentials of the 
REM Tableau Server service account. 
REM This account must be a valid domain user account.
REM If the password contains a literal \" (blackslash - double quote), all backslashes 
REM immediately before the double quote must be
REM duplicated when typed for the password to work, e.g. if password contains 
REM  \" replace with \\", if passwords contains \\" replace with \\\\"

set /p adpass= "Enter password for the Tableau Server service account."
set adpass=!adpass:"=\"!

REM **********

REM The following setspn commands create the SPN in the domain.
REM More information on setspn can be found here: 
REM http://technet.microsoft.com/en-us/library/cc731241(WS.10).aspx  
REM Enter the canonical FQDN and the host names for Tableau Server followed by the  
REM Tableau Server service account name.
REM Use this syntax: HTTP/hostname domain\service_account_name.
REM The example below shows syntax for a computer named "tableau01" in the "example.lan"  
REM domain, with service account, "tab-serv-account":
REM setspn -s HTTP/tableau01 example\tab-serv-account
REM setspn -s HTTP/tableau01.example.lan example\tab-serv-account  
REM DNS and AD are not case sensitive, but the keytab files are.  Verify that host names  
REM match letter case as stored in DNS. 
REM Use Windows Server's DNS Manager utility to verify host name case.

REM **********

echo Creating SPNs...
setspn -s HTTP/!--replace with canonical host name and service account --!
setspn -s HTTP/!--replace with canonical FQDN and service account --!

REM **********

REM The following commands create the keytab file in the same directory where the 
REM bat file is run. More information on ktpass can be found here: 
REM https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/ktpass 
REM Note: keytab files are case-sensitive.
REM The realm following the FQDN should be all uppercase.
REM Syntax is:
REM ktpass /princ HTTP/!--FQDN--!@!--Kerberos_Realm--! /pass !adpass!
REM /pttype KRB5_NTPRINCIPAL /crypto !--cipher--! /out keytabs\kerberos.keytab
REM Best practice: specify the /crypto value that is required by your KDC. 
REM Options for /crypto = {DES-CBC-CRC|DES-CBC-MD5|AES256-SHA1|AES128-SHA1|All}
REM Do not specify /crypto All because it will result in a keytab that contains ciphers that are not supported
REM and cause errors.
REM When using AES256-SHA1 OR AES128-SHA1, the /mapuser option must be included 
REM in the ktpass command to ensure the keytab file is mapped properly to the user. For example:
REM ktpass /princ HTTP/!--FQDN--!@!--Kerberos_Realm--! /pass !adpass! /ptype KRB5_NT_PRINCIPAL /mapuser <domain\username> /crypto AES256-SHA1 /out keytabs\kerberos.keytab
REM The following example shows the ktpass syntax with the example.lan configuration from above:
REM ktpass /princ HTTP/!--FQDN--!@!--Kerberos_Realm--! /pass !adpass! /ptype KRB5_NT_PRINCIPAL /crypto DES-CBC-CRC /out keytabs\kerberos.keytab
					
REM **********

echo Creating Keytab files in %CD%\keytabs
mkdir keytabs
ktpass /princ HTTP/!--FQDN--!@!--Kerberos_Realm--! /pass !adpass! /ptype KRB5_NT_PRINCIPAL /crypto DES-CBC-CRC /out keytabs\kerberos.keytab

For earlier versions of Tableau Server

@echo off
setlocal EnableDelayedExpansion

REM ******* 

REM This script generates the Service Principal Names (SPNs) and keytab files required for 
REM Kerberos SSO with Apache.
REM This script executes set, setspn, and ktpass commands included in any Windows Server 
REM Operating System from 2003 on.
REM Before running this script you must enter configuration information for the setspn and 
REM ktpass commands. 
REM Elements that require your configuration information are enclosed in as such:
REM  ! -- and --!. 
REM After you customize this file, save it as a .bat file, and run on a domain-joined 
REM computer. 
REM This script must be run by a Domain admin.

REM **********

REM The following set command will prompt the domain admin for credentials of the 
REM Tableau Server service account. 
REM This account must be a valid domain user account.
REM If the password contains a literal \" (blackslash - double quote), all backslashes 
REM immediately before the double quote must be
REM duplicated when typed for the password to work, e.g. if password contains 
REM  \" replace with \\", if passwords contains \\" replace with \\\\"

set /p adpass= "Enter password for the Tableau Server service account."
set adpass=!adpass:"=\"!

REM **********

REM The following setspn commands create the SPN in the domain.
REM More information on setspn can be found here: 
REM http://technet.microsoft.com/en-us/library/cc731241(WS.10).aspx  
REM Enter the canonical FQDN and the host names for Tableau Server followed by the  
REM Tableau Server service account name.
REM Use this syntax: HTTP/hostname domain\service_account_name.
REM The example below shows syntax for a computer named "tableau01" in the "example.lan"  
REM domain, with service account, "tab-serv-account":
REM setspn -s HTTP/tableau01 example\tab-serv-account
REM setspn -s HTTP/tableau01.example.lan example\tab-serv-account  
REM DNS and AD are not case sensitive, but the keytab files are.  Verify that host names  
REM match letter case as stored in DNS. 
REM Use Windows Server's DNS Manager utility to verify host name case.

REM **********

echo Creating SPNs...
setspn -s HTTP/!--replace with canonical host name and service account --!
setspn -s HTTP/!--replace with canonical FQDN and service account --!

REM **********

REM The following commands create the keytab file in the same directory where the 
REM bat file is run. More information on ktpass can be found here: 
REM https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/ktpass 
REM Note: keytab files are case-sensitive.
REM The realm following the FQDN should be all uppercase.
REM Syntax is:
REM ktpass /princ HTTP/!--FQDN--!@!--Kerberos_Realm--! /pass !adpass!
REM /pttype KRB5_NTPRINCIPAL /crypto !--cipher--! /out keytabs\kerberos.keytab
REM Best practice: specify the /crypto value that is required by your KDC. 
REM Options for /crypto = {DES-CBC-CRC|DES-CBC-MD5|RC4-HMAC-NT|AES256-SHA1|AES128-SHA1|All}
REM Specifying /crypto All will result in passwords stored with RC4 cipher, which is
REM no longer considered secure.
REM When using AES256-SHA1 OR AES128-SHA1, the /mapuser option must be included 
REM in the ktpass command to ensure the keytab file is mapped properly to the user. For example:
REM ktpass /princ HTTP/!--FQDN--!@!--Kerberos_Realm--! /pass !adpass! /ptype KRB5_NT_PRINCIPAL /mapuser <domain\username> /crypto AES256-SHA1 /out keytabs\kerberos.keytab
REM The following example shows the ktpass syntax with the example.lan configuration from above:
REM ktpass /princ HTTP/!--FQDN--!@!--Kerberos_Realm--! /pass !adpass! /ptype KRB5_NT_PRINCIPAL /crypto DES-CBC-CRC /out keytabs\kerberos.keytab
					
REM **********

echo Creating Keytab files in %CD%\keytabs
mkdir keytabs
ktpass /princ HTTP/!--FQDN--!@!--Kerberos_Realm--! /pass !adpass! /ptype KRB5_NT_PRINCIPAL /crypto DES-CBC-CRC /out keytabs\kerberos.keytab

Operating system

If your organization uses Kerberos for authentication, then the computer where Tableau Server is running must be authenticated with the Kerberos realm in which it's running.

Tableau is running on... Need to manually generate a keytab?
Windows in Active Directory domain No
Linux in Active Directory domain Yes
Windows or Linux in non-Active Directory environment Yes

If you are running Tableau Server on Windows, and the computer is joined to the Active Directory, then you do not need to manage or generate a keytab file for the operating system.

If you are running Tableau Server on Linux in a Kerberos realm (MIT KDC or Active Directory), then you will need to generate a keytab file specifically for the computer operating system. The keytab you create for the computer should be specifically for OS authentication. Do not use the same keytab file for OS authentication that you will be using for the other services described later in this topic.

Directory service

If your organization uses a directory service, such as LDAP or Active Directory, to manage user identity, then Tableau Server requires read-only access to the directory.

Alternatively, you can configure Tableau Server to manage all accounts by installing with a local identity store. In this case, you do not need a keytab.

The following table summarizes keytab requirements:

Tableau is running on... Directory service Need to manually generate a keytab?
Windows in AD domain Active Directory No
Windows LDAP (GSSAPI bind) Yes
Linux Active Directory or LDAP (GSSAPI bind) Yes
Windows or Linux Active Directory or LDAP (Simple bind) No
Windows or Linux Local identity store No keytab required.

If you need to manually generate a keytab for this scenario, then you will use it for GSSAPI bind to the directory. Follow these recommendations:

  • Create a service account in your directory for Tableau Server.

  • Create a keytab specifically for the Tableau Server service account. Do not reuse the keytab file that the computer account/OS uses to authenticate.

  • Upload the keytab file as part of the json configuration of the Tableau Server identity store. See identityStore Entity.

As part of your disaster recovery plan, we recommend keeping a backup of the keytab and conf files in a safe location off of the Tableau Server. The keytab and conf files that you add to Tableau Server will be stored and distributed to other nodes by the Client File Service. However, the files are not stored in a recoverable format. See Tableau Server Client File Service.

Datasource delegation

You can also use Kerberos delegation to access data sources in an Active Directory. In this scenario, users can be authenticated to Tableau Server with any supported authentication mechanism (SAML, local authentication, Kerberos, etc), but can access datasources that are enabled by Kerberos.

Follow these recommendations:

  • The computer account for Tableau Server (Windows or Linux) must be in Active Directory domain.

  • The keytab file that you use for Kerberos delegation can be the same keytab that you use for Kerberos user authentication (SSO).

  • The keytab must be mapped to the service principal for Kerberos delegation in Active Directory.

  • You may use the same keytab for multiple data sources.

For more information, see the following configuration topics:

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