Konfigurieren des JDBC-Treibers

.

Verwandte Themen

• SnowCD (Connectivity Diagnostic Tool)

Unter diesem Thema wird beschrieben, wie der JDBC-Treiber konfiguriert wird, einschließlich des Verbindens mit Snowflake mithilfe des Treibers.

Unter diesem Thema:

JDBC-Treiberklasse

Verwenden Sie net.snowflake.client.jdbc.SnowflakeDriver als Treiberklasse in Ihrer JDBC-Anwendung.

Bemerkung

• Verweisen Sie in Ihrem Anwendungscode nicht auf andere Snowflake-Klassen oder -Methoden, da diese in Zukunft geändert werden können, um Verbesserungen und Korrekturen zu implementieren.

• Die vorherige Treiberklasse com.snowflake.client.jdbc.SnowflakeDriver wird weiterhin unterstützt, ist aber veraltet (d. h. sie wird in einer zukünftigen Version entfernt, TBD). Daher funktioniert jeder Code, der auf den vorherigen Klassennamen verweist, auch weiterhin. Sie sollten aber nach Implementierung der Änderung den Code aktualisieren, um auf den neuen Klassennamen zu verweisen.

Verbindungszeichenfolge für den JDBC-Treiber

Die Verwendung des JDBC-Treibers zur Verbindung mit Snowflake erfordert eine Verbindungszeichenfolge mit der folgenden Syntax.

Syntax

jdbc:snowflake://<account_name>.snowflakecomputing.com/?<connection_params>

Verbindungsparameter

<Kontoname>

Gibt den vollen Namen Ihres Kontos an (bereitgestellt von Snowflake). Beachten Sie, dass Ihr vollständiger Kontoname möglicherweise zusätzliche Segmente enthält, die die Region und die Cloudplattform angeben, wo Ihr Konto gehostet wird.

Beispiele für Kontonamen nach Region

Wenn Ihr Kontoname beispielsweise xy12345 ist:

Cloudplattform/Region	Vollständiger Kontoname
AWS
US West (Oregon)	xy12345
US East (Ohio)	xy12345.us-east-2.aws
US East (N. Virginia)	xy12345.us-east-1
US East (Commercial Gov - N. Virginia)	xy12345.us-east-1-gov.aws
Canada (Central)	xy12345.ca-central-1.aws
EU (Irland)	xy12345.eu-west-1
EU (Frankfurt)	xy12345.eu-central-1
Asia Pacific (Tokio)	xy12345.ap-northeast-1.aws
Asia Pacific (Mumbai)	xy12345.ap-south-1.aws
Asia Pacific (Singapur)	xy12345.ap-southeast-1
Asia Pacific (Sydney)	xy12345.ap-southeast-2
GCP
US Central1 (Iowa)	xy12345.us-central1.gcp
Europe West2 (London)	xy12345.europe-west2.gcp
Europe West4 (Niederlande)	xy12345.europe-west4.gcp
Azure
West US 2 (Washington)	xy12345.west-us-2.azure
East US 2 (Virginia)	xy12345.east-us-2.azure
US Gov Virginia	xy12345.us-gov-virginia.azure
Canada Central (Toronto)	xy12345.canada-central.azure
West Europe (Niederlande)	xy12345.west-europe.azure
Switzerland North (Zürich)	xy12345.switzerland-north.azure
Southeast Asia (Singapur)	xy12345.southeast-asia.azure
Australia East (New South Wales)	xy12345.australia-east.azure

Wichtig

Wenn eine der folgenden Bedingungen zutrifft, unterscheidet sich Ihr Kontoname von der oben beschriebenen Struktur:

• Wenn Ihre Snowflake Edition VPS ist, wenden Sie sich an den Snowflake-Support, um Details zu Ihrem Kontonamen zu erhalten.

• Wenn für Ihr Konto AWS PrivateLink aktiviert ist, muss der Kontoname ein zusätzliches privatelink-Segment enthalten. Weitere Details dazu finden Sie unter AWS PrivateLink & Snowflake.

<Regions-ID> – Veraltet

Gibt die ID für die Region an, in der sich Ihr Konto befindet.

Dieser Parameter wird nicht mehr verwendet, da die Regionsinformationen, falls erforderlich, Teil des vollständigen Kontonamens sind. Sie ist hier nur aus Gründen der Abwärtskompatibilität dokumentiert.

<Verbindungsparameter>

Gibt eine Reihe von einem oder mehreren Parametern in Form von <Parameter>=<Wert> an, wobei jeder Parameter durch das kaufmännische Und-Zeichen (&) getrennt ist und keine Leerzeichen in der Verbindungszeichenfolge vorhanden sind:

user=<Anmeldename>

Gibt den Anmeldenamen des Benutzers für die Verbindung an.

password=<Zeichenfolge>

Gibt das Kennwort für den angegebenen Benutzer an.

Es gibt zwei Möglichkeiten, das Kennwort anzugeben:

• Die erste Möglichkeit besteht darin, Benutzer-ID und Kennwort direkt an die getConnection-Methode zu übergeben:

  String user = "<user>";          // replace "<user>" with your user name
  String password = "<password>";  // replace "<password>" with your password
  Connection con = DriverManager.getConnection("jdbc:snowflake://<account>.snowflakecomputing.com/", user, password);
  

• Die zweite Möglichkeit besteht darin, ein Properties-Objekt zu erstellen, das Objekt mit dem Kennwort zu aktualisieren und das Objekt an die getConnection-Methode zu übergeben:

  String user = "<user>";          // replace "<user>" with your user name
  String password = "<password>";  // replace "<password>" with your password
  Properties props = new Properties();
  props.put("user", user);
  props.put("password", password);
  Connection con = DriverManager.getConnection("jdbc:snowflake://<account>.snowflakecomputing.com/", props);
  

