Gestion des connexions Snowflake¶

Fichier de configuration alternatif¶

Snowflake CLI prend également en charge le fichier de configuration connections.toml. Le fichier doit être placé dans le même répertoire que le fichier config.toml et ne doit contenir que des connexions. Les configurations dans connections.toml nécessitent un nom de section différent, sans connections. Par exemple, (connections.myconnection) serait juste (myconnection).

Ajouter une connexion¶

Pour créer une nouvelle connexion et l’ajouter au fichier de configuration, procédez comme suit :

1. Exécutez la commande snow connection add :

   snow connection add
   

   Copy

2. Lorsque vous y êtes invité, fournissez les paramètres de connexion, de compte et de nom d’utilisateur requis, ainsi que tous les autres paramètres facultatifs souhaités.

   Enter connection name: <connection_name>
   Enter account: <account>
   Enter user: <user-name>
   Enter password: <password>
   Enter role: <role-name>
   Enter warehouse: <warehouse-name>
   Enter database: <database-name>
   Enter schema: <schema-name>
   Enter host: <host-name>
   Enter port: <port-number>
   Enter region: <region-name>
   Enter authenticator: <authentication-method>
   Enter private key file: <path-to-private-key-file>
   Enter token file path: <path-to-mfa-token>
   Do you want to configure key pair authentication? [y/N]: y
   Key length [2048]: <key-length>
   Output path [~/.ssh]: <path-to-output-file>
   Private key passphrase: <key-description>
   Wrote new connection <connection-name> to config.toml
   

Vous pouvez également ajouter des valeurs pour des paramètres spécifiques sur la ligne de commande, comme indiqué :

snow --config-file config.toml connection add -n myconnection2 --account myaccount2 --user jdoe2

Par défaut, la commande snow connection add demande des paramètres optionnels s’ils ne sont pas spécifiés sur la ligne de commande. Si vous souhaitez ajouter des connexions sans spécifier de paramètre facultatif comme account et ignorer les invites interactives, vous pouvez utiliser l’option --no-interactive, comme indiqué :

snow connection add -n myconnection2 --user jdoe2 --no-interactive

Après avoir ajouté une connexion, vous pouvez tester la connexion pour vous assurer qu’elle fonctionne correctement.

Lister les connexions définies¶

Pour lister les connexions disponibles, entrez la commande snow connection list, comme indiqué :

snow connection list

+-------------------------------------------------------------------------------------------------+
| connection_name | parameters                                                       | is_default |
|-----------------+------------------------------------------------------------------+------------|
| myconnection    | {'account': 'myaccount', 'user': 'jondoe', 'password': '****',   | False      |
|                 | 'database': 'my_db', 'schema': 'my_schema', 'warehouse':         |            |
|                 | 'my-wh'}                                                         |            |
| myconnection2   | {'account': 'myaccount2', 'user': 'jdoe2'}                       | False      |
+-------------------------------------------------------------------------------------------------+

Tester et diagnostiquer une connexion¶

Pour tester si une connexion peut se connecter avec succès à Snowflake, entrez la commande snow connection test, semblable à la suivante :

snow connection test -c myconnection2

+--------------------------------------------------+
| key             | value                          |
|-----------------+--------------------------------|
| Connection name | myconnection2                  |
| Status          | OK                             |
| Host            | example.snowflakecomputing.com |
| Account         | myaccount2                     |
| User            | jdoe2                          |
| Role            | ACCOUNTADMIN                   |
| Database        | not set                        |
| Warehouse       | not set                        |
+--------------------------------------------------+

Si vous rencontrez des problèmes de connectivité, vous pouvez effectuer des diagnostics directement dans Snowflake CLI. L’assistance Snowflake peut également demander ces informations pour vous aider à résoudre les problèmes de connectivité.

La collection de diagnostics utilise les options de commande suivantes snow connection test :

• --enable-diag pour générer un rapport de diagnostic.

• --diag-log-path pour spécifier le chemin absolu du rapport généré.

• --diag-allowlist-path pour spécifier le chemin absolu vers un fichier JSON contenant la sortie des commandes SYSTEM$ALLOWLIST() or SYSTEM$ALLOWLIST_PRIVATELINK() SQL. Cette option n’est requise que si l’utilisateur défini dans la connexion n’a pas l’autorisation d’exécuter les fonctions de la liste d’autorisation du système ou si la connexion à l’URL du compte échoue.

L’exemple suivant génère un rapport de diagnostic pour la connexion myconnection2 et le stocke dans le fichier ~/report/SnowflakeConnectionTestReport.txt :

snow connection test -c myconnection2 --enable-diag --diag-log-path $(HOME)/report

