-
Notifications
You must be signed in to change notification settings - Fork 1.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'branch/v15' into bot/backport-38494-branch/v15
- Loading branch information
Showing
11 changed files
with
960 additions
and
19 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -630,6 +630,7 @@ | |
| "nodename", | ||
| "nohup", | ||
| "nologin", | ||
| "noout", | ||
| "noprompt", | ||
| "nosql", | ||
| "nowait", | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,176 @@ | ||
| --- | ||
| title: Database CA Migrations | ||
| description: How to complete Teleport Database CA migrations. | ||
| --- | ||
|
|
||
| In Teleport, self-hosted databases must be configured with certificates to | ||
| enable mTLS authentication via the Teleport Database Service. | ||
|
|
||
| Teleport 15 introduced a new `db_client` certificate authority (CA) to split the | ||
| responsibilities of the Teleport `db` CA, which was acting as both host and | ||
| client CA for Teleport self-hosted database access. | ||
|
|
||
| Teleport's host/client database CA split is intended to limit the potential for | ||
| lateral movement to other resources in the event that a database instance's | ||
| private key is compromised. | ||
|
|
||
| The `db` and `db_client` CAs were both introduced as an automatic migration | ||
| after upgrading to Teleport 10 and Teleport 15, respectively. | ||
|
|
||
| This guide will explain why these CAs were created and how to determine if your | ||
| CA(s) should be rotated to complete the migration process. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| (!docs/pages/includes/edition-prereqs-tabs.mdx!) | ||
|
|
||
| - (!docs/pages/includes/tctl.mdx!) | ||
| - A Teleport cluster that was created prior to Teleport 15. | ||
| If your Teleport cluster was created with Teleport 15+, then this guide does | ||
| not apply to your cluster, because your `db` and `db_client` CAs were not | ||
| migrated. | ||
|
|
||
| ## Teleport `db` CA migration | ||
|
|
||
| Your Teleport cluster's `db` CA can be used to issue certificates to self-hosted | ||
| databases. | ||
| This is convenient, because the Teleport Database Service trusts certificates | ||
| issued by the `db` CA by default, so there is no additional TLS configuration | ||
| in Teleport required. | ||
|
|
||
| Alternatively, you can issue certificates to your self-hosted databases using | ||
| an external CA - you just need to configure the Teleport Database Service to | ||
| trust that CA when connecting to your database(s). | ||
|
|
||
| <Details title="How to make Teleport trust an external database CA?"> | ||
| For a static database defined in your Teleport Database Service `teleport.yaml` | ||
| configuration file, set `tls.ca_cert_file` to a file containing your CA's root | ||
| certificate. | ||
|
|
||
| For a dynamic database, put your CA's root certificate in `spec.tls.ca_cert`. | ||
|
|
||
| For examples and more information, consult the | ||
| [Database Access Configuration Reference](../../database-access/reference/configuration.mdx). | ||
| </Details> | ||
|
|
||
| Prior to Teleport 10, the Teleport `host` CA was used to issue certificates to | ||
| self-hosted databases (via `tctl auth sign`). | ||
| The Teleport `db` CA was introduced to decouple self-hosted database CA rotation | ||
| from the rest of your Teleport cluster. | ||
| The idea is that you should be able to rotate the CA used for self-hosted | ||
| databases without affecting other resources connected to your cluster. | ||
| Likewise, when you rotate your cluster's `host` CA, you should not have to worry | ||
| about affecting self-hosted databases. | ||
|
|
||
| To avoid breaking database access after upgrading to Teleport 10, Teleport | ||
| clusters are automatically migrated to create the `db` CA as a copy of | ||
| the `host` CA. | ||
|
|
||
| If your cluster was upgraded to Teleport 10 and you use Teleport to issue | ||
| certificates to your self-hosted databases, then you should ensure that you have | ||
| completed the `db` CA migration. | ||
| Otherwise, if you later rotate just one CA for any reason, a copy of the old CA | ||
| will still exist. | ||
| While this does not necessarily lead to a vulnerability in your cluster, it is | ||
| bad security practice to keep an old CA around after rotating it. | ||
|
|
||
| To complete the `db` CA migration: | ||
| - we recommend rotating your `host` CA | ||
| - we **strongly recommend** rotating your `db` CA | ||
|
|
||
| ## Teleport `db_client` CA migration | ||
|
|
||
| The Teleport Database Service needs to authenticate itself to self-hosted | ||
| database(s) using a client certificate, which requires that you configure your | ||
| database(s) to trust Teleport's `db_client` CA. | ||
| Prior to the introduction of the `db_client` CA in Teleport 15, self-hosted | ||
| had to be configured to trust the Teleport `db` CA for client authentication. | ||
|
|
||
| With the old approach - trusting the `db` CA for client connections - if a | ||
| database's private key is compromised, and a `db` certificate was issued for | ||
| that key, then it could be used to gain access to other databases. | ||
|
|
||
| Not all self-hosted databases are vulnerable to lateral movement after a private | ||
| key compromise. | ||
| For example, MySQL and PostgreSQL both verify that a client's certificate | ||
| subject matches the client's database user. | ||
| Other databases only verify that a client's certificate is trusted, but do not | ||
| match the certificate subject to the database username. | ||
| For example, Cassandra, ScyllaDB, and Redis do not verify the client cert | ||
| subject. | ||
| All of these databases can be configured to require password authentication | ||
| after a successful mTLS handshake. | ||
| However, for defense in depth, these databases should only mTLS handshake with | ||
| a client that presents a `db_client` CA-issued certificate. | ||
|
|
||
| If your Teleport cluster was upgraded to Teleport 15, then you should ensure | ||
| that you have completed the `db_client` migration. | ||
| To complete the `db_client` CA migration: | ||
| - we recommend rotating your `db` CA | ||
| - we **strongly recommend** rotating your `db_client` CA. | ||
| - we **strongly recommend** reconfiguring your databases' certificates after | ||
| you complete the `db_client` CA rotation. | ||
|
|
||
| <Admonition type="note" title="reconfiguring certs after db_client CA rotation"> | ||
| If you use `tctl auth sign` to reconfigure a database's certificates during | ||
| a `db_client` CA rotation, then the trusted certificate output will include | ||
| both the old and the new CA certificates. | ||
| To complete the migration, you should reconfigure those databases again after | ||
| the rotation - that way they will only trust the new CA. | ||
|
|
||
| If you don't want to reconfigure each database both during and after the | ||
| `db_client` CA rotation, and you do not mind temporarily losing connectivity | ||
| to your databases via Teleport, then you can just complete the `db_client` CA | ||
| rotation and reconfigure your databases afterward. | ||
| </Admonition> | ||
|
|
||
| ## 1/2. Check for Teleport CA migrations | ||
|
|
||
| If you upgraded your cluster to Teleport 10 and you have never rotated your | ||
| `host` or `db` CAs, then you should complete the `db` CA migration. | ||
|
|
||
| If you upgraded your cluster to Teleport 15 and you have never rotated your | ||
| `db` or `db_client` CAs, then you should complete the `db_client` CA migration. | ||
|
|
||
| If you are unsure whether you need to complete the migration for either the `db` | ||
| or `db_client` CAs, you can check for duplicated CAs. | ||
| Use these commands to print the X.509 certificate serial number for your `host`, | ||
| `db`, and `db_client` CAs (in that order): | ||
|
|
||
| ```code | ||
| $ tctl auth export --type=tls-host | openssl x509 -noout -serial | ||
| $ tctl auth export --type=db | openssl x509 -noout -serial | ||
| $ tctl auth export --type=db-client | openssl x509 -noout -serial | ||
| ``` | ||
|
|
||
| If the `db` CA serial number matches the `host` CA serial number, then you | ||
| need to complete the `db` CA migration. | ||
|
|
||
| If the `db_client` CA serial number matches the `db` CA serial number, then you | ||
| need to complete the `db_client` CA migration. | ||
|
|
||
| ## 2/2. Rotate CAs | ||
|
|
||
| If you need to complete both the `db` and `db_client` migrations, then a single | ||
| rotation of each of the `host`, `db`, and `db_client` CAs is enough: you do not | ||
| need to rotate the `db` CA twice. | ||
|
|
||
| If you need to rotate the `host` CA, we recommend completing that rotation | ||
| before starting either of the `db` or `db_client` CA rotations: do not rotate | ||
| other CAs in parallel with a `host` CA rotation. | ||
| For information about `host` CA rotation, refer to the | ||
| [CA Rotation Guide](./ca-rotation.mdx). | ||
|
|
||
| Database CA rotations are a little different, because they involve configuring | ||
| external resources (self-hosted databases) with new certificates during the | ||
| rotation. | ||
| You can (and should) rotate the `db` and `db_client` CAs at the same time to | ||
| avoid repeating the database certificate reconfiguration steps. | ||
|
|
||
| For details on rotating the `db` or `db_client` CA, refer to the | ||
| [Database CA Rotation Guide](./db-ca-rotation.mdx). | ||
|
|
||
| ## Further reading | ||
|
|
||
| - How the [Teleport Certificate Authority](../../architecture/authentication.mdx) works. | ||
| - How [Teleport Database Access](../../database-access/architecture.mdx) works. |
Oops, something went wrong.