Achtung

Wir empfehlen dringend, dass Sie das Benutzerkennwort nicht direkt in die JDBC-Verbindungszeichenfolge aufnehmen, da das Kennwort versehentlich von der Clientanwendung, die die Zeichenfolge für die Verbindung zu Snowflake verwendet, angezeigt werden könnte. Verwenden Sie stattdessen die von der Anwendung bereitgestellten Schnittstellen, um das Benutzerkennwort anzugeben.

authenticator=<Zeichenfolge>

Gibt den Authentifikator an, der für die Überprüfung der Anmeldeinformationen des Benutzers verwendet werden soll:

• snowflake, um den internen Snowflake-Authentifikator zu verwenden.

• externalbrowser to use your web browser to authenticate with Okta, ADFS, or any other SAML 2.0-compliant identity provider (IdP) that has been defined for your account.

• https://<Name_Ihres_Okta-Kontos>.okta.com (d. h. der URL-Endpunkt für Okta) zum Authentifizieren über das systemeigene Okta (nur unterstützt, wenn Ihr IdP Okta ist).

• oauth zum Authentifizieren mit OAuth. Wenn OAuth als Authentifikator angegeben ist, müssen Sie auch den Parameter token festlegen, um das OAuth-Token anzugeben (siehe unten).

• snowflake_jwt, um die Schlüsselpaar-Authentifizierung zu verwenden. Weitere Informationen zur Schlüsselpaarauthentifizierung finden Sie unter Verwenden der Schlüsselpaar-Authentifizierung.

Der Standardwert ist snowflake.

Wenn die Verbindungszeichenfolge ein Schlüsselpaar angibt, wird die Schlüsselpaarauthentifizierung auch dann verwendet, wenn der Authentifikatorparameter nicht festgelegt oder auf „snowflake“ gesetzt ist.

Weitere Informationen zur Authentifizierung finden Sie unter Verwenden und Verwalten der Verbundauthentifizierung und OAuth mit Clients, Treibern und Konnektoren.

token=<Zeichenfolge>

Gibt das OAuth-Token an, das für die Authentifizierung verwendet werden soll, wobei <Zeichenfolge> das Token ist. Dieser Parameter ist nur erforderlich, wenn der Parameter authenticator=oauth eingestellt ist.

Der Standardwert ist „none“.

role=<Name>

Gibt die Standardrolle für die Zugriffssteuerung an, die in der vom Treiber initiierten Snowflake-Sitzung verwendet werden soll. Die angegebene Rolle sollte eine bestehende Rolle sein, die dem angegebenen Benutzer des Treibers bereits zugeordnet wurde. Wenn die angegebene Rolle dem Benutzer noch nicht zugewiesen wurde, wird die Rolle nicht verwendet, wenn die Sitzung vom Treiber initiiert wird.

Nach dem Verbinden kann der Befehl USE ROLE ausgeführt werden, um eine andere Rolle für die Sitzung festzulegen.

Weitere Informationen zu Rollen und zur Zugriffssteuerung finden Sie unter Zugriffssteuerung in Snowflake.

db=<Name>

Gibt die Standarddatenbank an, die nach der Verbindung verwendet werden soll, oder eine leere Zeichenfolge. Die angegebene Datenbank sollte eine bestehende Datenbank sein, deren angegebene Standardrolle über entsprechende Berechtigungen verfügt.

Nach dem Verbinden kann der Befehl USE DATABASE ausgeführt werden, um eine andere Datenbank für die Sitzung festzulegen.

schema=<Name>

Gibt das Standardschema an, das nach dem Verbinden für die angegebene Datenbank verwendet werden soll, oder eine leere Zeichenfolge. Das angegebene Schema sollte ein bestehendes Schema sein, für das die angegebene Standardrolle über entsprechende Berechtigungen verfügt.

Nach dem Verbinden kann der Befehl USE SCHEMA ausgeführt werden, um ein anderes Schema für die Sitzung festzulegen.

warehouse=<Name>

Gibt das virtuelle Warehouse an, das nach dem Verbinden verwendet werden soll, oder eine leere Zeichenfolge. Das angegebene Warehouse sollte ein bestehendes Warehouse sein, für das die angegebene Standardrolle über entsprechende Berechtigungen verfügt.

Nach dem Verbinden kann der Befehl USE WAREHOUSE ausgeführt werden, um ein anderes Warehouse für die Sitzung festzulegen.

tracing=<Zeichenfolge>

Gibt den Protokolliergrad für den Treiber an. Der Treiber verwendet das Standard-Java-Protokolldienstprogramm. Gültige Werte für den Protokolliergrad sind:

OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL.

Der Standardwert ist INFO.

passcode=<Zeichenfolge>

Gibt die Kennung an, die für die mehrstufige Authentifizierung verwendet werden soll.

Weitere Informationen zur mehrstufigen Authentifizierung finden Sie unter Mehrstufige Authentifizierung (MFA).

passcodeInPassword=<Zeichenfolge>

Gibt an, ob die Kennung für die mehrstufige Authentifizierung an das Kennwort angehängt wird:

• on (oder true) gibt an, dass die Kennung angehängt wird.

• off (oder false) oder ein anderer Wert gibt an, dass die Kennung nicht angehängt wird.

Der Standardwert ist off.

loginTimeout

Gibt an, wie lange beim Herstellen einer Verbindung zum Snowflake-Service auf eine Antwort gewartet werden soll, bevor ein Anmeldefehler zurückgegeben wird.

Die Standardeinstellung ist 60 Sekunden.

networkTimeout

