> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GSSAPI Authentication (Enterprise)

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

CockroachDB supports the Generic Security Services API (GSSAPI) with Kerberos authentication. Although CockroachDB does not support communicating directly with an LDAP service, GSSAPI with Kerberos can be configured to communicate with your LDAP service to authenticate users.

## Requirements

* A working Active Directory or Kerberos environment
* A Service Principal
* A GSSAPI-compatible PostgreSQL Client (psql, etc.)
* A client machine with a Kerberos client installed and configured

## Configure KDC for CockroachDB

To use Kerberos authentication with CockroachDB, configure a Kerberos service principal name (SPN) for CockroachDB and generate a valid keytab file with the following specifications:

* Set the SPN to the name specified by your client driver. For example, if you use the psql client, set SPN to `postgres`.
* Create SPNs for all DNS addresses that a user would use to connect to your CockroachDB cluster (including any TCP load balancers between the user and the CockroachDB node) and ensure that the keytab contains the keys for every SPN you create.

### Active Directory

For Active Directory, the client syntax for generating a keytab that maps a service principal to the SPN is as follows:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ktpass -out {keytab_filename} \
  -princ {Client_SPN}/{NODE/LB_FQDN}@{DOMAIN} \
  -mapUser {Service_Principal}@{DOMAIN} \
  -mapOp set -pType KRB5_NT_PRINCIPAL +rndPass \
  -crypto AES256-SHA1
```

Example:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ktpass -out postgres.keytab \
  -princ postgres/loadbalancer1.cockroach.industries@COCKROACH.INDUSTRIES \
  -mapUser pguser@COCKROACH.INDUSTRIES \
  -mapOp set -pType KRB5_NT_PRINCIPAL +rndPass \
  -crypto AES256-SHA1
```

Copy the resulting keytab to the database nodes. If clients are connecting to multiple addresses (more than one load balancer, or clients connecting directly to nodes), you will need to generate a keytab for each client endpoint. You may want to merge your keytabs together for easier management. You can do this using the `ktpass` command, using the following syntax:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ktpass -out {new_keytab_filename} \
  -in {old_keytab_filename} \
  -princ {Client_SPN}/{NODE/LB_FQDN}@{DOMAIN} \
  -mapUser {Service_Principal}@{DOMAIN} \
  -mapOp add \
  -pType KRB5_NT_PRINCIPAL +rndPass \
  -crypto AES256-SHA1
```

Example (adds `loadbalancer2` to the above example):

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ktpass -out postgres_2lb.keytab \
  -in postgres.keytab \
  -princ postgres/loadbalancer2.cockroach.industries@COCKROACH.INDUSTRIES \
  -mapUser pguser@COCKROACH.INDUSTRIES \
  -mapOp add \
  -pType KRB5_NT_PRINCIPAL +rndPass \
  -crypto AES256-SHA1
```

### MIT KDC

In MIT KDC, you cannot map a service principal to an SPN with a different username, so you will need to create a service principal that includes the SPN for your client.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
create-user: kadmin.local -q "addprinc {SPN}/{CLIENT_FQDN}@{DOMAIN}" -pw "{initial_password}"
```

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
create-keytab: kadmin.local -q "ktadd -k keytab {SPN}/{CLIENT_FQDN}@{DOMAIN}"
```

Example:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
kadmin.local -q "addprinc postgres/client2.cockroach.industries@COCKROACH.INDUSTRIES" -pw "testing12345!"
kadmin.local -q "ktadd -k keytab postgres/client2.cockroach.industries@COCKROACH.INDUSTRIES"
```

Copy the resulting keytab to the database nodes. If clients are connecting to multiple addresses (more than one load balancer, or clients connecting directly to nodes), you will need to generate a keytab for each client endpoint. You may want to merge your keytabs together for easier management. The `ktutil` command can be used to read multiple keytab files and output them into a single output [here](https://web.mit.edu/kerberos/krb5-devel/doc/admin/admin_commands/ktutil).

## Configure the CockroachDB node

1. Copy the keytab file to a location accessible by the `cockroach` binary.
2. <InternalLink path="cockroach-cert">Create certificates</InternalLink> for inter-node and `root` user authentication:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   mkdir certs my-safe-directory
   ```

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   cockroach cert create-ca \
     --certs-dir=certs \
     --ca-key=my-safe-directory/ca.key
   ```

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   cockroach cert create-node \
     localhost \
     $(hostname) \
     --certs-dir=certs \
     --ca-key=my-safe-directory/ca.key
   ```

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   cockroach cert create-client root \
   --certs-dir=certs \
   --ca-key=my-safe-directory/ca.key
   ```
3. Provide the path to the keytab in the `KRB5_KTNAME` environment variable.

   Example: `export KRB5_KTNAME=/home/cockroach/postgres.keytab`
4. Start a CockroachDB node:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   cockroach start --certs-dir=certs --listen-addr=0.0.0.0
   ```
