Add Snowflake integration docs (#12816)

Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
2026-09-24 16:17:11 +08:00 · 2022-06-30 02:53:19 +00:00
parent 86e0b6aec0
commit a3bc24e28b
19 changed files with 299 additions and 12 deletions
@@ -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/"
@@ -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).
+[configuration file](./reference/configuration.mdx#database-service-configuration).
@@ -16,7 +16,7 @@ Ensure that your environment includes the following:
 <TabItem scope={["oss"]} label="Open Source">

 - 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.
@@ -0,0 +1,208 @@
+---
+title: Database Access with Snowflake
+description: How to configure Teleport Database Access with Snowflake.
+---
+
+<Details
+  title="Version warning"
+  opened={true}
+  scope={["oss", "enterprise"]}
+  scopeOnly={true}
+  min="10.0"
+>
+  Database access for Snowflake is available starting from Teleport `10.0`.
+</Details>
+
+This guide will help you to:
+
+- Install and configure Teleport.
+- Assign Teleport's public key to a Snowflake user.
+- Connect to Snowflake through Teleport.
+
+<ScopedBlock scope={["oss", "enterprise"]}>
+  ![Teleport Database Access Snowflake Self-Hosted](../../../img/database-access/guides/snowflake_selfhosted.png)
+</ScopedBlock>
+
+<ScopedBlock scope={["cloud"]}>
+  ![Teleport Database Access Snowflake Cloud](../../../img/database-access/guides/snowflake_cloud.png)
+</ScopedBlock>
+
+## 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!)
+
+<ScopedBlock scope={["oss", "enterprise"]}>
+
+  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
+  ```
+
+  <Admonition type="note">
+
+    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.
+
+  </Admonition>
+
+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>
+
+  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
+  ```
+
+</ScopedBlock>
+
+<Admonition type="tip">
+  You can start the Database Service using a configuration file instead of CLI flags.
+  See the [YAML reference](../reference/configuration.mdx) for details.
+</Admonition>
+
+## 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:
+
+<Tabs>
+  <TabItem scope={["enterprise", "oss"]} label="Self-Hosted">
+    ```code
+    $ tsh login --proxy=teleport.example.com --user=alice
+    $ tsh db ls
+    # Name              Description         Labels
+    # ----------------- ------------------- --------
+    # example-snowflake Example Snowflake ❄ env=dev
+    ```
+  </TabItem>
+  <TabItem scope={["cloud"]} label="Teleport Cloud">
+    ```code
+    $ tsh login --proxy=mytenant.teleport.sh --user=alice
+    $ tsh db ls
+    # Name              Description         Labels
+    # ----------------- ------------------- --------
+    # example-snowflake Example Snowflake ❄ env=dev
+    ```
+  </TabItem>
+</Tabs>
+
+To connect to a particular database instance, first retrieve its certificate
+using the `tsh db login` command:
+
+```code
+$ tsh db login example-snowflake
+```
+
+<Admonition type="tip" title="Tip">
+  You can be logged into multiple databases simultaneously.
+</Admonition>
+
+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!)
@@ -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` |
@@ -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                                                                                                                              |
+|---------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
+| <nobr>`--roles`</nobr>    | List of roles to assign to the user. The builtin `access` role allows them to connect to any database server registered with Teleport.   |
+| <nobr>`--db-users`</nobr> | List of database usernames the user will be allowed to use when connecting to the databases. A wildcard allows any user.                 |
+| <nobr>`--db-names`</nobr> | List of logical databases (aka schemas) the user will be allowed to connect to within a database server. A wildcard allows any database. |

 <Admonition type="warning">
  Database names are only enforced for PostgreSQL and MongoDB databases.
@@ -40,6 +40,9 @@
  <Tile icon="database" title="Active Directory SQL Server (Preview)" href="./guides/sql-server-ad.mdx">
    Connect Microsoft SQL Server with Active Directory authentication.
  </Tile>
+  <Tile icon="database" title="Snowflake (Preview)" href="./guides/snowflake.mdx">
+    Connect Snowflake.
+  </Tile>
 </TileSet>

 ## Other guides
@@ -1,8 +1,10 @@
 <Admonition type="note" title="Certificate Rotation">
-  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.
 </Admonition>