Gibt an, wie lange beim Interagieren mit dem Snowflake-Service auf eine Antwort gewartet werden soll, bevor ein Fehler zurückgegeben wird. Null (0) bedeutet, dass kein Netzwerk-Timeout eingestellt ist.

Der Standard ist 0 Sekunden.

queryTimeout=<Zahl>

Gibt an, wie lange auf das Ende einer Abfrage gewartet werden soll, bevor ein Fehler gemeldet wird. Null (0) bedeutet, dass Sie auf unbestimmte Zeit warten müssen.

Der Standard ist 0 Sekunden.

application=<Zeichenfolge>

Snowflake partner use only: Gibt den Namen einer Partneranwendung an, die über JDBC verbunden werden soll.

disableSocksProxy=<Zeichenfolge>

Gibt an, ob der Treiber die in den Java-Systemoptionen angegebene SOCKS-Proxy-Konfiguration ignorieren soll (falls vorhanden):

• on (oder true) gibt an, den Proxy zu ignorieren.

• off (oder false) oder ein anderer Wert gibt an, dass der Proxy verwendet werden soll.

Der Standardwert ist off.

Hinweis: Das Einstellen dieses Verbindungsparameters ändert das Verhalten für alle Verbindungen derselben JVM (Java Virtual Machine).

stringsQuotedForColumnDef=<Boolescher_Wert>

Wenn dieser Parameter auf true gesetzt ist und DatabaseMetaData.getColumns() und DatabaseMetaData.getProcedureColumns() einen Wert vom Typ String in der Spalte COLUMN_DEF zurückgeben, wird dieser Wert in einfache Anführungszeichen eingeschlossen. (Wenn der Datentyp des Werts nicht String ist, wird der Wert unabhängig von der Einstellung dieses Parameters nicht in Anführungszeichen gesetzt.)

• true gibt an, dass Zeichenfolgenwerte in einfache Anführungszeichen eingeschlossen werden sollen (die Anführungszeichen sind Teil der Zeichenfolge und keine Trennzeichen). Dies entspricht dem JDBC-Standard.

• false gibt an, dass Zeichenfolgenwerte nicht in einfache Anführungszeichen eingeschlossen werden.

Der Standardwert ist false.

Weitere Parameter

Jeder Sitzungsparameter kann in die Verbindungszeichenfolge aufgenommen werden. Beispiel:

CLIENT_SESSION_KEEP_ALIVE=<Boolesch>

Gibt an, ob die aktuelle Sitzung nach einer Zeit der Inaktivität aktiv bleiben soll oder ob der Benutzer gezwungen werden soll, sich erneut anzumelden. Wenn der Wert true ist, hält Snowflake die Sitzung auf unbestimmte Zeit aktiv, auch wenn es keine Aktivität des Benutzers gibt. Wenn der Wert false ist, muss sich der Benutzer nach vier Stunden Inaktivität erneut anmelden.

Der Standardwert ist false.

Eine Beschreibung aller Sitzungsparameter finden Sie unter Parameter.

Beispiele

Konto in US West:

jdbc:snowflake://xy12345.snowflakecomputing.com/?user=peter&warehouse=mywh&db=mydb&schema=public

Konto in EU (Frankfurt):

jdbc:snowflake://xy12345.eu-central-1.snowflakecomputing.com/?user=peter&warehouse=mywh&db=mydb&schema=public

Verwenden von Single Sign-On (SSO) zur Authentifizierung

Wenn Sie Snowflake für die Verwendung von Single Sign-On (SSO) konfiguriert haben, können Sie Ihre Clientanwendung so konfigurieren, dass SSO für die Authentifizierung verwendet wird. Weitere Informationen dazu finden Sie unter Verwenden von SSO bei Clientanwendungen, die sich mit Snowflake verbinden.

Verwenden der Schlüsselpaar-Authentifizierung

Snowflake unterstützt die Verwendung von Schlüsselpaar-Authentifizierung anstelle der typischen Authentifizierung durch Benutzernamen und Kennwort. Dieses Authentifizierungsverfahren erfordert ein 2048-Bit-RSA-Schlüsselpaar (Minimum). Generieren Sie das Public/Private-Schlüsselpaar mit OpenSSL. Der öffentliche Schlüssel wird dem Snowflake-Benutzer zugewiesen, der den Snowflake-Client verwendet.

So konfigurieren Sie das Public/Private-Schlüsselpaar:

1. Generieren Sie über die Befehlszeile in einem Terminalfenster einen privaten Schlüssel:

   Sie können entweder eine verschlüsselte Version des privaten Schlüssels oder eine unverschlüsselte Version des privaten Schlüssels generieren.

   Um eine unverschlüsselte Version zu generieren, verwenden Sie den folgenden Befehl:

   $ openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
   

   Um eine verschlüsselte Version zu generieren, verwenden Sie den folgenden Befehl (ohne „-nocrypt“):

   $ openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8
   

   Es ist normalerweise sicherer, eine verschlüsselte Version zu erstellen.

   Wenn Sie den zweiten Befehl zum Verschlüsseln des privaten Schlüssels verwenden, fordert OpenSSL Sie zur Eingabe einer Passphrase auf, die zum Verschlüsseln der Datei des privaten Schlüssels verwendet wird. Wir empfehlen, zum Schutz des privaten Schlüssels eine starke Passphrase zu verwenden. Notieren Sie sich diese Passphrase an einem sicheren Ort. Sie müssen sie beim Herstellen der Verbindung mit Snowflake eingeben. Beachten Sie, dass die Passphrase nur zum Schutz des privaten Schlüssels verwendet wird und niemals an Snowflake gesendet wird.

   Beispiel für einen privaten PEM-Schlüssel

   -----BEGIN ENCRYPTED PRIVATE KEY-----
   MIIE6TAbBgkqhkiG9w0BBQMwDgQILYPyCppzOwECAggABIIEyLiGSpeeGSe3xHP1
   wHLjfCYycUPennlX2bd8yX8xOxGSGfvB+99+PmSlex0FmY9ov1J8H1H9Y3lMWXbL
   ...
   -----END ENCRYPTED PRIVATE KEY-----
   

