Skip to content

Commit

Permalink
Add MFA explainer (#5721)
Browse files Browse the repository at this point in the history
Following this conversation:
https://dbt-labs.slack.com/archives/C02SRNY2EQ4/p1719421396340509

---------

Co-authored-by: mirnawong1 <mirna.wong@fishtownanalytics.com>
Co-authored-by: Mirna Wong <89008547+mirnawong1@users.noreply.github.com>
Co-authored-by: Matt Shaver <60105315+matthewshaver@users.noreply.github.com>
  • Loading branch information
4 people authored Jul 4, 2024
1 parent 51b2829 commit 586e701
Show file tree
Hide file tree
Showing 2 changed files with 45 additions and 25 deletions.
70 changes: 45 additions & 25 deletions website/docs/docs/cloud/connect-data-platform/connect-snowflake.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,31 @@ to authenticate dbt Cloud to run queries against Snowflake on behalf of a Snowfl
**Note**: The schema field in the **Developer Credentials** section is a required field.
<Lightbox src="/img/docs/dbt-cloud/snowflake-userpass-auth.png" width="70%" title="Snowflake username/password authentication"/>

### Snowflake MFA

**Prerequisites:**
- A development environment in a dbt Cloud project
- The Duo authentication app
- Admin access to Snowflake (if MFA settings haven't already been applied to the account)
- [Admin (write) access](/docs/cloud/manage-access/seats-and-users) to dbt Cloud environments

dbt Cloud supports Snowflake's [multi-factor authentication (MFA)](https://docs.snowflake.com/en/user-guide/security-mfa) as another username and password option for increased login security. Snowflake's MFA support is powered by the Duo Security service.

- In dbt Cloud, set the following [extended attribute](/docs/dbt-cloud-environments#extended-attributes) in the development environment **General settings** page, under the **Extended attributes** section:

```yaml
authenticator: username_password_mfa
```
- To reduce the number of user prompts when connecting to Snowflake with MFA, [enable token caching](https://docs.snowflake.com/en/user-guide/security-mfa#using-mfa-token-caching-to-minimize-the-number-of-prompts-during-authentication-optional) in Snowflake.
- Optionally, if users miss prompts and their Snowflake accounts get locked, you can prevent automatic retries by adding the following in the same **Extended attributes** section:
```yaml
connect_retries: 0
```
<Lightbox src="/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/extended-attributes-mfa.jpg" width="70%" title="Configure the MFA username and password, and connect_retries in the development environment settings." />
### Key pair
**Available in:** Development environments, Deployment environments
Expand Down Expand Up @@ -67,15 +92,16 @@ The `Keypair` auth method uses Snowflake's [Key Pair Authentication](https://doc
**Available in:** Development environments, Enterprise plans only

The OAuth auth method permits dbt Cloud to run development queries on behalf of
a Snowflake user without the configuration of Snowflake password in dbt Cloud. For
more information on configuring a Snowflake OAuth connection in dbt Cloud, please see [the docs on setting up Snowflake OAuth](/docs/cloud/manage-access/set-up-snowflake-oauth).
<Lightbox src="/img/docs/dbt-cloud/dbt-cloud-enterprise/database-connection-snowflake-oauth.png" width="70%" title="Configuring Snowflake OAuth connection"/>
a Snowflake user without the configuration of Snowflake password in dbt Cloud.

For more information on configuring a Snowflake OAuth connection in dbt Cloud, please see [the docs on setting up Snowflake OAuth](/docs/cloud/manage-access/set-up-snowflake-oauth).
<Lightbox src="/img/docs/dbt-cloud/dbt-cloud-enterprise/database-connection-snowflake-oauth.png" width="55%" title="Configuring Snowflake OAuth connection"/>

## Configuration

To learn how to optimize performance with data platform-specific configurations in dbt Cloud, refer to [Snowflake-specific configuration](/reference/resource-configs/snowflake-configs).

### Custom domain URL support
### Custom domain URL

To connect to Snowflake through a custom domain (vanity URL) instead of the account locator, use [extended attributes](/docs/dbt-cloud-environments#extended-attributes) to configure the `host` parameter with the custom domain:

Expand All @@ -90,30 +116,24 @@ This configuration may conflict with Snowflake OAuth when used with PrivateLink.

If you're receiving a `Could not deserialize key data` or `JWT token` error, refer to the following causes and solutions:

<details>
<detailsToggle alt_header="Error: `Could not deserialize key data`">
Possible cause and solution for the error "Could not deserialize key data" in dbt Cloud.
- This could be because of mistakes like not copying correctly, missing dashes, or leaving out commented lines.

<summary>Error: <code>Could not deserialize key data</code></summary>
**Solution**:
- You can copy the key from its source and paste it into a text editor to verify it before using it in dbt Cloud.

- <b>Possible cause</b>

- This could be because of mistakes like not copying correctly, missing dashes, or leaving out commented lines.
- <b>Solution</b>

- You can copy the key from its source and paste it into a text editor to verify it before using it in dbt Cloud.

</details>
</detailsToggle>

<details>
<summary>Error: <code>JWT token</code></summary>
<detailsToggle alt_header="Error: `JWT token`">
- <b>Possible causes</b>

- This could be a transient issue between Snowflake and dbt Cloud. When connecting to Snowflake, dbt gets a JWT token valid for only 60 seconds. If there's no response from Snowflake within this time, you might see a `JWT token is invalid` error in dbt Cloud.
- The public key was not entered correctly in Snowflake.
- <b>Solutions</b>
Possible cause and solution for the error "JWT token" in dbt Cloud.
- This could be a transient issue between Snowflake and dbt Cloud. When connecting to Snowflake, dbt gets a JWT token valid for only 60 seconds. If there's no response from Snowflake within this time, you might see a `JWT token is invalid` error in dbt Cloud.
- The public key was not entered correctly in Snowflake.

- dbt needs to retry connections to Snowflake.
- Confirm and enter Snowflake's public key correctly. Additionally, you can reach out to Snowflake for help or refer to this Snowflake doc for more info: [Key-Based Authentication Failed with JWT token is invalid Error](https://community.snowflake.com/s/article/Key-Based-Authentication-Failed-with-JWT-token-is-invalid-Error).
**Solutions**
- dbt needs to retry connections to Snowflake.
- Confirm and enter Snowflake's public key correctly. Additionally, you can reach out to Snowflake for help or refer to this Snowflake doc for more info: [Key-Based Authentication Failed with JWT token is invalid Error](https://community.snowflake.com/s/article/Key-Based-Authentication-Failed-with-JWT-token-is-invalid-Error).

</details>
</detailsToggle>
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 586e701

Please sign in to comment.