+----------------------------------------------------------------------------+
| key                  | value                                               |
|----------------------+-----------------------------------------------------|
| Connection name      | myconnection2                                       |
| Status               | OK                                                  |
| Host                 | example.snowflakecomputing.com                      |
| Account              | myaccount2                                          |
| User                 | jdoe2                                               |
| Role                 | ACCOUNTADMIN                                        |
| Database             | not set                                             |
| Warehouse            | not set                                             |
| Diag Report Location | /Users/<username>/SnowflakeConnectionTestReport.txt |
+----------------------------------------------------------------------------+

Vous pouvez consulter le rapport pour tout problème de connectivité et en discuter avec votre équipe réseau. Vous pouvez également fournir le rapport à l’assistance de Snowflake pour obtenir une assistance supplémentaire.

Définir la connexion par défaut¶

Vous pouvez utiliser la commande snow connection set-default pour spécifier quelle configuration de Snowflake CLI devrait être utilisée par défaut, en remplaçant le fichier de configuration default_connection_name et les variables SNOWFLAKE_DEFAULT_CONNECTION_NAME, si définies.

L’exemple suivant définit la connexion par défaut sur myconnection2 :

snow connection set-default myconnection2

Default connection set to: myconnection2

Utiliser des variables d’environnement pour les identifiants de connexion Snowflake¶

Vous pouvez spécifier les identifiants de connexion de Snowflake dans les variables d’environnement du système plutôt que dans les fichiers de configuration. Vous pouvez utiliser les variables d’environnement génériques suivantes uniquement pour spécifier les paramètres de connexion :

• SNOWFLAKE_ACCOUNT

• SNOWFLAKE_USER

• SNOWFLAKE_PASSWORD

• SNOWFLAKE_DATABASE

• SNOWFLAKE_SCHEMA

• SNOWFLAKE_ROLE

• SNOWFLAKE_WAREHOUSE

• SNOWFLAKE_AUTHENTICATOR

• SNOWFLAKE_PRIVATE_KEY_PATH

• SNOWFLAKE_PRIVATE_KEY_RAW

• SNOWFLAKE_SESSION_TOKEN

• SNOWFLAKE_MASTER_TOKEN

• SNOWFLAKE_TOKEN_FILE_PATH

• SNOWFLAKE_OAUTH_CLIENT_ID

• SNOWFLAKE_OAUTH_CLIENT_SECRET

• SNOWFLAKE_OAUTH_AUTHORIZATION_URL

• SNOWFLAKE_OAUTH_TOKEN_REQUEST_URL

• SNOWFLAKE_OAUTH_REDIRECT_URI

• SNOWFLAKE_OAUTH_SCOPE

• SNOWFLAKE_OAUTH_DISABLE_PKCE

• SNOWFLAKE_OAUTH_ENABLE_REFRESH_TOKENS

• SNOWFLAKE_OAUTH_ENABLE_SINGLE_USE_REFRESH_TOKENS

• SNOWFLAKE_CLIENT_STORE_TEMPORARY_CREDENTIAL

Transmettez les paramètres de connexion à la commande snow¶

Vous pouvez transmettre des paramètres de connexion directement dans chaque commande snow qui nécessite une connexion. Pour une liste complète des paramètres de configuration de connexion, exécutez la commande snow sql --help, comme indiqué. Notez que la sortie affiche uniquement la section avec les options de configuration de connexion.

snow sql --help