2. Generieren Sie über die Befehlszeile den öffentlichen Schlüssel, indem Sie auf den privaten Schlüssel verweisen:

   Angenommen, der private Schlüssel befindet sich in der Datei „rsa_key.p8“, verwenden Sie den folgenden Befehl:

   $ openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
   

   Beispiel für einen öffentlichen PEM-Schlüssel

   -----BEGIN PUBLIC KEY-----
   MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy+Fw2qv4Roud3l6tjPH4
   zxybHjmZ5rhtCz9jppCV8UTWvEXxa88IGRIHbJ/PwKW/mR8LXdfI7l/9vCMXX4mk
   ...
   -----END PUBLIC KEY-----
   

3. Kopieren Sie die Dateien der öffentlichen und privaten Schlüssel zur Speicherung in einem lokalen Verzeichnis. Zeichnen Sie den Pfad zu den Dateien auf. Beachten Sie, dass der private Schlüssel im Format PKCS#8 (Public Key Cryptography Standards) gespeichert und mit der im vorherigen Schritt angegebenen Passphrase verschlüsselt wird; die Datei sollte jedoch weiterhin mit dem von Ihrem Betriebssystem bereitgestellten Dateiberechtigungsmechanismus vor unbefugtem Zugriff geschützt sein. Es liegt in Ihrer Verantwortung, die Datei zu sichern, wenn sie nicht verwendet wird.

4. Weisen Sie dem Snowflake-Benutzer den öffentlichen Schlüssel mit ALTER USER zu. Beispiel:

   ALTER USER jsmith SET RSA_PUBLIC_KEY='MIIBIjANBgkqh...';
   

   Bemerkung

   • Nur Sicherheitsadministratoren (d. h. Benutzer mit der Rolle SECURITYADMIN oder höher) können andere Benutzer ändern.

   • Schließen Sie die Kopf- und Fußzeile des öffentlichen Schlüssels in der SQL-Anweisung aus.

   Überprüfen Sie den Fingerabdruck des öffentlichen Schlüssels des Benutzers mithilfe von DESCRIBE USER:

   DESC USER jsmith;
   +-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------+
   | property                      | value                                               | default | description                                                                   |
   |-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------|
   | NAME                          | JSMITH                                              | null    | Name                                                                          |
   ...
   ...
   | RSA_PUBLIC_KEY_FP             | SHA256:nvnONUsfiuycCLMXIEWG4eTp4FjhVUZQUQbNpbSHXiA= | null    | Fingerprint of user's RSA public key.                                         |
   | RSA_PUBLIC_KEY_2_FP           | null                                                | null    | Fingerprint of user's second RSA public key.                                  |
   +-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------+
   

   Bemerkung

   Die RSA_PUBLIC_KEY_2_FP-Eigenschaft wird unter Schlüsselrotation (unter diesem Thema) beschrieben.

5. Nachdem Sie das private Schlüsselpaar erstellt haben, können Sie es beim Herstellen einer Verbindung mit Snowflake zur Authentifizierung verwenden.

   Sie können den Wert des privaten Schlüssels direkt verwenden oder den privaten Schlüssel in einer Datei speichern und den Dateinamen und ein Kennwort für diese Datei übergeben, wenn Sie eine Verbindung herstellen:

   1. Geben Sie den privaten Schlüssel über die Eigenschaft „privateKey“ in den Verbindungseigenschaften an.

   2. Geben Sie den Dateinamen und das Kennwort des privaten Schlüssels als separate Eigenschaften in den Verbindungseigenschaften an.

   3. Geben Sie den Dateinamen und das Kennwort des privaten Schlüssels als Teil der Verbindungszeichenfolge an.

Jede davon wird in einem der nächsten drei Abschnitte ausführlicher beschrieben.

privateKey-Eigenschaft in Verbindungseigenschaften

Ändern Sie den unten stehenden Beispielcode, und führen Sie ihn aus. Der Code entschlüsselt die Datei, die den privaten Schlüssel enthält, und übergibt sie an den Snowflake-Treiber, um eine Verbindung herzustellen: Aktualisieren Sie im Beispielcode die Sicherheitsparameter und die Sitzungsparameter:

• Sicherheitsparameter:

  • Pfad: Gibt den lokalen Pfad zu der von Ihnen erstellten Datei mit dem privaten Schlüssel an.

• Sitzungsparameter:

  • Benutzer: Gibt Ihren Snowflake-Anmeldenamen an.

  • Konto: Gibt den Namen Ihres Kontos an (bereitgestellt von Snowflake).

Beispielcode

import java.util.Properties;
import java.sql.Connection;
import java.sql.Statement;
import java.sql.ResultSet;
import java.sql.DriverManager;
import java.io.File;
import java.io.FileInputStream;
import java.io.DataInputStream;
import java.util.Base64;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.KeyFactory;
import java.security.PrivateKey;
import javax.crypto.EncryptedPrivateKeyInfo;
import javax.crypto.SecretKeyFactory;
import javax.crypto.spec.PBEKeySpec;

