DEV Community

Cockroach Labs profile image Fabio Ghirardello
Fabio Ghirardello for Cockroach Labs

Posted on

How-To: CockroachDB AuthN with Kerberos

#cockroachdb #kerberos #authentication #tutorial

CockroachDB supports user AuthN using the following methods:

  • password
  • cert (TLS client cert)
  • cert-password (either cert or password)
  • trusted (always authenticate)
  • reject (always reject)
  • gss (Use GSSAPI e.g. Kerberos)

By default every user can authenticate using either the cert or password methods.

In this brief blog, we outline the high level steps required to configure Kerberos AuthN in place of cert/password AuthN.

1 - Create Kerberos SPN and Keytab

In most organizations, you might have to find and ask another department to create the SPN and its keytab on your behalf.

Below the command to create the SPN, assuming we've access to the KDC server.
The keytab default location is /etc/krb5.keytab.

In our case, we add a Principal for the LB address only: we are permitting connection to the cluster only via the LB, that is, you can't point to a CockroachDB node directly.

This is to avoid endusers hardcoding a connection to a single node.
With this implementation, we ensure endusers go to the load-balancer for connection, which is the intended behavior.

Please note: user root bypasses Kerberos AuthN so it can connect from any node as long as the root key+crt are available.

# create principal named 'cockroach' kadmin.local addprinc -pw <password> cockroach/<load-balancer-IP>@<YOUR.REALM> kadmin.local addprinc -pw <password> cockroach/<load-balancer-hostname>@<YOUR.REALM> # create the principal keytab at /etc/krb5.keytab kadmin.local ktadd cockroach/<load-balancer-IP>@<YOUR.REALM> kadmin.local ktadd cockroach/<load-balancer-hostname>@<YOUR.REALM>
Enter fullscreen mode Exit fullscreen mode

Each CockroachDB User must have an equally named Principal.

# Principal and DB username is 'fabio' kadmin.local addprinc -pw <password> fabio@<YOUR.REALM>
Enter fullscreen mode Exit fullscreen mode

2 - Configure keytab on CockroachDB nodes

Download keytab file etc/krb5.keytab locally, then upload it to every CockroachDB cluster node.

The keytab file should be located inside the CockroachDB config directory, by default is /var/lib/cockroach.

It is customary to rename the file to cockroach.keytab.

Also, we assume a Linux user cockroach was created for running CockroachDB.

# assume krb5.keytab is available in the current directory sudo mv krb5.keytab /var/lib/cockroach/cockroach.keytab # ensure permissions and ownership are set correctly sudo chmod 644 /var/lib/cockroach/cockroach.keytab sudo chown cockroach:cockroach /var/lib/cockroach/cockroach.keytab
Enter fullscreen mode Exit fullscreen mode

CockroachDB will look for this file by querying the environment variable KRB5_KTNAME.

You make this env var available to CockroachDB via the Environment parameter in systemd unit file.

Here's an example systemd unit file, notice the Environment parameter.

[Unit] Description=Cockroach Database cluster node Requires=network.target [Service] Type=notify WorkingDirectory=/var/lib/cockroach Environment="KRB5_KTNAME=/var/lib/cockroach/cockroach.keytab" ExecStart=/usr/local/bin/cockroach start \ --certs-dir=/var/lib/cockroach/certs \ --store=/mnt/cockroach \ --listen-addr=0.0.0.0:26257 \ --advertise-addr=host1:26257 \ --cache=.25 \ --max-sql-memory=.25 \ --http-addr=0.0.0.0:8080 \ --join=host1,host2,host3 \ --locality=region=us-east4,zone=a TimeoutStopSec=300 LimitNOFILE=65000 Restart=always RestartSec=10 StandardOutput=syslog StandardError=syslog SyslogIdentifier=cockroach User=cockroach [Install] WantedBy=default.target
Enter fullscreen mode Exit fullscreen mode

Reload systemd service files, and restart each CockroachDB node

# repeat for each CockroachDB node systemctl daemon-reload systemctl restart cockroachdb
Enter fullscreen mode Exit fullscreen mode

3 - Configure CockroachDB for Kerberos AuthN

As an admin user, login into CockroachDB and enter these commands at the SQL prompt.

Please note, you need an enterprise license for this feature.

-- enable Kerberos AuthN for all users from all hosts SET cluster setting server.host_based_authentication.configuration = 'host all all all gss include_realm=0'; -- if not present already, create user 'fabio' -- the password is only used for logging into the DB Console. -- The password doesn't have to match the  -- password you gave for the Kerberos Principal, they -- are not related. CREATE USER fabio WITH password 'cockroach'; -- apply required grants to the user GRANT admin TO fabio;
Enter fullscreen mode Exit fullscreen mode

More info on the cluster setting value is available with great details here.

4 - Test

Login into the app server or any other server setup so that you can kinit (or equivalent in your favorite programming language).

# get the kerberos ticket kinit fabio
Enter fullscreen mode Exit fullscreen mode

You can use klist to verify the ticket is valid.
Now you're ready to connect to the database.

cockroach sql --url "postgresql://fabio@<load-balancer-hostname>:26257/defaultdb?sslmode=verify-full&sslrootcert=ca.crt&krbsrvname=cockroach"
Enter fullscreen mode Exit fullscreen mode

krbsrvname=cockroach this is where you tell CockroachDB what is the SPN user you created in step 1.

To confirm, destroy the ticket and re-attempt connection.
It should fail AuthN of the user.

# destroy all kerberos tickets kdestroy # there's no ticket, AuthN will fail cockroach sql --url "postgresql://fabio@<load-balancer-hostname>:26257/defaultdb?sslmode=verify-full&sslrootcert=ca.crt&krbsrvname=cockroach"
Enter fullscreen mode Exit fullscreen mode

References

Helpful blogs:

Top comments (0)