5. Connect to CockroachDB as `root` using the `root` client certificate generated above:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   cockroach sql --certs-dir=certs
   ```
6. <InternalLink path="licensing-faqs#obtain-a-license">Enable an Enterprise license</InternalLink>.

<Note>
  You need the Enterprise license if you want to use the GSSAPI feature. However, if you only want to test that the GSSAPI setup is working, you do not need to enable an Enterprise license.
</Note>

7. Enable GSSAPI authentication:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   SET cluster setting server.host_based_authentication.configuration = 'host all all all gss include_realm=0';
   ```

   Setting the `server.host_based_authentication.configuration` <InternalLink path="cluster-settings">cluster setting</InternalLink> to this particular value makes it mandatory for all non-`root` users to authenticate using GSSAPI. The `root` user is always an exception and remains able to authenticate using a valid client cert or a user password.

   The `include_realm=0` option is required to tell CockroachDB to remove the `@DOMAIN.COM` realm information from the username. We do not support any advanced mapping of GSSAPI usernames to CockroachDB usernames right now. If you want to limit which realms' users can connect, you can also add one or more `krb_realm` parameters to the end of the line as an allowlist, as follows: `host all all all gss include_realm=0 krb_realm=domain.com krb_realm=corp.domain.com`

   The syntax is based on the `pg_hba.conf` standard for PostgreSQL which is documented [here](https://www.postgresql.org/docs/current/auth-pg-hba-conf). It can be used to exclude other users from Kerberos authentication.
8. Create CockroachDB users for every Kerberos user. Ensure the username does not have the `DOMAIN.COM` realm information. For example, if one of your Kerberos users has a username `carl@realm.com`, then you need to create a CockroachDB user with the username `carl`:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   CREATE USER carl;
   ```

   Grant privileges to the user:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   GRANT ALL ON DATABASE defaultdb TO carl;
   ```

## Configure the client

1. Install and configure your Kerberos client:

   For CentOS/RHEL systems, run:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   yum install krb5-user
   ```

   For Ubuntu/Debian systems, run:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   apt-get install krb5-user
   ```

   Edit the `/etc/krb5.conf` file to include:

   ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
          [libdefaults]
            default_realm = {REALM}

          [realms]
            {REALM} = {
             kdc = {fqdn-kdc-server or ad-server}
             admin_server = {fqdn-kdc-server or ad-server}
             default_domain = {realm-lower-case}
           }
   ```

   Example:

   ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}

          [libdefaults]
            default_realm = COCKROACH.INDUSTRIES

          [realms]
            COCKROACH.INDUSTRIES = {
             kdc = ad.cockroach.industries
             admin_server = ad.cockroach.industries
             default_domain = cockroach.industries
           }
   ```
2. Get a ticket for the db user:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   kinit carl
   ```
3. Verify if a valid ticket has been generated:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   klist
   ```
4. Connect to the cluster using the `cockroach sql` command as the Kerberos user:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   cockroach sql --certs-dir=certs -U carl
   ```
5. If you specified an Enterprise license earlier, the command succeeds. This indicates that the GSSAPI authentication was successful. Otherwise, the error `ERROR: use of GSS authentication requires an Enterprise license` is shown.

## See also

* <InternalLink path="authentication">Authentication</InternalLink>
* <InternalLink path="cockroach-cert">Create Security Certificates</InternalLink>