public class TestJdbc
{
    public static void main(String[] args)
        throws Exception
    {
      File f = new File("<path>/rsa_key.p8");
      FileInputStream fis = new FileInputStream(f);
      DataInputStream dis = new DataInputStream(fis);
      byte[] keyBytes = new byte[(int) f.length()];
      dis.readFully(keyBytes);
      dis.close();

      String encrypted = new String(keyBytes);
      String passphrase = System.getenv("PRIVATE_KEY_PASSPHRASE");
      encrypted = encrypted.replace("-----BEGIN ENCRYPTED PRIVATE KEY-----", "");
      encrypted = encrypted.replace("-----END ENCRYPTED PRIVATE KEY-----", "");
      EncryptedPrivateKeyInfo pkInfo = new EncryptedPrivateKeyInfo(Base64.getMimeDecoder().decode(encrypted));
      PBEKeySpec keySpec = new PBEKeySpec(passphrase.toCharArray());
      SecretKeyFactory pbeKeyFactory = SecretKeyFactory.getInstance(pkInfo.getAlgName());
      PKCS8EncodedKeySpec encodedKeySpec = pkInfo.getKeySpec(pbeKeyFactory.generateSecret(keySpec));
      KeyFactory keyFactory = KeyFactory.getInstance("RSA");
      PrivateKey encryptedPrivateKey = keyFactory.generatePrivate(encodedKeySpec);

      String url = "jdbc:snowflake://<account>.snowflakecomputing.com";
      Properties prop = new Properties();
      prop.put("user", "<user>");
      prop.put("account", "<account>");
      prop.put("privateKey", encryptedPrivateKey);

      Connection conn = DriverManager.getConnection(url, prop);
      Statement stat = conn.createStatement();
      ResultSet res = stat.executeQuery("select 1");
      res.next();
      System.out.println(res.getString(1));
      conn.close();
    }
}

Dateiname und Kennwort des privaten Schlüssels als Verbindungseigenschaften

Sie können den Dateinamen und das Kennwort des privaten Schlüssels als separate Verbindungseigenschaften angeben. Beispiel:

Properties props = new Properties();
props.put("private_key_file", "/tmp/rsa_key.p8");
props.put("private_key_file_pwd", "dummyPassword");
Connection connection = DriverManager.getConnection(properties, "jdbc:snowflake://exampleaccount.snowflake.com");

Wenn Sie die Parameter private_key_file und private_key_file_pwd angeben, geben Sie den Parameter privateKey nicht in den Verbindungseigenschaften an.

Dateiname und Kennwort des privaten Schlüssels in der Verbindungszeichenfolge

Sie können den Dateinamen und das Kennwort des privaten Schlüssels in der Verbindungszeichenfolge wie folgt angeben:

Connection connection = DriverManager.getConnection(properties,
    "jdbc:snowflake://exampleaccount.snowflake.com/?private_key_file=/tmp/rsa_key.p8&private_key_file_pwd=dummyPassword");

Wenn Sie den privaten Schlüssel und das Kennwort in der Verbindungszeichenfolge angeben, geben Sie die Parameter private_key_file, private_key_file_pwd oder privateKey nicht in den Verbindungseigenschaften an.

Schlüsselrotation

Snowflake unterstützt mehrere aktive Schlüssel, um eine ununterbrochene Rotation zu ermöglichen. Rotieren und ersetzen Sie Ihre öffentlichen und privaten Schlüssel basierend auf dem Ablaufzeitplan, den Sie intern einhalten.

Derzeit können Sie die Parameter RSA_PUBLIC_KEY und RSA_PUBLIC_KEY_2 für ALTER USER verwenden, um einem einzelnen Benutzer bis zu zwei öffentliche Schlüssel zuzuordnen.

So rotieren Sie Ihre Schlüssel:

1. Führen Sie die unter Verwenden der Schlüsselpaar-Authentifizierung angegebenen Schritte aus, um Folgendes zu ermöglichen:

   • Generieren eines neuen privaten und öffentlichen Schlüsselsatzes

   • Zuweisen des öffentlichen Schlüssels an einen Benutzer Setzen Sie den Wert des öffentlichen Schlüssels entweder auf RSA_PUBLIC_KEY oder RSA_PUBLIC_KEY_2 (je nachdem, welcher Schlüsselwert gerade nicht verwendet wird). Beispiel:

     alter user jsmith set rsa_public_key_2='JERUEHtcve...';
     

2. Aktualisieren Sie den Code, um eine Verbindung zu Snowflake herzustellen. Geben Sie den neuen privaten Schlüssel an.

   Snowflake überprüft den korrekten aktiven öffentlichen Schlüssel für die Authentifizierung basierend auf dem privaten Schlüssel, der mit Ihren Verbindungsinformationen übermittelt wurde.

3. Entfernen Sie den alten öffentlichen Schlüssel aus dem Benutzerprofil. Beispiel:

   alter user jsmith unset rsa_public_key;
   

Überprüfen der Netzwerkverbindung zu Snowflake mit SnowCD

Nach der Konfiguration des Treibers können Sie die Netzwerkkonnektivität zu Snowflake mit SnowCD testen und Probleme beheben.

Sie können während der Erstkonfiguration und bei Bedarf jederzeit SnowCD verwenden, um Ihre Netzwerkverbindung zu Snowflake zu testen und Probleme zu beheben.

Verbinden über einen Proxyserver

Es gibt zwei Möglichkeiten, mit dem Snowflake JDBC-Treiber einen Proxyserver zu verwenden:

• Fügen Sie den JVM (Java Virtual Machine)-Optionen Ihrer Clientanwendung Parameter hinzu.

• Fügen Sie die Proxyhost- und Port-Informationen in die JDBC-Verbindungszeichenfolge oder die an die DriverManager .getConnection ()-Methode übergebenen Eigenschaften ein.

Beide Techniken sind im Folgenden dokumentiert.

Angeben eines Proxyservers durch Festlegen von JVM-Optionen