╭─ Connection configuration ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --connection,--environment             -c      TEXT     Name of the connection, as defined in your config.toml. Default: default.
│ --host                                         TEXT     Host address for the connection. Overrides the value specified for the connection.
│ --port                                         INTEGER  Port for the connection. Overrides the value specified for the connection.
│ --account,--accountname                        TEXT     Name assigned to your Snowflake account. Overrides the value specified for the connection.
│ --user,--username                              TEXT     Username to connect to Snowflake. Overrides the value specified for the connection.
│ --password                                     TEXT     Snowflake password. Overrides the value specified for the connection.
│ --authenticator                                TEXT     Snowflake authenticator. Overrides the value specified for the connection.
│ --private-key-file,--private-key-path          TEXT     Snowflake private key file path. Overrides the value specified for the connection.
│ --token-file-path                              TEXT     Path to file with an OAuth token that should be used when connecting to Snowflake.
│ --database,--dbname                            TEXT     Database to use. Overrides the value specified for the connection.
│ --schema,--schemaname                          TEXT     Database schema to use. Overrides the value specified for the connection.
│ --role,--rolename                              TEXT     Role to use. Overrides the value specified for the connection.
│ --warehouse                                    TEXT     Warehouse to use. Overrides the value specified for the connection.
│ --temporary-connection                 -x               Uses connection defined with command line parameters, instead of one defined in config.
│ --mfa-passcode                                 TEXT     Token to use for multi-factor authentication (MFA).
│ --oauth-client-id                              TEXT     Value of the client ID provided by the identity provider for Snowflake integration.
│ --oauth-client-secret                          TEXT     Value of the client secret provided by the identity provider for Snowflake integration.
│ --oauth-authorization-url                      TEXT     Identity provider endpoint supplying the authorization code to the driver.
│ --oauth-token-request-url                      TEXT     Identity provider endpoint supplying the access tokens to the driver.
│ --oauth-redirect-uri                           TEXT     URI to use for the authorization code.
│ --oauth-scope                                  TEXT     Scope requested in the identity provider authorization request.
│ --oauth-disable-pkce                                    Disables Proof Key for Code Exchange (PKCE). Default: False.
│ --oauth-enable-refresh-tokens                           Enables a silent re-authentication when the actual access token becomes outdated. Default: False.
│ --oauth-enable-single-use-refresh-tokens                Whether to opt in to single-use refresh token semantics. Default: False.
│ --client-store-temporary-credential                     Store the temporary credential.
│ --enable-diag                                           Run the python connector diagnostic test.
│ --diag-log-path                                TEXT     Diagnostic report path.
│ --diag-allowlist-path                          TEXT     Diagnostic report path to optional allowlist.
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Utiliser un fichier de clé privée pour l’authentification¶

Pour utiliser un fichier de clé privée pour l’authentification, la configuration de votre connexion exige que vous définissiez la valeur du paramètre authenticator sur SNOWFLAKE_JWT et que vous indiquiez le chemin d’accès au fichier contenant votre clé privée, comme indiqué ci-dessous :

• Précisez l’option --private_key-file dans la commande snow connection add, comme indiqué :

  snow connection add \
     --connection-name jwt \
     --authenticator SNOWFLAKE_JWT \
     --private-key-file ~/.ssh/sf_private_key.p8
  

  Copy

• Utilisez le fichier de configuration :

  [connections.jwt]
  account = "my_account"
  user = "jdoe"
  authenticator = "SNOWFLAKE_JWT"
  private_key_file = "~/sf_private_key.p8"
  

  Copy

Pour plus de détails sur la configuration de l’authentification par paire de clés, voir Authentification par paire de clés et rotation de paires de clés.

Snowflake CLI recherche la clé privée dans les paramètres de connexion dans l’ordre suivant :

1. Si private_key_file est spécifié, Snowflake CLI lit la clé dans le chemin du fichier spécifié.

2. Si private_key_path est spécifié, Snowflake CLI lit la clé dans le chemin du fichier spécifié.

3. Si private_key_file ou private_key_path ne sont pas spécifiés, Snowflake CLI lit la clé directement à partir du paramètre private_key_raw.

Utiliser l’authentification OAuth¶

Pour l’utiliser en vous connectant avec OAuth, vous pouvez effectuer l’une des opérations suivantes :

• Précisez l’option --token-file-path dans la commande snow connection add, comme indiqué :

  snow connection add --token-file-path "my-token.txt"
  

  Copy

• Dans le fichier config.toml, définissez authenticator = "oauth", et ajoutez le paramètre token_file_path à la définition de connexion, comme indiqué :

  [connections.oauth]
  account = "my_account"
  user = "jdoe"
  authenticator = "oauth"
  token_file_path = "my-token.txt"
  

  Copy

Utiliser le flux du code d’autorisation OAuth 2.0¶

Le flux du code d’autorisation OAuth 2.0 est une méthode sécurisée permettant à une application client d’obtenir un jeton d’accès auprès d’un serveur d’autorisation au nom d’un utilisateur, sans révéler les identifiants de l’utilisateur. Pour plus d’informations sur ce flux et ses paramètres, voir Activer le flux du code d’autorisation OAuth 2.0 dans la documentation Snowflake Connector pour Python.

Pour utiliser le flux du code d’autorisation OAuth 2.0, ajoutez à votre fichier config.toml une définition de connexion similaire à la suivante :

[connections.oauth]
authenticator = "OAUTH_AUTHORIZATION_CODE"
user = "user"
account = "account"
oauth_client_id = "client_id"
oauth_client_secret = "client_secret"
oauth_redirect_uri = "http://localhost:8001/snowflake/oauth-redirect"
oauth_scope = "session:role:PUBLIC"

Utiliser le flux d’identifiants de connexion client OAuth 2.0¶

