# Configuring SingleStore for Kerberos Authentication Once you have generated an SPN and a keytab file on the Kerberos KDC server, you can configure SingleStore to allow access for Kerberos-authenticated users. Depending on your SingleStore cluster configuration, the SPN and keytab file may need to be configured on one or many aggregator nodes. For example, if your cluster contains one Master Aggregator and one child aggregator, you must configure both nodes to allow client connections for Kerberos-authenticated users. The following steps describe how to use the SPN and keytab file created earlier. ## Copying the Keytab File to SingleStore A keytab file is a credential that can be used to access network resources, so it is important to consider the security implications of copying it from one location to another. Additionally, since a keytab file is a binary file, it must be transferred using a method that will not corrupt the file. For example, if FTP is configured to transfer as an ASCII file type instead of a binary file type, the keytab file *will* be corrupted. Use a secure file transfer method, such as `scp`, to copy the keytab file from the KDC server to each SingleStore aggregator node. After the keytab file has been copied, its file path on the aggregator node will be used to configure the `memsql.cnf` file in the next step. ## Configuring memsql.cnf Before Kerberos-authenticated users can connect to SingleStore, you must configure each SingleStore aggregator node’s `memsql.cnf` file with two variables: * `gssapi-keytab-path`: The local path to the keytab file that was created on the KDC server and copied to the node. For example: `/path/to/memsql.keytab` * `gssapi-principal-name`: The SPN for SingleStore that was created on the KDC server. For example: `memsql/host.domain.com@DOMAIN.COM` > **📝 Note**: You cannot use the `SET GLOBAL VARIABLE` command when setting these variables. They must be configured in the `memsql.cnf` file on the applicable node using the steps described below. To set these variables in the `memsql.cnf` file: 1. Ensure that the [cluster is stopped](https://docs.singlestore.com/db/v9.1/reference/singlestore-tools-reference/sdb-admin-commands/stop-node.md) before continuing. 2. Open the aggregator node’s `memsql.cnf` file in a text editor ([typical location](https://docs.singlestore.com/db/v9.1/reference/configuration-reference/engine-variables/memsql-cnf.md) for this file). 3. Add the following line to the file anywhere below the `[server]` declaration: ``` [server] ... gssapi-keytab-path = /path/to/memsql.keytab gssapi-principal-name = memsql/host.domain.com@DOMAIN.COM ... ``` 4. Save the file. 5. Repeat this process for each aggregator node’s `memsql.cnf` file. 6. After the `memsql.cnf` file has been updated for each aggregator node in the cluster, [start the cluster](https://docs.singlestore.com/db/v9.1/reference/singlestore-tools-reference/sdb-admin-commands/start-node.md). 7. Verify that the change was successful by executing the following command on one of the affected nodes: ```sql SHOW GLOBAL VARIABLES LIKE 'gssapi%'; ``` ```output +-----------------------+-------------------------------------+ | Variable_name | Value | +-----------------------+-------------------------------------+ | gssapi_keytab_path | /path/to/memsql.keytab | | gssapi_principal_name | memsql/host.domain.com@DOMAIN.COM | +-----------------------+-------------------------------------+ 2 rows in set (0.00 sec) ``` ## Granting a User Kerberos Authentication Permissions Now that the SingleStore cluster has been configured, you can use the GRANT command to create a Kerberos-authenticated user and grant permissions. To grant permissions, you simply map a SingleStore user to their Kerberos SPN. You can map Kerberos SPNs in two ways: by providing the name of a single Kerberos SPN, or by using regular expressions to match with or more Kerberos SPNs. ## Mapping a Single Kerberos Identity The following example creates a new SingleStore user (`'user1'@'%'`) authenticating via Kerberos on all databases, where the Kerberos SPN is `user1@EXAMPLE.COM`: ```sql GRANT ALL ON *.* TO 'user1'@'%' IDENTIFIED WITH 'authentication_gss' AS 'user1@EXAMPLE.COM'; ``` When this command is run, the `'user1'@'%'` SingleStore user is created and mapped to the `user1@EXAMPLE.COM` Kerberos SPN. After the command has been run, all subsequent SingleStore connection attempts for `'user1'@'%'` will require a Ticket Granting Ticket (TGT) from the KDC server for the `user1@EXAMPLE.COM` SPN. If a user attempts to connect with a TGT for a different SPN, the connection will fail. > **📝 Note**: The recommended way to create users is through the `CREATE USER` command. Granting permissions to existing users should only use the existing username without the `IDENTIFIED WITH` clause.```sql > GRANT DELETE ON db.* TO steve; > ``` ## Mapping with Regular Expressions You may also use regular expressions in the `AS` clause of the `GRANT` statement. This functionality is useful if you want to map a single SingleStore user to one or more Kerberos SPNs across multiple domains, or if you have other unique realm requirements. > **⚠️ Warning**: When using a regular expression in a `GRANT` statement, confirm that the expression evaluates in an expected manner. Unintended results can occur without thoroughly validating a regular expression. Regular expressions can only be used in the `AS` clause of the `GRANT` statement. By default, regular expressions are disabled in the `AS` clause. To enable regular expressions support, the first character in your `AS` clause must start with a forward slash (`/`). SingleStore recommends that the string use standard `^` (start of line) and `$` (end of line) operators to indicate when the regular expression should start and end. Consider the following example that creates a new user: ```sql GRANT ALL ON *.* to 'user1'@'%' IDENTIFIED WITH 'authentication_gss' AS '/^user1@EXAMPLE\.COM$'; ``` This example creates the user via regular expression to match the `user1@EXAMPLE.COM` string in any Kerberos SPN that attempts to authenticate with SingleStore. It uses proper start-of-line and end-of-line operators to indicate that only the full `user1@EXAMPLE.COM` SPN will be matched. It’s possible to introduce unexpected behavior without providing these operators. Consider the following example: ```sql GRANT ALL ON *.* to 'user1'@'%' IDENTIFIED WITH 'authentication_gss' AS '/user1@EXAMPLE\.COM$'; ``` The example above differs from the previous example by omitting the `^` start of line operator. This simple omission introduces significant security implications, because another Kerberos SPN might contain the substring of `user1@EXAMPLE.COM`, such as `other_user1@EXAMPLE.COM`. *Always ensure that your regular expression produces the intended result.* ## Example: Optional Subdomain The following example creates the SingleStore user `'user1'@'%'` with a Kerberos SPN that contains an optional subdomain. ```sql GRANT ALL ON *.* to 'user1'@'%' IDENTIFIED WITH 'authentication_gss' AS '/^user1@(SUBDOMAIN\.)?EXAMPLE\.COM$'; ``` ## Example: Optional Domain Suffix The following example creates the SingleStore user `'user1'@'%'` with a Kerberos SPN across domains with different suffixes, namely `.COM`, `.NET`, or `.ORG`. ```sql GRANT ALL ON *.* to 'user1'@'%' IDENTIFIED WITH 'authentication_gss' AS '/^user1@EXAMPLE\.(COM|NET|ORG)$'; ``` ## Connecting to SingleStore as a Kerberos-authenticated User After a SingleStore user has been associated with a Kerberos SPN, you can connect to SingleStore as that user. Before authenticating however, you must have a valid TGT in your credential cache. Depending on your domain and system configuration, there are a variety of ways to acquire a valid TGT. For example, the most common method on Linux/Unix is to execute `kinit` from the terminal. On Windows, TGT acquisition and renewal is typically done automatically, as per the Active Directory group policy configuration. ## Use the SingleStore Client Install the SingleStore client via the following instructions. ## Install SingleStore Client * *Red Hat Distribution* ## Online InstallationFor online installations where the target host can access the SingleStore YUM repository, perform the following steps.**Note**: These steps are also provided in the [self-managed deployment guides](https://docs.singlestore.com/db/v9.1/deploy.md).1) Add the SingleStore repository to your repository list. ```shell sudo yum-config-manager --add-repo https://release.memsql.com/production/rpm/x86_64/repodata/memsql.repo ``` 2) Verify that the SingleStore repo information is listed under `repolist`. ```shell sudo yum repolist ``` 3) Verify that the `which` package installed. This is used during the install process to identify the correct package type for your installation. ```shell rpm -q which ``` If `which` is not installed, it must be installed before proceeding. If you cannot install `which`, you will have to specify the correct package during the deployment phase covered in the respective deployment guide. ```shell sudo yum install -y which ``` 4) Install the SingleStore client. ```shell sudo yum install -y singlestore-client ```## Offline InstallationFor clusters that must be deployed in an environment without Internet access, download the SingleStore client package onto a host that can access the main deployment host.Copy the SingleStore client package onto the target host (typically the main deployment host when deploying SingleStore) and install the SingleStore client.```shell sudo rpm -ivh /tmp/singlestore-client--.x86_64.rpm ``` * *Debian Distribution* ## Online InstallationFor online installations where the target host can access the SingleStore APT repository, perform the following steps.**Note**: These steps are also provided in the [self-managed deployment guides](https://docs.singlestore.com/db/v9.1/deploy.md).1) SingleStore packages are signed to ensure integrity, so the GPG key needs to be added to this host. When done, verify that the SingleStore signing key has been added using `apt-key list`. ```shell wget -O - 'https://release.memsql.com/release-aug2018.gpg' 2>/dev/null | sudo apt-key add - && apt-key list ``` **Without using `apt-key`**: ```shell wget -q -O - 'https://release.memsql.com/release-aug2018.gpg' | sudo tee /etc/apt/trusted.gpg.d/memsql.asc 1>/dev/null ``` 2) Verify that `apt-transport-https` is installed. ```shell apt-cache policy apt-transport-https ``` If `apt-transport-https` is not installed, it must be installed before proceeding. ```shell user-shell sudo apt -y install apt-transport-https ``` 3) Add the SingleStore repository to retrieve its packages. ```shell echo "deb [arch=amd64] https://release.memsql.com/production/debian memsql main" | sudo tee /etc/apt/sources.list.d/memsql.list ``` 4) Install the SingleStore client. ```shell sudo apt update && sudo apt -y install singlestore-client ```## Offline InstallationFor clusters that must be deployed in an environment without Internet access, download the SingleStore client package onto a host that can access the main deployment host.Copy the SingleStore client package onto the target host (typically the main deployment host when deploying SingleStore) and install the SingleStore client.```shell sudo dpkg -i /tmp/singlestore-client___amd64.deb ``` * *Tarball* ## Download the SingleStore ClientDownload the SingleStore client tarball file onto a host that can access the main deployment host.## Transfer the SingleStore ClientTransfer the SingleStore client tarball file into a dedicated `singlestore` directory on the target host (typically the main deployment host when deploying SingleStore) that has been configured so that non-`sudo` users can access it, such as `/opt/singlestore`.## Unpack the SingleStore ClientUnpack the SingleStore client tarball file into the `singlestore` directory.```shell tar xzvf singlestore-client--.x86_64.tar.gz ```Using symbolic links (or "symlinks") can make using and upgrading the SingleStore client easier. Performing the following steps will allow the `singlestore` command to be run from anywhere on the filesystem, even after an upgrade by updating the symlink.1) Navigate to the directory that contains the unpacked SingleStore client tarball file and create a `singlestore-client` symlink that points to the SingleStore client directory. ```shell ln -s singlestore-client-- singlestore-client ``` 2) Verify that the symlink has been created. ```shell ls -l ``` ```output singlestore-client -> singlestore-client-1.0.6-c3803db03b ``` 3) Update the `PATH` environment variable with the path to the new `singlestore-client` directory. This path can also be added to your shell startup file so you won't have to run this command each time you log in. ```shell export PATH=/opt/singlestore/singlestore-client:$PATH ``` 4) You may now run the `singlestore` command from anywhere on the filesystem. ```shell singlestore ``` Once the SingleStore client has been installed: 1. Obtain a ticket from the Kerberos server. ```shell kinit @ ``` ```output Password for @: ``` 2. Connect with the SingleStore client. 1. For a **package-based installation** of the SingleStore client. ```shell singlestore -h --plugin-dir=/usr/lib/singlestore-client/plugin/ -u ``` 2. For a **tarball-based installation** of the SingleStore client. ```shell singlestore -h --plugin-dir=/path/to/singlestore-client/plugin/ -u ``` Note that this authentication method requires you to specify the plugin directory that contains the `auth_gssapi` plugin for the SingleStore ODBC Driver, as described in [Assumptions and Prerequisites](https://docs.singlestore.com/db/v9.1/security/authentication/kerberos-authentication/assumptions-and-prerequisites.md). Depending on the host operating system, you must provide the appropriate GSSAPI authentication plugin version. The SingleStore ODBC Driver provides authentication plugins for 32-bit and 64-bit versions of each supported operating system. To connect using ODBC, consider the following example: ``` Driver=;Database=information_schema;ServerName=10.0.0.1;Port=3306;UID=myusername;Plugin_Dir=; ``` *** Modified at: August 6, 2025 Source: [/db/v9.1/security/authentication/kerberos-authentication/configuring-singlestore-for-kerberos-authentication/](https://docs.singlestore.com/db/v9.1/security/authentication/kerberos-authentication/configuring-singlestore-for-kerberos-authentication/) (An index of the documentation is available at /llms.txt)