Um eine Verbindung über einen Proxyserver herzustellen, können Sie Optionen in Ihrem Code festlegen oder Befehlszeilenparameter an die JVM (Java Virtual Machine) Ihrer Clientanwendung übergeben. Die beiden Techniken sind äquivalent.

Gehen Sie folgendermaßen vor, um die Optionen in Ihrem Code festzulegen:

System.setProperty("http.useProxy", "true");
System.setProperty("http.proxyHost", "proxyHost Value");
System.setProperty("http.proxyPort", "proxyPort Valure");
System.setProperty("https.proxyHost", "proxyHost HTTPS Value");
System.setProperty("https.proxyPort", ""proxyPort HTTPS Value"")

Gehen Sie folgendermaßen vor, um die Optionen über Befehlszeilenparameter für Ihre JVM festzulegen:

-Dhttp.useProxy=true
-Dhttps.proxyHost=<proxy_host>
-Dhttp.proxyHost=<proxy_host>
-Dhttps.proxyPort=<proxy_port>
-Dhttp.proxyPort=<proxy_port>

Um den Proxy für eine oder mehrere IP-Adressen oder URLs zu umgehen, fügen Sie die Speicherorte zu Ihren JVM-Optionen hinzu: Die Elemente sind durch einen senkrechten Strich voneinander getrennt. Ein Element kann ein Sternchen („*“) als Platzhalterzeichen enthalten. Beispiel:

-Dhttp.nonProxyHosts="*.my_company.com|localhost|xy12345.snowflakecomputing.com|192.168.91.*"

Angeben eines Proxyservers in der JDBC-Verbindungszeichenfolge

Sie können die IP-Adresse und die Portnummer eines Proxyservers direkt in der JDBC-Verbindungszeichenfolge angeben:

jdbc: snowflake: //<Konto>.<Regions-ID> .snowflakecomputing.com /? warehouse =<Warehousename> &useProxy = true&proxyHost =<IP_Adresse>&proxyPort =<Port>&proxyUser = test&proxyPassword = test

Beispiel:

jdbc:snowflake://xy12345.us-east-1.snowflakecomputing.com/?warehouse=DemoWarehouse1 &useProxy=true&proxyHost=172.31.89.76&proxyPort=8888&proxyUser=test&proxyPassword=test

Wenn Ihr Proxyserver keine Authentifizierung erfordert, können Sie die Informationen proxyUser und proxyPassword weglassen.

Bemerkung

Die obigen Beispiele enthalten Leerzeichen zur besseren Lesbarkeit. Wenn Sie eines dieser Beispiele kopieren und einfügen möchten, entfernen Sie das zusätzliche Leerzeichen.

Bemerkung

Das Angeben der Proxyinformationen als Teil der URL ist weniger sicher als andere Methoden zum Angeben der Proxyinformationen.

Tipp

Das Sicherheitsmodell von Snowflake erlaubt keine Secure Sockets Layer (SSL)-Proxys (unter Verwendung eines HTTPS-Zertifikats). Ihr Proxyserver muss eine öffentlich zugängliche Zertifizierungsstelle (CA) verwenden, um potenzielle Sicherheitsrisiken wie einen MITM (Man In The Middle)-Angriff durch einen kompromittierten Proxy zu reduzieren.

Wenn Sie Ihren SSL-Proxy verwenden müssen, empfehlen wir Ihnen dringend, die Serverrichtlinie zu aktualisieren, um die Snowflake-Zertifikatsprüfung zu bestehen, sodass mitten in der Kommunikation kein Zertifikat geändert wird.

Optional kann NO_PROXY verwendet werden, um den Proxy für bestimmte Arten der Kommunikation zu umgehen. Beispielsweise kann der Zugriff auf Amazon S3 durch Angabe von NO_PROXY=".amazonaws.com" umgangen werden.

OCSP

Wenn der Treiber eine Verbindung herstellt, sendet Snowflake ein Zertifikat, um zu bestätigen, dass die Verbindung zu Snowflake und nicht zu einem Host besteht, der sich als Snowflake ausgibt. Der Treiber sendet dieses Zertifikat an einen OCSP (Online Certificate Status Protocol)-Server, um zu überprüfen, ob das Zertifikat widerrufen wurde.

Wenn der Treiber den OCSP-Server nicht erreichen kann, um das Zertifikat zu überprüfen, kann beim Treiber „Fail-open“ oder „Fail-close“ auftreten.

Auswahl des Fail-Open- oder Fail-Close-Modus

Bei JDBC-Treiberversionen vor 3.8.0 findet standardmäßig „Fail-close“ statt. Bei Versionen 3.8.0 und höher findet standardmäßig „Fail-open“ statt. Sie können das Standardverhalten auf eine der folgenden Arten überschreiben:

• Setzen Sie die Verbindungseigenschaft ocspFailOpen auf true oder false. Beispiel: . Properties connection_properties = new Properties(); . connection_properties.put("ocspFailOpen", "false"); . ... . connection = DriverManager.getConnection(connectionString, connection_properties);

• Setzen Sie die Systemeigenschaft net.snowflake.jdbc.ocspFailOpen auf true oder false. Beispiel: . Properties p = new Properties(System.getProperties()); . p.put("net.snowflake.jdbc.ocspFailOpen", "false"); . System.setProperties(p);

Überprüfen der Version von OCSP-Konnektor oder -Treiber

Weitere Informationen zu Treiber- oder Konnektor-Version, Konfiguration und OCSP-Verhalten finden Sie unter OCSP-Konfiguration.

OCSP-Antwort-Cacheserver

Bemerkung

Der OCSP-Antwort-Cacheserver wird derzeit vom Snowflake JDBC Driver 3.6.0 und höher unterstützt.

