diff --git a/docs/config.json b/docs/config.json index 60dc051a178..747af2d3b38 100644 --- a/docs/config.json +++ b/docs/config.json @@ -569,6 +569,10 @@ "title": "SQL Server (Preview)", "slug": "/database-access/guides/sql-server-ad/" }, + { + "title": "Snowflake (Preview)", + "slug": "/database-access/guides/snowflake/" + }, { "title": "Database GUI Clients", "slug": "/database-access/guides/gui-clients/" diff --git a/docs/img/database-access/guides/snowflake/dbeaver-driver.png b/docs/img/database-access/guides/snowflake/dbeaver-driver.png new file mode 100644 index 00000000000..aad3f911c3e Binary files /dev/null and b/docs/img/database-access/guides/snowflake/dbeaver-driver.png differ diff --git a/docs/img/database-access/guides/snowflake/dbeaver-main-screen.png b/docs/img/database-access/guides/snowflake/dbeaver-main-screen.png new file mode 100644 index 00000000000..2a2a19ed334 Binary files /dev/null and b/docs/img/database-access/guides/snowflake/dbeaver-main-screen.png differ diff --git a/docs/img/database-access/guides/snowflake/dbeaver-main.png b/docs/img/database-access/guides/snowflake/dbeaver-main.png new file mode 100644 index 00000000000..226244f6d21 Binary files /dev/null and b/docs/img/database-access/guides/snowflake/dbeaver-main.png differ diff --git a/docs/img/database-access/guides/snowflake/dbeaver-select-database.png b/docs/img/database-access/guides/snowflake/dbeaver-select-database.png new file mode 100644 index 00000000000..f741275f2e7 Binary files /dev/null and b/docs/img/database-access/guides/snowflake/dbeaver-select-database.png differ diff --git a/docs/img/database-access/guides/snowflake/dbeaver-success.png b/docs/img/database-access/guides/snowflake/dbeaver-success.png new file mode 100644 index 00000000000..3fbeb3b6cc4 Binary files /dev/null and b/docs/img/database-access/guides/snowflake/dbeaver-success.png differ diff --git a/docs/img/database-access/guides/snowflake/jetbrains-add-database.png b/docs/img/database-access/guides/snowflake/jetbrains-add-database.png new file mode 100644 index 00000000000..266c7e159f7 Binary files /dev/null and b/docs/img/database-access/guides/snowflake/jetbrains-add-database.png differ diff --git a/docs/img/database-access/guides/snowflake/jetbrains-advanced.png b/docs/img/database-access/guides/snowflake/jetbrains-advanced.png new file mode 100644 index 00000000000..8074dd7de82 Binary files /dev/null and b/docs/img/database-access/guides/snowflake/jetbrains-advanced.png differ diff --git a/docs/img/database-access/guides/snowflake/jetbrains-general.png b/docs/img/database-access/guides/snowflake/jetbrains-general.png new file mode 100644 index 00000000000..348a96ab726 Binary files /dev/null and b/docs/img/database-access/guides/snowflake/jetbrains-general.png differ diff --git a/docs/img/database-access/guides/snowflake/jetbrains-success.png b/docs/img/database-access/guides/snowflake/jetbrains-success.png new file mode 100644 index 00000000000..246b0da46ea Binary files /dev/null and b/docs/img/database-access/guides/snowflake/jetbrains-success.png differ diff --git a/docs/img/database-access/guides/snowflake_cloud.png b/docs/img/database-access/guides/snowflake_cloud.png new file mode 100644 index 00000000000..3f96e9a4d71 Binary files /dev/null and b/docs/img/database-access/guides/snowflake_cloud.png differ diff --git a/docs/img/database-access/guides/snowflake_selfhosted.png b/docs/img/database-access/guides/snowflake_selfhosted.png new file mode 100644 index 00000000000..b2c9b4d3b99 Binary files /dev/null and b/docs/img/database-access/guides/snowflake_selfhosted.png differ diff --git a/docs/pages/database-access/faq.mdx b/docs/pages/database-access/faq.mdx index a579246b8c7..feaba179695 100644 --- a/docs/pages/database-access/faq.mdx +++ b/docs/pages/database-access/faq.mdx @@ -13,6 +13,7 @@ Teleport Database Access currently supports the following protocols: - MySQL - PostgreSQL - Redis +- Snowflake For PostgreSQL and MySQL, the following Cloud-hosted versions are supported in addition to self-hosted deployments: @@ -112,4 +113,4 @@ If none of the above options work for you and you still want to disable the CA check, you can use `mode` under the `tls` option in the Teleport configuration file. For more details please refer to the reference -[configuration file](./reference/configuration.mdx#database-service-configuration). \ No newline at end of file +[configuration file](./reference/configuration.mdx#database-service-configuration). diff --git a/docs/pages/database-access/guides/gui-clients.mdx b/docs/pages/database-access/guides/gui-clients.mdx index 44b91bb3217..1cfa530368c 100644 --- a/docs/pages/database-access/guides/gui-clients.mdx +++ b/docs/pages/database-access/guides/gui-clients.mdx @@ -16,7 +16,7 @@ Ensure that your environment includes the following: - A running Teleport cluster. For details on how to set this up, see one of our - [Getting Started](/docs/getting-started) guides. + [Getting Started](/docs/getting-started) guides. - The `tsh` client tool version >= (=teleport.version=). @@ -338,3 +338,72 @@ Click `Add Redis Database`. Congratulations! You have just connected to your Redis instance. ![Redis Insight Connected](../../../img/database-access/guides/redis/redisinsight-connected.png) + + +## Snowflake: JetBrains (IntelliJ, Goland, DataGrip, PyCharm, etc.) + + +The Snowflake integration works only in the authenticated proxy mode. Start a local proxy for connections to your Snowflake database by using the command below: +``` +tsh proxy db --tunnel --port 2000 snowflake +``` + +In "Database Explorer" click the "add" button, pick "Data Source", and then pick "Snowflake": + +![JetBrains Add Database](../../../img/database-access/guides/snowflake/jetbrains-add-database.png) + +Next, set "Host" to `localhost` and "Port" to the port returned by the `tsh proxy db` command you ran earlier (`2000` in the example above). +Set the "Username" to match the one that you are assuming when you connect to Snowflake + via Teleport and enter any value (e.g., "teleport") in the "Password" field (the value of + "Password" will be ignored but is required to create a data source in your IDE): + +![JetBrains General](../../../img/database-access/guides/snowflake/jetbrains-general.png) + +Switch to the "Advanced" tab, set any value (e.g., "teleport") for "account", and add a new record named `ssl` with value `off` (as with "Password", "account" is ignored while establishing the connection but required by your IDE): + +![JetBrains Advanced](../../../img/database-access/guides/snowflake/jetbrains-advanced.png) + +Teleport ignores the provided password and the account name as internally it uses values from the Database Agent configuration. +Setting "SSL" to `off` only disables encryption on your local machine. The connection to Snowflake is encrypted by Teleport. + +Now you can click "Test Connection" to check your configuration. + +![JetBrains Success](../../../img/database-access/guides/snowflake/jetbrains-success.png) + +Congratulations! You have just connected to your Snowflake instance. + +## Snowflake: DBeaver + +The Snowflake integration works only in the authenticated proxy mode. Start a local proxy for connections to your Snowflake database by using the command below: +``` +tsh proxy db --tunnel --port 2000 snowflake +``` + +Add a new database by clicking the "add" icon in the top-left corner: + +![DBeaver Main Screen](../../../img/database-access/guides/snowflake/dbeaver-main-screen.png) + +In the search bar of the "Connect to a database" window that opens up, type "snowflake", select the Snowflake driver, and click "Next": + +![DBeaver Select Database](../../../img/database-access/guides/snowflake/dbeaver-select-database.png) + +Set "Host" to `localhost` and "Port" to the port returned by the `tsh proxy db` command you ran earlier (`2000` in the example above). +In the "Authentication" section set the "Username" to match the database username passed to Teleport with `--db-user` +and enter any value (e.g., "teleport") in the "Password" field (the value of + "Password" will be ignored when establishing a connection but is required by DBeaver to register your database): + +![DBeaver Main](../../../img/database-access/guides/snowflake/dbeaver-main.png) + +Next, click the "Driver properties" tab and set "account" to any value (e.g., "teleport"; as with "Password", the value of + "account" will be ignored when establishing a connection but is required by DBeaver to register your database). In "User properties", set "ssl" to `off`: + +![DBeaver Driver](../../../img/database-access/guides/snowflake/dbeaver-driver.png) + +Teleport ignores the provided password and the account name as internally it uses values from the Database Agent configuration. +SSL set to `off` disables only encryption on local machine. Connection to Snowflake is encrypted by Teleport. + +Now you can click on "Test Connection..." in the bottom-left corner: + +![DBeaver Success](../../../img/database-access/guides/snowflake/dbeaver-success.png) + +Congratulations! You have just connected to your Snowflake instance. diff --git a/docs/pages/database-access/guides/snowflake.mdx b/docs/pages/database-access/guides/snowflake.mdx new file mode 100644 index 00000000000..9ea6ee88695 --- /dev/null +++ b/docs/pages/database-access/guides/snowflake.mdx @@ -0,0 +1,208 @@ +--- +title: Database Access with Snowflake +description: How to configure Teleport Database Access with Snowflake. +--- + +
+ Database access for Snowflake is available starting from Teleport `10.0`. +
+ +This guide will help you to: + +- Install and configure Teleport. +- Assign Teleport's public key to a Snowflake user. +- Connect to Snowflake through Teleport. + + + ![Teleport Database Access Snowflake Self-Hosted](../../../img/database-access/guides/snowflake_selfhosted.png) + + + + ![Teleport Database Access Snowflake Cloud](../../../img/database-access/guides/snowflake_cloud.png) + + +## Prerequisites + +- Snowflake account with `SECURITYADMIN` role or higher. + +- `snowsql` installed and added to your system's `PATH` environment variable. + +- A host where you will run the Teleport Database Service. Teleport version 10.0 or newer must be installed. + + See [Installation](../../installation.mdx) for details. + +(!docs/pages/includes/user-client-prereqs.mdx!) + +(!docs/pages/includes/tctl.mdx!) + +## Step 1/5. Install and configure Teleport + +### Set up the Teleport Auth and Proxy Services + +(!docs/pages/includes/database-access/start-auth-proxy.mdx!) + +### Set up the Teleport Database Service + +(!docs/pages/includes/database-access/token.mdx!) + +Install Teleport on the host where you will run the Teleport Database Service: + +(!docs/pages/includes/install-linux.mdx!) + + + + Start the Teleport Database Service, pointing the `--auth-server` flag to the + address of your Teleport Proxy Service: + + ```code + $ teleport db start \ + --token=/tmp/token \ + --auth-server=teleport.example.com:3080 \ + --name=example-snowflake \ + --protocol=Snowflake \ + --uri=https://abc123.us-east-2.aws.snowflakecomputing.com \ + --labels=env=dev + ``` + + + + The `--auth-server` flag must point to the Teleport cluster's Proxy Service + endpoint because the Database Service always connects back to the cluster over a + reverse tunnel. + + + + + + + Start the Teleport Database Service, pointing the `--auth-server` flag to the + address of your Teleport Cloud tenant: + + ```code + $ teleport db start \ + --token=/tmp/token \ + --auth-server=mytenant.teleport.sh:443 \ + --name=example-snowflake \ + --protocol=Snowflake \ + --uri=Snowflakes://Snowflake.example.com:6379 \ + --labels=env=dev + ``` + + + + + You can start the Database Service using a configuration file instead of CLI flags. + See the [YAML reference](../reference/configuration.mdx) for details. + + +## Step 2/5. Create a Teleport user + +(!docs/pages/includes/database-access/create-user.mdx!) + +## Step 3/5. Export a public key + +Use the `tctl auth sign` command below to export a public key for your Snowflake user: + +```code +$ tctl auth sign --format=snowflake --out=server +``` + +The command will create a `server.pub` file with Teleport's public key. Teleport will use the corresponding private key to +generate a JWT (JSON Web Token) that will be used to authenticate to Snowflake. + +(!docs/pages/includes/database-access/rotation-note.mdx!) + +## Step 4/5. Add the public key to your Snowflake user + +Use the public key you generated earlier to enable key pair authentication. + +Log in to your Snowflake instance and execute the SQL statement below: + +```sql +alter user alice set rsa_public_key='MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAv3dHYw4LJCcZzdbhb3hV +... +LwIDAQAB'; +``` + +In this statement, `alice` is the name of the Snowflake user and the `rsa_public_key` is the key generated earlier without +the PEM header/footer (first and the last line). + +You can use the `describe user` command to verify the user's public key: + +```sql +desc user alice; +``` + +See the [Snowflake documentation](https://docs.snowflake.com/en/user-guide/key-pair-auth.html#step-4-assign-the-public-key-to-a-snowflake-user) +for more details. + +## Step 5/5. Connect + +Log in to your Teleport cluster and see the available databases: + + + + ```code + $ tsh login --proxy=teleport.example.com --user=alice + $ tsh db ls + # Name Description Labels + # ----------------- ------------------- -------- + # example-snowflake Example Snowflake ❄ env=dev + ``` + + + ```code + $ tsh login --proxy=mytenant.teleport.sh --user=alice + $ tsh db ls + # Name Description Labels + # ----------------- ------------------- -------- + # example-snowflake Example Snowflake ❄ env=dev + ``` + + + +To connect to a particular database instance, first retrieve its certificate +using the `tsh db login` command: + +```code +$ tsh db login example-snowflake +``` + + + You can be logged into multiple databases simultaneously. + + +You can optionally specify the user to use by default +when connecting to the database instance: + +```code +$ tsh db login --db-user=alice example-snowflake +``` + +Once logged in, connect to the database: + +```code +$ tsh db connect example-snowflake +``` + +The `snowsql` command-line client should be available in the system `PATH` in order to be +able to connect. + +To log out of the database and remove credentials: + +```code +# Remove credentials for a particular database instance. +$ tsh db logout example-snowflake +# Remove credentials for all database instances. +$ tsh db logout +``` + +## Next steps + +(!docs/pages/includes/database-access/guides-next-steps.mdx!) diff --git a/docs/pages/database-access/reference/cli.mdx b/docs/pages/database-access/reference/cli.mdx index 1dd0f9ddb0e..52bbe9760fa 100644 --- a/docs/pages/database-access/reference/cli.mdx +++ b/docs/pages/database-access/reference/cli.mdx @@ -107,7 +107,7 @@ $ teleport db configure create \ | `--redshift-discovery` | List of AWS regions the agent will discover for Redshift instances. | | `--ca-pin` | CA pin to validate the Auth Service (can be repeated for multiple pins). | | `--name` | Name of the proxied database. | -| `--protocol` | Proxied database protocol. Supported are: `[postgres mysql mongodb cockroachdb redis sqlserver]`. | +| `--protocol` | Proxied database protocol. Supported are: `[postgres mysql mongodb cockroachdb redis sqlserver snowflake]`. | | `--uri` | Address the proxied database is reachable at. | | `--labels` | Comma-separated list of labels for the database, for example env=dev,dept=it | | `-o/--output` | Write to stdout with `-o=stdout`, the default config file with `-o=file`, or a custom path with `-o=file:///path` | diff --git a/docs/pages/includes/database-access/create-user.mdx b/docs/pages/includes/database-access/create-user.mdx index 5aea083c01b..3016aff737f 100644 --- a/docs/pages/includes/database-access/create-user.mdx +++ b/docs/pages/includes/database-access/create-user.mdx @@ -8,11 +8,11 @@ $ tctl users add \ alice ``` -| Flag | Description | -| ---- | ----------- | -| `--roles` | List of roles to assign to the user. The builtin `access` role allows them to connect to any database server registered with Teleport. | -| `--db-users` | List of database usernames the user will be allowed to use when connecting to the databases. A wildcard allows any user. | -| `--db-names` | List of logical databases (aka schemas) the user will be allowed to connect to within a database server. A wildcard allows any database. | +| Flag | Description | +|---------------------------|------------------------------------------------------------------------------------------------------------------------------------------| +| `--roles` | List of roles to assign to the user. The builtin `access` role allows them to connect to any database server registered with Teleport. | +| `--db-users` | List of database usernames the user will be allowed to use when connecting to the databases. A wildcard allows any user. | +| `--db-names` | List of logical databases (aka schemas) the user will be allowed to connect to within a database server. A wildcard allows any database. | Database names are only enforced for PostgreSQL and MongoDB databases. diff --git a/docs/pages/includes/database-access/guides.mdx b/docs/pages/includes/database-access/guides.mdx index 05325a9eba3..2acdac7fe0a 100644 --- a/docs/pages/includes/database-access/guides.mdx +++ b/docs/pages/includes/database-access/guides.mdx @@ -40,6 +40,9 @@ Connect Microsoft SQL Server with Active Directory authentication. + + Connect Snowflake. + ## Other guides diff --git a/docs/pages/includes/database-access/rotation-note.mdx b/docs/pages/includes/database-access/rotation-note.mdx index e95abbb111c..7b57d167f08 100644 --- a/docs/pages/includes/database-access/rotation-note.mdx +++ b/docs/pages/includes/database-access/rotation-note.mdx @@ -1,8 +1,10 @@ - Teleport 9.1 introduced new database certificate authority that is only used by Database Access. - Older Teleport versions uses host certificate to sign Database Access certificates. - After upgrading to Teleport 9.1 the host certificate authority will be still used by Database Access to maintain compatibility. + Teleport 10.0 introduced a new certificate authority that is only used by Database Access. + Older Teleport versions use a host certificate to sign Database Access certificates. + +After upgrading to Teleport 10.0, the host certificate authority will still be used by Database Access to maintain compatibility. The first [certificate rotation](../../setup/operations/ca-rotation.mdx) will rotate host and database certificates. - New Teleport 9.1+ installations generate database certificate authority on the first start and they are not affected + +New Teleport 10.0+ installations generate the database certificate authority when they first start, and are not affected by the rotation procedure described above.