diff --git a/docs/pages/database-access/guides/cockroachdb-self-hosted.mdx b/docs/pages/database-access/guides/cockroachdb-self-hosted.mdx index e6fdb1fafea57..47b52206df222 100644 --- a/docs/pages/database-access/guides/cockroachdb-self-hosted.mdx +++ b/docs/pages/database-access/guides/cockroachdb-self-hosted.mdx @@ -20,17 +20,16 @@ description: How to configure Teleport database access with self-hosted Cockroac (!docs/pages/includes/edition-prereqs-tabs.mdx!) - CockroachDB cluster. + - A host, e.g., an Amazon EC2 instance, where you will run the Teleport Database Service. + - (!docs/pages/includes/tctl.mdx!) + - A certificate authority to issue CockroachDB certificates for nodes in your CockroachDB cluster. - Teleport uses a split CA architecture for database access, and requires that - you create your own CA for node-to-node mTLS communication. - See [cockroach cert](https://www.cockroachlabs.com/docs/stable/cockroach-cert) - for instructions on creating a CA and issuing a client certificate and key - for each node. The certificate and key should be named `client.node.crt` and - `client.node.key`. + + (!docs/pages/includes/database-access/split-db-ca-details.mdx db="CockroachDB"!) ## Step 1/4. Set up the Teleport Database Service @@ -81,49 +80,128 @@ in the CockroachDB documentation for more information. ### Set up mutual TLS -(!docs/pages/includes/database-access/tctl-auth-sign.mdx!) - To set up mutual TLS authentication, you need to make sure that: - Teleport trusts certificates presented by CockroachDB nodes. -- CockroachDB trusts client certificates signed by Teleport. +- CockroachDB nodes trust client certificates signed by both your CockroachDB CA + and your Teleport cluster's `db_client` CA. + +CockroachDB nodes need to trust the Teleport `db_client` CA so that Teleport +users can authenticate to your CockroachDB cluster as clients. + +The CockroachDB CA needs to be trusted by each CockroachDB node so that nodes +can authenticate themselves as clients to other nodes in the CockroachDB +cluster. This is because CockroachDB uses mTLS for node-to-node communication. + + + +In this configuration, your CockroachDB CA will be used to issue the server cert +`node.crt` for each CockroachDB node. -Generate the secrets by running the following `tctl` command against your -Teleport cluster: +This configuration is simpler to set up, because an existing CockroachDB cluster +already has `node.crt` issued for each node and you only need to configure the +CockroachDB nodes to trust your Teleport `db_client` CA. +Another benefit is that your CockroachDB nodes will continue to serve the same +CockroachDB CA-issued cert, rather than serving a new cert signed by Teleport's +`db` CA, so you don't have to configure other clients to trust a new CA. + +Copy your CockroachDB CA cert to `ca-client.crt` in the certs directory of +each CockroachDB node: + +```code +$ CERTS_DIR= +$ cp "${CERTS_DIR}/ca.crt" "${CERTS_DIR}/ca-client.crt" +``` + +Next, for each CockroachDB node, export Teleport's `db_client` CA using `tctl` +(or export it once and copy it to each node) and append the certificate to +`ca-client.crt`: + +```code +$ tctl auth export --type=db_client >> /ca-client.crt +``` + +(!docs/pages/includes/database-access/custom-db-ca.mdx db="CockroachDB" protocol="cockroachdb" port="26257"!) + + +In this configuration, Teleport's CA will be used to issue the server cert, +`node.crt`, and your own custom CA will be used to issue the client certificate, +`client.node.crt`, for each CockroachDB node. + +(!docs/pages/includes/database-access/tctl-auth-sign.mdx!) + +Generate secrets for a CockroachDB node using `tctl`: ```code $ tctl auth sign \ --format=cockroachdb \ --host=roach.example.com \ - --out=/path/to/cockroach/certs/dir/ \ + --out= \ --ttl=2190h ``` +(!docs/pages/includes/database-access/ttl-note.mdx!) + The command will produce 4 files: - `ca.crt` with Teleport's `db` certificate authority - `ca-client.crt` with Teleport's `db_client` certificate authority - `node.crt` / `node.key` with the node's certificate and key. + +You can specify multiple comma-separated addresses e.g. +`--host=roach,node-1,192.168.1.1`. +However, you must include the hostname that Teleport will use to connect to the +database. + + Do not rename these files as this is how CockroachDB expects them to be named. See [Node key and certificates](https://www.cockroachlabs.com/docs/v21.1/create-security-certificates-custom-ca#node-key-and-certificates) for details. -Generate the secrets for each cluster node and make sure to use the hostname -Teleport will be using to connect to the nodes in the `--host` flag. +Prepend your CockroachDB CA's certificate to `ca-client.crt`. +Now issue a client certificate for the node using your CockroachDB CA: - - You can specify multiple comma-separated addresses e.g. `--host=roach,node-1,192.168.1.1`. - +```code +$ cockroach cert create-client node \ + --certs-dir= \ + --ca-key=ca-secrets/ca-client.key +``` + +
+If you see an error message like: `tls: private key does not match public key`, +it likely means you did not prepend your CockroachDB CA cert to `ca-client.crt` +earlier. + +`cockroach cert create-client` expects the first certificate in `ca-client.crt` +(in the `--certs-dir` specified) to be the certificate signed by `--ca-key`. +Ensure that your CockroachDB CA certificate is the first certificate in +`ca-client.crt`. +
+ +Now copy `` to the CockroachDB +node and repeat these steps for all of your other CockroachDB nodes. + + Restart your CockroachDB nodes, passing them the directory with generated secrets via the `--certs-dir` flag: ```code $ cockroach start \ - --certs-dir=/path/to/cockroachdb/certs/dir/ \ + --certs-dir= \ # other flags... ``` +Alternatively, if the nodes were already started with +`--certs-dir=`, you can send a +`SIGHUP` signal to the `cockroach` process to reload certificates without +restarting the node. You must send `SIGHUP` as the same user that started the +`cockroach` process: + +```code +$ pkill -SIGHUP -x cockroach +``` + ## Step 4/4. Connect Log in to your Teleport cluster. Your CockroachDB cluster should appear in the diff --git a/docs/pages/database-access/guides/mongodb-self-hosted.mdx b/docs/pages/database-access/guides/mongodb-self-hosted.mdx index b501e6fe2efc7..f935153173cd2 100644 --- a/docs/pages/database-access/guides/mongodb-self-hosted.mdx +++ b/docs/pages/database-access/guides/mongodb-self-hosted.mdx @@ -22,27 +22,18 @@ videoBanner: 6lgVObxoLkc - MongoDB cluster (standalone or replica set) version `(=mongodb.min_version=)` or newer. - + Teleport database access supports MongoDB `(=mongodb.min_version=)` and newer. Older versions have not been tested and are not guaranteed to work. MongoDB `(=mongodb.min_version=)` was released in November 2017 and reached EOL in April 2021 so if you're still using an older version, consider upgrading. - + - (!docs/pages/includes/tctl.mdx!) - A certificate authority for MongoDB Replica Set, and the public certificate - for that CA, in PEM format, e.g. `/path/to/your/ca.crt`. + for that CA, in PEM format: ``. - - A MongoDB replica set requires that each MongoDB server is configured with a - certificate that has extendedKeyUsage `clientAuth, serverAuth`. - - Teleport uses a split CA architecture for better security: - the Teleport Database Server CA issues certs with `serverAuth` - and the Teleport Database Client CA issues certs with `clientAuth`. - Therefore, you must provide each MongoDB server with a certificate issued by - your own CA with extendedKeyUsage `clientAuth, serverAuth`. - + (!docs/pages/includes/database-access/split-db-ca-details.mdx db="MongoDB Replica Set"!) ## Step 1/3. Install and configure Teleport @@ -124,12 +115,10 @@ accordingly to grant the user appropriate database permissions. ### Set up mutual TLS -(!docs/pages/includes/database-access/tctl-auth-sign.mdx!) - -Create the secrets: - + (!docs/pages/includes/database-access/tctl-auth-sign.mdx!) + When connecting to standalone MongoDB, sign the certificate for the hostname over which Teleport will be connecting to it. @@ -152,28 +141,14 @@ Create the secrets: ```code $ tctl auth export --type=db_client > db-client-ca.crt - $ cat /path/to/your/ca.crt db-client-ca.crt > /etc/certs/mongo.cas + $ cat db-client-ca.crt > /etc/certs/mongo.cas ``` When MongoDB is configured to trust these CAs, it will trust the Teleport Database Client CA and allow access via Teleport, while still allowing MongoDB replication over TLS using your CA's certs for peer verification. - Next, modify your Teleport Database Service to trust your MongoDB Replica - Set CA: - ```yaml - databases: - - name: "example-mongo" - protocol: "mongodb" - uri: "mongo.example.com:27017" - static_labels: - "env": "dev" - tls: - ca_cert_file: "/path/to/your/ca.crt" - ``` - - Now the Teleport Database Service will trust certificates presented by your - MongoDB Replica Set. + (!docs/pages/includes/database-access/custom-db-ca.mdx db="MongoDB Replica Set" protocol="mongodb" port="27017"!) diff --git a/docs/pages/database-access/guides/redis-cluster.mdx b/docs/pages/database-access/guides/redis-cluster.mdx index 86dbc1e229a05..0a5eb6eb3bebf 100644 --- a/docs/pages/database-access/guides/redis-cluster.mdx +++ b/docs/pages/database-access/guides/redis-cluster.mdx @@ -22,12 +22,19 @@ If you want to configure Redis Standalone, please read [Database Access with Red (!docs/pages/includes/edition-prereqs-tabs.mdx!) - Redis version `6.0` or newer. + + + RESP3 (REdis Serialization Protocol) is currently not supported. + + - `redis-cli` version `6.2` or newer installed and added to your system's `PATH` environment variable. + - A host where you will run the Teleport Database Service. - - Redis `7.0` and RESP3 (REdis Serialization Protocol) are currently not supported. - +- A certificate authority to issue server certificates for nodes in your Redis + Cluster. + + (!docs/pages/includes/database-access/split-db-ca-details.mdx db="Redis Cluster"!) - (!docs/pages/includes/tctl.mdx!) @@ -66,43 +73,16 @@ Install and configure Teleport where you will run the Teleport Database Service: ## Step 4/6. Set up mutual TLS -(!docs/pages/includes/database-access/tctl-auth-sign.mdx!) - -We will show you how to use the `tctl auth sign` command below. - -When connecting to Redis Cluster, sign certificates for each member -using their hostnames and IP addresses. -For example, if the first member is accessible at `redis1.example.com` with IP `10.0.0.1` and -the second at `redis2.example.com` with IP `10.0.0.2`, run: +Export your Teleport cluster's `db_client` CA cert and concatenate it with your Redis +Cluster's CA cert (in PEM format): ```code -$ tctl auth sign --format=redis --host=redis1.example.com,10.0.0.1 --out=redis1 --ttl=2190h -$ tctl auth sign --format=redis --host=redis2.example.com,10.0.0.2 --out=redis2 --ttl=2190h +$ tctl auth export --type=db_client > db-client-ca.crt +$ cat db-client-ca.crt > pem-bundle.cas ``` -(!docs/pages/includes/database-access/ttl-note.mdx!) - -The command will create three files: -- `out.cas` with Teleport's database client certificate authority -- `out.key` with a generated private key -- `out.crt` with a generated certificate issued by Teleport's database server -certificate authority - -You will need these files to enable mutual TLS on your Redis server. - - - -If you wish to enable intra-cluster TLS communication in Redis, you will need -to generate and manage a CA to issue certificates for Redis Cluster nodes, -and configure your Teleport Database Service to trust that CA. - -Concatenate your CA's cert (in PEM format) with Teleport's database client -certificate authority: -```sh -cat /path/to/your/ca.crt out.cas > pem-bundle.cas -``` - -Using your CA, issue `server.crt` for your Redis Cluster node and enable mutual -TLS in your `redis.conf` configuration file, then restart the database: +Using your Redis Cluster's CA, issue `server.crt` for each of your Redis Cluster +nodes and enable mutual TLS in your `redis.conf` configuration file, then +restart each node: ```ini tls-port 7001 @@ -119,43 +99,6 @@ tls-ca-cert-file /usr/local/etc/redis/certs/pem-bundle.cas tls-protocols "TLSv1.2 TLSv1.3" ``` -Modify your Teleport Database Service to trust your Redis Cluster CA: -```yaml - databases: - - name: "example-redis" - protocol: "redis" - uri: "rediss://redis.example.com:6379?mode=cluster" - static_labels: - "env": "dev" - tls: - ca_cert_file: "/path/to/your/ca.crt" -``` - - -Use the generated secrets to enable mutual TLS in your `redis.conf` configuration -file and restart the database: - -```ini -tls-port 7001 -port 0 -cluster-enabled yes -tls-replication no -tls-cluster no -aclfile /path/to/users.acl -masterauth GENERATED_STRONG_PASSWORD -masteruser replica-user -tls-cert-file /usr/local/etc/redis/certs/server.crt -tls-key-file /usr/local/etc/redis/certs/server.key -tls-ca-cert-file /usr/local/etc/redis/certs/server.cas -tls-protocols "TLSv1.2 TLSv1.3" -``` - -With this configuration, communication between user clients and the Redis -Cluster will still use TLS, but Redis nodes will not use TLS to communicate with -each other. - - - Once mutual TLS has been enabled, you will no longer be able to connect to the cluster without providing a valid client certificate. You can use the `tls-auth-clients optional` setting to allow connections @@ -164,21 +107,28 @@ from clients that do not present a certificate. See [TLS Support](https://redis.io/topics/encryption) in the Redis documentation for more details. +(!docs/pages/includes/database-access/custom-db-ca.mdx db="Redis Cluster" protocol="redis" scheme="rediss://" port="6379" query="?mode=cluster"!) ## Step 5/6. Create a cluster +To create the cluster after mutual TLS is enabled, you will need to use a +certificate that the Redis nodes trust for client authentication. +You can use a certificate that you already issued for one of the nodes, i.e. +`server.crt` or you can issue a new client certificate using your Redis Cluster +CA. + Use the following command to create the cluster. Please note `redis-cli --cluster create` accepts only IP addresses. -```sh -export REDISCLI_AUTH=STRONG_GENERATED_PASSWORD -export CERTS_DIR=/path/to/certs/ -export IP1=10.0.0.1 # update with the real node 1 IP -export IP2=10.0.0.2 # update with the real node 2 IP -export IP3=10.0.0.3 # update with the real node 3 IP -export IP4=10.0.0.4 # update with the real node 4 IP -export IP5=10.0.0.5 # update with the real node 5 IP -export IP6=10.0.0.6 # update with the real node 6 IP -redis-cli --user alice --cluster-replicas 1 --tls --cluster-yes \ ---cluster create ${IP1}:7001 ${IP2}:7002 ${IP3}:7003 ${IP4}:7004 ${IP5}:7005 ${IP6}:7006 \ ---cacert ${CERTS_DIR}/server.cas --key ${CERTS_DIR}/server.key --cert ${CERTS_DIR}/server.crt +```code +$ export REDISCLI_AUTH=STRONG_GENERATED_PASSWORD +$ export CERTS_DIR=/path/to/certs/ +$ export IP1=10.0.0.1 # update with the real node 1 IP +$ export IP2=10.0.0.2 # update with the real node 2 IP +$ export IP3=10.0.0.3 # update with the real node 3 IP +$ export IP4=10.0.0.4 # update with the real node 4 IP +$ export IP5=10.0.0.5 # update with the real node 5 IP +$ export IP6=10.0.0.6 # update with the real node 6 IP +$ redis-cli --user alice --cluster-replicas 1 --tls --cluster-yes \ + --cluster create ${IP1}:7001 ${IP2}:7002 ${IP3}:7003 ${IP4}:7004 ${IP5}:7005 ${IP6}:7006 \ + --cacert ${CERTS_DIR}/ca.crt --key ${CERTS_DIR}/server.key --cert ${CERTS_DIR}/server.crt ``` ## Step 6/6. Connect diff --git a/docs/pages/database-access/guides/redis.mdx b/docs/pages/database-access/guides/redis.mdx index 04dd0be020ce6..a6f50feff7856 100644 --- a/docs/pages/database-access/guides/redis.mdx +++ b/docs/pages/database-access/guides/redis.mdx @@ -23,16 +23,16 @@ If you want to configure Redis Cluster, please read [Database Access with Redis - Redis version `6.0` or newer. + + RESP3 (REdis Serialization Protocol) is currently not supported. + + - `redis-cli` version `6.2` or newer installed and added to your system's `PATH` environment variable. - A host where you will run the Teleport Database Service. See [Installation](../../installation.mdx) for details. - - Redis `7.0` and RESP3 (REdis Serialization Protocol) are currently not supported. - - - (!docs/pages/includes/tctl.mdx!) ## Step 1/5. Set up the Teleport Database Service diff --git a/docs/pages/includes/database-access/custom-db-ca.mdx b/docs/pages/includes/database-access/custom-db-ca.mdx new file mode 100644 index 0000000000000..96ed9057512b9 --- /dev/null +++ b/docs/pages/includes/database-access/custom-db-ca.mdx @@ -0,0 +1,15 @@ +{{ scheme="" query="" }} +Modify the Teleport Database Service to trust your {{ db }} CA: + ```yaml + databases: + - name: "example-{{ protocol }}" + protocol: "{{ protocol }}" + uri: "{{ scheme }}{{ protocol }}.example.com:{{ port }}{{ query }}" + static_labels: + "env": "example" + tls: + ca_cert_file: "" + ``` + +Now the Teleport Database Service will trust certificates presented by your +{{ db }}. diff --git a/docs/pages/includes/database-access/split-db-ca-details.mdx b/docs/pages/includes/database-access/split-db-ca-details.mdx new file mode 100644 index 0000000000000..1605a45b7127b --- /dev/null +++ b/docs/pages/includes/database-access/split-db-ca-details.mdx @@ -0,0 +1,21 @@ +
+Distributed databases like {{ db }} use mTLS for node-to-node communication. +Teleport requires that you have your own CA to issue certificates for +node-to-node mTLS communication. + +Teleport uses a split-CA architecture for database access. The Teleport `db` CA +issues server certificates and the `db_client` CA issues client certificates. + +Databases are configured to trust the Teleport `db_client` CA for client +authentication, but not the `db` CA. +Additionally, Teleport only issues *ephemeral* `db_client` CA certificates. + +When a {{ db }} node connects to another {{ db }} node, it must present a +certificate that the other node trusts for client authentication. +Since Teleport does not issue long-lived `db_client` certificates, the node +needs to have a long-lived certificate issued by another CA that its peer node +trusts. + +The split `db` and `db_client` CA architecture was introduced as a security fix +in Teleport `15`. +