Snowflake-Clients initiieren jede Verbindung zu einem Snowflake-Service-Endpunkt mit einem „Handshake“, der eine sichere Verbindung herstellt, bevor tatsächlich Daten übertragen werden. Im Rahmen des Handshakes authentifiziert ein Client das TLS/SSL-Zertifikat für den Service-Endpunkt. Der Sperrstatus des Zertifikats wird überprüft, indem eine Client-Zertifikatsanforderung an einen der OCSP (Online Certificate Status Protocol)-Server für die CA (Zertifizierungsstelle) gesendet wird.

Ein Verbindungsfehler tritt auf, wenn die Antwort des OCSP-Servers über eine angemessene Zeit hinaus verzögert wird. Die folgenden Caches behalten den Sperrstatus bei und helfen, diese Probleme zu beheben:

• Speichercache, der während der gesamten Lebensdauer des Prozesses beibehalten wird.

• Dateicache, der so lange beibehalten wird, bis das Cacheverzeichnis (z. B. ~/.cache/snowflake oder ~/.snowsql/ocsp_response_cache) gelöscht ist.

• Snowflake-OCSP-Antwort-Cacheserver, der OCSP-Antworten von den OCSP-Servern der CA stündlich abruft und 24 Stunden lang speichert. Clients können dann den Validierungsstatus eines bestimmten Snowflake-Zertifikats von diesem Servercache anfordern.

  Wichtig

  Wenn Ihre Serverrichtlinie den Zugriff auf die meisten oder alle externen IP-Adressen und Websites verweigert, müssen Sie die Adresse des Cacheservers auf die Whitelist setzen, um einen normalen Servicebetrieb zu ermöglichen. Der Hostname des Cacheservers lautet ocsp*.snowflakecomputing.com:80.

  Wenn Sie den Cacheserver aus irgendeinem Grund deaktivieren müssen, setzen Sie die Umgebungsvariable SF_OCSP_RESPONSE_CACHE_SERVER_ENABLED auf false. Beachten Sie, dass der Wert zwischen Groß- und Kleinschreibung unterscheidet und in Kleinbuchstaben angegeben werden muss.

Wenn keine der Cacheschichten die OCSP-Antwort enthält, versucht der Client, den Validierungsstatus direkt vom OCSP-Server der CA abzurufen.

Dateicaches

Um die Benutzerfreundlichkeit zu verbessern, verwendet der Treiber Dateicaches zur Authentifizierung und für OCSP-Antworten. Standardmäßig werden diese Dateien in den folgenden Verzeichnissen gespeichert:

Linux

~/.cache/snowflake

macOS

~/Library/Caches/Snowflake

Windows

%USERPROFILE%AppDataLocalSnowflakeCaches

Wenn der JDBC-Anwendungsbenutzer im lokalen Betriebssystem kein Benutzerprofil hat, versucht der Treiber, die Cachedateien im temporären Verzeichnis zu speichern. Sie können den Treiber so konfigurieren, dass er Cachedateien in ein anderes Verzeichnis schreibt, indem Sie die folgenden Umgebungsvariablen verwenden:

SF_TEMPORARY_CREDENTIAL_CACHE_DIR=Zeichenfolge

Gibt den Speicherort der temporären Cachedatei mit den Anmeldeinformationen in einem lokalen Verzeichnis an. Dies kann auch beim Start mit der JVM-Option -Dnet.snowflake.jdbc.temporaryCredentialCacheDir=Zeichenfolge konfiguriert werden.

SF_OCSP_RESPONSE_CACHE_DIR=Zeichenfolge

Gibt den Speicherort der OCSP-Antwort-Cachedatei in einem lokalen Verzeichnis an. Dies kann auch beim Start mit der JVM-Option -Dnet.snowflake.jdbc.ocspResponseCacheDir=Zeichenfolge konfiguriert werden.

Weitere Informationen dazu finden Sie unter OCSP-Antwort-Cacheserver (unter diesem Thema).

Beachten Sie, dass die Optionen für JVM beim Start festgelegt werden sollten und nicht programmgesteuert (über System.setProperty()). Wenn sowohl die Umgebungsvariable als auch die JVM-Optionen angegeben sind, wird die JVM-Option verwendet.

Konfigurieren der JDBC-Protokollierung

Ab Version 3.0.4 unterstützt der JDBC-Treiber zwei Protokollierungs-Frameworks:

• Java-Core-Protokollierungsmöglichkeiten

• Simple Logging Facade für Java

Java-Core-Protokollierungsmöglichkeiten (java.util.logging)

Um diese Protokollierung zu verwenden, geben Sie für die JVM folgende Option an:

-Dnet.snowflake.jdbc.loggerImpl=net.snowflake.client.log.JDK14Logger

Anschließend können Sie die Protokollierungskonfiguration über die Anwendungsprogrammierungsschnittstelle (API) für die Protokollierung anpassen. Weitere Details dazu finden Sie in der Dokumentation zum java.util.logging-Paket.

Erstellen Sie beispielsweise eine Datei mit dem Namen logging.properties und folgendem Inhalt:

###########################################################
#   Default Logging Configuration File
#
# You can use a different file by specifying a filename
# with the java.util.logging.config.file system property.
# For example java -Djava.util.logging.config.file=myfile
############################################################

############################################################
#   Global properties
############################################################

# "handlers" specifies a comma-separated list of log Handler
# classes.  These handlers will be installed during VM startup.
# Note that these classes must be on the system classpath.
# ConsoleHandler and FileHandler are configured here such that
# the logs are dumped into both a standard error and a file.
handlers = java.util.logging.ConsoleHandler, java.util.logging.FileHandler

