diff --git a/docs/pages/enroll-resources/database-access/enroll-self-hosted-databases/enroll-self-hosted-databases.mdx b/docs/pages/enroll-resources/database-access/enroll-self-hosted-databases/enroll-self-hosted-databases.mdx index 8e136d4240a27..a2d346b53764c 100644 --- a/docs/pages/enroll-resources/database-access/enroll-self-hosted-databases/enroll-self-hosted-databases.mdx +++ b/docs/pages/enroll-resources/database-access/enroll-self-hosted-databases/enroll-self-hosted-databases.mdx @@ -20,6 +20,7 @@ database in your Teleport cluster with the following guides: - [PostgreSQL](postgres-self-hosted.mdx) - [Redis Cluster](redis-cluster.mdx) - [Redis](redis.mdx) +- [SingleStore](singlestore-self-hosted.mdx) - [SQL Server with PKINIT authentication](sql-server-ad-pkinit.mdx) - [Vitess](vitess.mdx) diff --git a/docs/pages/enroll-resources/database-access/enroll-self-hosted-databases/singlestore-self-hosted.mdx b/docs/pages/enroll-resources/database-access/enroll-self-hosted-databases/singlestore-self-hosted.mdx new file mode 100644 index 0000000000000..41175309254e9 --- /dev/null +++ b/docs/pages/enroll-resources/database-access/enroll-self-hosted-databases/singlestore-self-hosted.mdx @@ -0,0 +1,196 @@ +--- +title: Database Access with Self-Hosted SingleStore +sidebar_label: SingleStore +description: How to configure Teleport database access with self-hosted SingleStore. +tags: + - how-to + - zero-trust + - infrastructure-identity +--- + +(!docs/pages/includes/database-access/self-hosted-introduction.mdx dbType="SingleStore"!) + +## How it works + +(!docs/pages/includes/database-access/how-it-works/mtls.mdx db="SingleStore"!) + +Teleport connects to the SingleStore database server using the same protocol and tools that are used to connect to MySQL Server. + + + +![Enroll SingleStore with a Self-Hosted Teleport Cluster](../../../../img/database-access/guides/mysql_selfhosted.png) + + +![Enroll SingleStore with a Cloud-Hosted Teleport Cluster](../../../../img/database-access/guides/mysql_cloud.png) + + + + +## Prerequisites + +(!docs/pages/includes/edition-prereqs-tabs.mdx!) + +- A self-hosted SingleStore instance managed by [SingleStore Toolbox](https://docs.singlestore.com/db/v9.0/user-and-cluster-administration/cluster-management-with-tools/singlestore-toolbox/). +The database version must be at least 9.0.11. +- A host, e.g., an Amazon EC2 instance, where you will run the Teleport Database + Service. +- Optional: a certificate authority that issues certificates for + your self-hosted database. +- (!docs/pages/includes/tctl.mdx!) + +## Step 1/4. Create the Teleport Database Token + +(!docs/pages/includes/tctl-token.mdx serviceName="Database" tokenType="db" tokenFile="/tmp/token"!) + +## Step 2/4. Create a certificate/key pair + +(!docs/pages/includes/database-access/tctl-auth-sign-3-files-with-ca.mdx dbname="SingleStore" databaseAddress="s2.example.com" !) + +## Step 3/4. Configure SingleStore + +To configure SingleStore to accept TLS connections, run the following commands to update SSL configuration on the server: + +```bash +sdb-admin update-config --key ssl_cert --value /path/to/server.crt --all --yes +sdb-admin update-config --key ssl_key --value /path/to/server.key --all --yes +sdb-admin update-config --key ssl_ca --value /path/to/teleport-bundle.pem --all --yes +sdb-admin update-config --key ssl_ca_for_client_cert --value /path/to/teleport-bundle.pem --all --yes +``` + +Restart the database instance to enable this configuration. + +``` +sdb-admin restart-node --all --yes +``` + +Your SingleStore database user accounts must be configured to require a +valid client certificate. + + + +Create a new user: + +```sql +CREATE USER 'alice'@'%' REQUIRE SUBJECT '/CN=alice'; +``` + +By default, the created user may not have access to anything and won't be able +to connect, so let's grant it some permissions: + +```sql +GRANT ALL ON `%`.* TO 'alice'@'%'; +``` + + +This is an example command that grants database-wide permissions to a user. +In a production environment you should follow the principle of least privilege + + + + +Because Teleport uses certificates to authenticate database users, the user must +not have a password set. Note that removing an existing user's password may break +existing integrations. Consider using a new Database user specifically for Teleport +access. + +Update the existing user to require a valid certificate: + +```sql +ALTER USER 'alice'@'%' REQUIRE SUBJECT '/CN=alice'; +``` + +Remove the password from the user: + +```sql +SET PASSWORD FOR 'alice'@'%' = PASSWORD(""); +``` + + + + +See +[Configuring SingleStore to Use Encrypted Connections](https://docs.singlestore.com/db/v9.0/security/encryption/ssl-secure-connections/server-configuration-for-secure-client-and-intra-cluster-connections/) +for more details. + +### Create a Teleport user + +(!docs/pages/includes/database-access/create-user.mdx!) + +### Configure and Start the Database Service + +Install and configure Teleport where you will run the Teleport Database Service: + + + + +(!docs/pages/includes/install-linux.mdx!) + +(!docs/pages/includes/database-access/self-hosted-config-start.mdx dbName="example-singlestore" dbProtocol="mysql" databaseAddress="s2.example.com:3306" !) + + + + Teleport provides Helm charts for installing the Teleport Database Service in Kubernetes Clusters. + + (!docs/pages/includes/kubernetes-access/helm/helm-repo-add.mdx!) + + (!docs/pages/includes/database-access/self-hosted-db-helm-install.mdx dbName="example-singlestore" dbProtocol="mysql" databaseAddress="s2.example.com:3306" !) + + + +(!docs/pages/includes/database-access/multiple-instances-tip.mdx !) + +## Step 4/4. Connect + +Once the Database Service has joined the cluster, log in to see the available +databases: + + + + +```code +$ tsh login --proxy=teleport.example.com --user=alice +$ tsh db ls +# Name Description Labels +# ------------------- ------------------- ------- +# example-singlestore Example SingleStore env=dev +``` + + + + +```code +$ tsh login --proxy=mytenant.teleport.sh --user=alice +$ tsh db ls +# Name Description Labels +# ------------------- ------------------- ------- +# example-singlestore Example SingleStore env=dev +``` + + + + + +Note that you will only be able to see databases your role has access to. See +the [RBAC](../rbac.mdx) guide for more details. + +To retrieve credentials for a database and connect to it: + +```code +$ tsh db connect --db-user=alice --db-name= example-singlestore +``` + + + The `mysql` or `mariadb` command-line client should be available in `PATH` in order to be + able to connect. `mariadb` is a default command-line client for SingleStore. + + +(!docs/pages/includes/database-access/db-access-webui-ad.mdx dbType="SingleStore"!) + +To log out of the database and remove credentials: + +```code +# Remove credentials for a particular database instance. +$ tsh db logout example-singlestore +# Remove credentials for all database instances. +$ tsh db logout +``` diff --git a/docs/pages/includes/database-access/tctl-auth-sign-3-files-with-ca.mdx b/docs/pages/includes/database-access/tctl-auth-sign-3-files-with-ca.mdx new file mode 100644 index 0000000000000..3dd65b841d130 --- /dev/null +++ b/docs/pages/includes/database-access/tctl-auth-sign-3-files-with-ca.mdx @@ -0,0 +1,100 @@ +{{ format="db" }} +Teleport uses mutual TLS authentication with self-hosted databases. These +databases must be able to verify certificates presented by the Teleport Database +Service. Self-hosted databases also need a certificate/key pair that Teleport +can verify. + +By default, the Teleport Database Service trusts certificates issued by a +certificate authority managed by the Teleport Auth Service. You can either: +- Configure your self-hosted database to trust this CA, and instruct Teleport to + issue a certificate for the database to present to the Teleport Database + Service. +- Configure the Database Service to trust a custom CA. + + + + +To configure the database to trust the Teleport CA and issue a certificate for +the database, follow these instructions on your workstation: + +1. To use `tctl` from your workstation, your Teleport user must be allowed to + impersonate the system role `Db` in order to be able to generate the database + certificate. Include the following `allow` rule in in your Teleport user's + role: + + ```yaml + allow: + impersonate: + users: ["Db"] + roles: ["Db"] + ``` + This can be done by creating a role named `db-access` and adding this role to the user, for example + ```yaml + kind: role + version: v7 + metadata: + name: db-access + spec: + allow: + db_labels: + "*": "*" + impersonate: + users: ["Db"] + roles: ["Db"] + ``` + The command `tctl create -f db-access.yml` will create the role, and the user can be created or modified using + ``` + tctl users add \ + --roles=access,requester,db-access \ + --db-users="*" \ + --db-names="*" \ + + ``` + +1. Export Teleport's certificate authority and generate certificate/key pair. + This example generates a certificate with a 90-day validity period. + `{{ databaseAddress }}` is the hostname where the Teleport Database Service can + reach the {{ dbname }} server. + + ```code + $ tctl auth sign --format={{ format }} --host={{ databaseAddress }} --out=server --ttl=2160h + ``` + + (!docs/pages/includes/database-access/ttl-note.mdx!) + + The command creates 3 files: `server.cas`, `server.crt` and `server.key`. +1. Export Teleport Database CA (Certificate Authority) public certificate and merge it with `server.cas` to + generate a bundled certificate which will be used by the database. + + ```code + tctl auth export --type=db > teleport-db-ca.pem + cat server.cas teleport-db-ca.pem > teleport-bundle.pem + ``` + + + + +If the {{ dbname }} database already has a CA that it uses to sign certificates +, you only need to export a Teleport CA certificate for the database to +authenticate traffic from the Teleport Database Service. You do not need to +enable `Db` impersonation privileges. + +1. Replace with the host and web port of + the Teleport Proxy Service in your cluster. Run the following command on your + workstation: + + ```code + $ tctl auth export --type=db-client --auth-server= > db-client.cas + ``` + + The command creates 1 file, `db-client.cas`. + +1. Append the contents of `db-client.cas` to your database's existing CA cert + file, which this guide expects to be called `server.cas`. + +1. Generate `server.crt` and `server.key` by retrieving a TLS certificate and + private key from your existing database CA, signed for your database server. + You will use these files later in the guide. + + +