Le flux d’identifiants de connexion client OAuth 2.0 fournit un moyen sûr pour l’authentification de machine à machine (M2M), comme Snowflake Connector pour Python qui se connecte à un service backend. Contrairement au flux du code d’autorisation OAuth 2.0, cette méthode ne s’appuie sur aucune donnée propre à l’utilisateur. Pour plus d’informations sur ce flux et ses paramètres, voir Activer le flux d’identifiants de connexion client OAuth 2.0 dans la documentation Snowflake Connector pour Python.

Pour utiliser le flux d’identifiants de connexion client OAuth 2.0, ajoutez à votre fichier config.toml une définition de connexion similaire à la suivante :

[connections.oauth]
authenticator = "OAUTH_CLIENT_CREDENTIALS"
user = "user"
account = "account"
oauth_client_id = "client_id"
oauth_client_secret = "client_secret"
oauth_token_request_url = "http://identity.provider.com/token"
oauth_scope = "session:role:PUBLIC"

Utiliser l’authentification multifactorielle (MFA)¶

Pour utiliser MFA :

1. Configurez l”authentification multifactorielle dans Snowflake et définissez le paramètre authenticator sur snowflake (qui est une valeur par défaut).

2. Si vous souhaitez utiliser un code d’accès généré par Duo au lieu du mécanisme Push, utilisez l’option --mfa-passcode <passcode> ou définissez passcode_in_password = true dans le fichier config.toml et incluez le code d’accès dans votre mot de passe comme décrit dans Utilisation de la MFA avec Python.

   Note

   Si vous souhaitez utiliser le code d’accès dans le mot de passe pour l’authentification, après l’exécution de la première commande snow, vous ne pouvez plus fournir le code d’accès tant que le jeton est valide. Vous devez procéder comme suit :

   • Supprimez le code d’accès du mot de passe.

   • Supprimez ou commentez le passcode_in_password = true dans le fichier config.toml.

Utiliser la mise en cache MFA¶

La mise en cache MFA est une fonction de sécurité qui réduit la fréquence des invites de l’authentification multifactorielle (MFA) lors des connexions. Les invites MFA fréquentes peuvent perturber le flux de travail et diminuer la productivité. La mise en cache MFA résout ce problème en stockant en toute sécurité les informations de session MFA pendant une période donnée. L’utilisation de la mise en cache MFA vous permet de vous authentifier sans avoir à saisir plusieurs fois les codes MFA, pour autant qu’ils se situent dans la période de validité de la session mise en cache.

Pour activer la mise en cache de MFA :

1. Pour votre compte, définissez ALLOW_CLIENT_MFA_CACHING = true.

2. Dans votre fichier config.toml, ajoutez authenticator = "username_password_mfa" à votre connexion.

Pour plus d’informations, voir Utilisation de la mise en cache des jetons MFA pour réduire le nombre d’invites lors de l’authentification — Facultatif.

Utiliser SSO (authentification unique)¶

Si vous avez configuré Snowflake pour utiliser la connexion unique (SSO), vous pouvez configurer votre application cliente pour utiliser SSO pour l’authentification. Voir Utilisation de SSO avec des applications clientes qui se connectent à Snowflake pour plus de détails et configurez votre connexion à l’aide des instructions pour Python.

Utiliser un navigateur externe¶

Vous pouvez utiliser votre navigateur pour authentifier votre connexion Snowflake CLI avec n’importe quel fournisseur d’identité conforme à SAML 2.0 (IdP), comme Okta ou Active Directory Federation Services.

Pour utiliser l’authentification externe du navigateur, utilisez l’une des méthodes suivantes :

• Utilisez l’option de commande snow connection add --authenticator :

  snow connection add --authenticator externalbrowser
  

  Copy

• Définissez l”authentificateur :codenowrap: sur externalbrowser dans votre fichier config.toml :

  [connections.externalbrowser]
  account = "my_account"
  user = "jdoe"
  authenticator = "externalbrowser"
  

  Copy

Utiliser PAT (jeton d’accès programmatique)¶

Le jeton d’accès programmatique (PAT) est une méthode d’authentification spécifique à Snowflake. La fonction doit être activée pour le compte avant son utilisation (voir Conditions préalables pour plus d’informations). L’authentification avec PAT n’implique aucune interaction humaine.

Pour utiliser PAT avec la connexion, définissez authenticator sur PROGRAMMATIC_ACCESS_TOKEN et token_file_path pour pointer le fichier avec le jeton, comme indiqué :

[connections.externalbrowser]
account = "my_account"
user = "jdoe"
authenticator = "PROGRAMMATIC_ACCESS_TOKEN"
token_file_path = "path-to-pat-token"

Pour plus d’informations sur les PATs, voir Utilisation de jetons d’accès programmatique pour l’authentification.