# Default global logging level.
# This specifies which kinds of events are logged across
# all loggers.  For any given facility this global level
# can be overriden by a facility specific level.
# Note that the ConsoleHandler also has a separate level
# setting to limit messages printed to the console.
.level = INFO

############################################################
# Handler specific properties.
# Describes specific configuration information for Handlers.
############################################################

# default file output is in the tmp dir
java.util.logging.FileHandler.pattern = /tmp/snowflake_jdbc%u.log
java.util.logging.FileHandler.limit = 5000000000000000
java.util.logging.FileHandler.count = 10
java.util.logging.FileHandler.level = INFO
java.util.logging.FileHandler.formatter = net.snowflake.client.log.SFFormatter

# Limit the messages that are printed on the console to INFO and above.
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter = net.snowflake.client.log.SFFormatter

# Example to customize the SimpleFormatter output format
# to print one-line log message like this:
#     <level>: <log message> [<date/time>]
#
# java.util.logging.SimpleFormatter.format=%4$s: %5$s [%1$tc]%n

############################################################
# Facility specific properties.
# Provides extra control for each logger.
############################################################

# Snowflake JDBC logging level.
net.snowflake.level = INFO
net.snowflake.handler = java.util.logging.FileHandler

Geben Sie die JVM-Parameter in die Befehlszeile ein:

java -jar application.jar -Dnet.snowflake.jdbc.loggerImpl=net.snowflake.client.log.JDK14Logger -Djava.util.logging.config.file=logging.properties

Dabei verweist application.jar auf den Anwendungscode für den JDBC-Treiber. Die Protokolldateien befinden sich unter /tmp/snowflake_jdbc*.

Simple Logging Facade für Java (org.slf4j)

Wenn ein Implementierungspaket für die Protokollierung (z. B. org.sl4j:sl4j-jdk14 oder org.sl4j:slf4j-log4j12) oder eine benutzerdefinierte Protokollierung (z. B. Ihre eigene org.slf4j.impl.StaticLoggerBinder-Klasse) im Klassenpfad definiert wurde, dann verwendet der Treiber diese Protokollierung automatisch.

Sie können diese Protokollierung auch explizit verwenden, indem Sie die folgende JVM-Option angeben:

-Dnet.snowflake.jdbc.loggerImpl=net.snowflake.client.log.SLF4JLogger.

Weitere Informationen dazu finden Sie in der Dokumentation zu Simple Logging Facade für Java (SLF4J).

Bemerkung

Wenn Sie keine Protokollierung für den Treiber mit einer der oben beschriebenen JVM-Optionen explizit angeben und keine benutzerdefinierte Protokollierung im Klassenpfad definiert ist (oder Sie eine Treiberversion vor 3.0.4 verwenden), verwendet der Treiber standardmäßig java.util.logging. Es gilt jedoch das folgende Standardverhalten:

• Sie können nicht angeben, wo die Protokolldatei geschrieben wird. Sie wird immer in das Verzeichnis geschrieben, das durch die Systemeigenschaft java.io.tmpDir angegeben ist:

  • In Linux- und macOS-Umgebungen ist das Standardverzeichnis normalerweise entweder /tmp oder /var/tmp.

  • In Windows-Umgebungen ist das Standardverzeichnis normalerweise C:\temp.

• Der Protokolliergrad wird durch den Verbindungsparameter tracing bestimmt (siehe oben).

Tipps zur Problembehandlung

Sicherstellen, dass die Eigenschaften korrekt eingestellt sind

Die DriverManager.getConnection()-Methode liest nur die Werte des Eigenschaftsparameters, die mit bestimmten vordefinierten Namen übereinstimmen (z. B. „Kennwort“, „Konto“ usw.). Wenn Sie einen Eigenschaftsnamen falsch schreiben oder zusätzliche Eigenschaften hinzufügen, ignoriert der Treiber diese Eigenschaften, ohne eine Fehler- oder Warnmeldung auszugeben. Dies kann es erschweren, kleine Rechtschreibfehler zu erkennen.

Verwenden der richtigen Werte für Verbindungszeichenfolge und Konto

Eine häufige Ursache für Verbindungsprobleme besteht darin, zu viele oder zu wenig Informationen anzugeben, wenn Sie nach einem Konto, einem Kontonamen oder einer Verbindungszeichenfolge gefragt werden.

Die Kontoinformationen haben in der Regel die folgende Struktur, abhängig von der Region und der Cloudplattform, wo Ihr Konto gehostet wird:

• <Konto>

• <Konto>.``<Regions-ID>``

• <Konto>.``<Regions-ID>``.``<Plattform>``

Beispiel:

• xy12345

• xy12345.us-east-1

• xy12345.east-us-2.azure

Die JDBC-Verbindungszeichenfolge sieht normalerweise folgendermaßen aus:

• jdbc:snowflake://xy12345.east-us-2.azure.snowflakecomputing.com

Die Verwendung der Verbindungszeichenfolge, wenn Kontoinformationen erwartet werden (oder umgekehrt), kann zu schwer zu behebenden Problemen führen.

Falls Sie keine Verbindung herstellen können, wenn Sie nach einem Konto gefragt werden, versuchen Sie es sowohl mit der Minimalform (z. B. xy12345) als auch mit dem vollständigen Kontonamen (z. B. xy12345.east-us-2.azure, aber ohne .snowflakecomputing.com), und stellen Sie sicher, dass Sie die Zeichenfolge jdbc:snowflake:// nicht enthalten ist.

Falls Sie keine Verbindung herstellen können, wenn Sie nach einer JDBC-Verbindungszeichenfolge gefragt werden, verwenden Sie die vollständige Form der Verbindungszeichenfolge (wie oben gezeigt).

Weitere Informationen zu Kontonamen finden Sie unter Verbindungsparameter.