Snowflake OAuth für kundenspezifische Clients konfigurieren¶

Workflow¶

Die folgenden allgemeinen Schritte sind erforderlich, um OAuth für kundenspezifische Clients zu konfigurieren:

1. Registrieren Sie Ihren Client bei Snowflake. Erstellen Sie eine Integration, um Ihren Client zu registrieren. Eine Integration ist ein Snowflake-Objekt, das eine Schnittstelle zwischen Snowflake und Services von Drittanbietern bereitstellt, z. B. ein Client, der OAuth unterstützt.

   Der Registrierungsprozess definiert eine Client-ID und Clientgeheimnisse.

2. Konfigurieren Sie Aufrufe an die Snowflake OAuth -Endpunkte, um Autorisierungscodes vom Snowflake-Autorisierungsserver anzufordern sowie Zugriffstoken anzufordern und zu aktualisieren.

   Mit den optionalen „scope“-Parametern lässt sich bei der erstmaligen Autorisierungsanforderung die vom Zugriffstoken zugelassene Rolle einschränken. Außerdem können sie zum Konfigurieren des Verhaltens des Aktualisierungstokens verwendet werden.

Snowflake OAuth-Integration erstellen¶

Erstellen Sie eine Snowflake OAuth-Integration mit dem Befehl CREATE SECURITY INTEGRATION. Achten Sie darauf, dass Sie beim Erstellen der Integration OAUTH_CLIENT = CUSTOM angeben.

CREATE SECURITY INTEGRATION oauth_kp_int
  TYPE = OAUTH
  ENABLED = TRUE
  OAUTH_CLIENT = CUSTOM
  OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
  OAUTH_REDIRECT_URI = 'https://localhost.com'
  OAUTH_ISSUE_REFRESH_TOKENS = TRUE
  OAUTH_REFRESH_TOKEN_VALIDITY = 86400
  BLOCKED_ROLES_LIST = ('SYSADMIN')
  OAUTH_CLIENT_RSA_PUBLIC_KEY ='
  MIIBI
  ...
  ';

OAuth-Endpunkte aufrufen¶

OAuth-Endpunkte sind die URLs, die Clients aufrufen, um Autorisierungscodes anzufordern und um Zugriffstoken anzufordern und zu aktualisieren. Diese Endpunkte verweisen auf bestimmte OAuth 2.0-Richtlinien, die beim Aufrufen des Endpunkts ausgeführt werden.

Snowflake bietet die folgenden OAuth-Endpunkte:

Autorisierung:

<Snowflake-Konto-URL>/oauth/authorize

Tokenanforderungen:

<Snowflake-Konto-URL>/oauth/token-request

Dabei ist <Snowflake-Konto-URL> eine gültige Snowflake-Konto-URL. Sie könnten beispielsweise die Endpunkte https://myorg-account_xyz.snowflakecomputing.com/oauth/authorize und https://myorg-account_xyz.snowflakecomputing.com/oauth/token-request verwenden. Eine Liste der unterstützten Formate für die Snowflake-Konto-URL finden Sie unter Verbinden mittels URL.

Um eine Liste der gültigen OAuth-Endpunkte für eine Sicherheitsintegration anzuzeigen, führen Sie DESCRIBE INTEGRATION aus, und zeigen Sie dann die Werte in den Eigenschaften OAUTH_ALLOWED_AUTHORIZATION_ENDPOINTS und OAUTH_ALLOWED_TOKEN_ENDPOINTS an.

<snowflake_account_url>/oauth/authorize

<snowflake_account_url>/oauth/token-request

Content-type: application/x-www-form-urlencoded

{
  "access_token":  "ACCESS_TOKEN",
  "expires_in": 600,
  "refresh_token": "REFRESH_TOKEN",
  "token_type": "Bearer",
  "username": "user1",
}

{
  "data" : null,
  "message" : "This is an invalid client.",
  "code" : null,
  "success" : false,
  "error" : "invalid_client"
}

Proof Key for Code Exchange (PKCE)¶

Snowflake unterstützt Proof Key for Code Exchange (PKCE) zum Abrufen von Zugriffstoken mit dem Gewährungstyp authorization_code, wie in RFC 7636 beschrieben. PKCE kann verwendet werden, um die Möglichkeit von Abfangangriffen auf Autorisierungscodes zu verringern, und ist für Clients geeignet, die möglicherweise nicht in der Lage sind, das Clientgeheimnis vollständig zu wahren.

Standardmäßig ist PKCE optional und wird nur durchgesetzt, wenn die Parameter code_challenge und code_challenge_method beide in der URL des Autorisierungsendpunkts enthalten sind. Snowflake empfiehlt jedoch dringend, dass Ihr Client für alle Berechtigungen PKCE benötigt, um den OAuth-Ablauf sicherer zu gestalten.

Im Folgenden wird beschrieben, wie PKCE für Snowflake funktioniert:

1. Der Client erstellt ein Geheimnis, einen sogenannten Code-Verifizierer („code_verifier“), und führt eine Transformation damit durch, um die Code-Challenge („code_challenge“) zu generieren. Der Client hat die Kontrolle über das Geheimnis.

   Wichtig

   Er generiert den Code-Verifizierer aus den zulässigen ASCII-Zeichen gemäß Abschnitt 4.1 von RFC 7636.

2. Beim Weiterleiten des Benutzer zur Autorisierungs-URL hängt der Client die folgenden zwei Abfrageparameter an:

   code_challenge

   Gibt die in Schritt 1 generierte Code-Challenge an.

   code_challenge_method

   Gibt die Transformationen an, die in Schritt 1 auf den Codeprüfer zum Generieren der Code-Challenge angewendet werden. Derzeit unterstützt Snowflake nur SHA256, daher muss dieser Wert auf S256 gesetzt werden. Der Transformationsalgorithmus für SHA256 ist BASE64URL-ENCODE(SHA256(ASCII(code_verifier))).

3. Nachdem der Benutzer den angeforderten Bereichen zugestimmt hat oder Snowflake feststellt, dass für diesen Benutzer eine Zustimmung vorliegt, wird der Autorisierungscode ausgegeben.

4. Der Client erhält den Autorisierungscode vom Snowflake-Autorisierungsserver, den er dann zusammen mit dem code_verifier in der Anforderung an den Token-Endpunkt sendet.

5. Snowflake transformiert den Wert code_verifier und prüft, ob der transformierte Wert mit dem Wert code_challenge übereinstimmt, der beim Generieren von Autorisierungen verwendet wird. Stimmen diese Werte überein, stellt der Autorisierungsserver die Zugriffs- und Aktualisierungstoken aus.

Verwenden der Schlüsselpaar-Authentifizierung¶

Snowflake unterstützt bei Aufrufen des OAuth-Token-Endpunkts 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 öffentlich-private PEM (Privacy Enhanced Mail)-Schlüsselpaar unter Verwendung von 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 verschlüsselten privaten Schlüssel:

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

   Copy

   OpenSSL fragt nach einer Passphrase, die zur Verschlüsselung der privaten Schlüsseldatei verwendet wird. Snowflake empfiehlt, zum Schutz des privaten Schlüssels eine starke Passphrase zu verwenden. Notieren Sie sich diese Passphrase. 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-----
   

   Copy

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

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

   Copy

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

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

   Copy

3. Kopieren Sie die Dateien der öffentlichen und privaten Schlüssel zur Speicherung in ein lokales 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 den öffentlichen Schlüssel mit ALTER SECURITY INTEGRATION dem Integrationsobjekt zu. Beispiel:

   ALTER SECURITY INTEGRATION myint SET OAUTH_CLIENT_RSA_PUBLIC_KEY='MIIBIjANBgkqh...';
   

   Copy

   Bemerkung

   • Nur Kontoadministratoren können den ALTERSECURITYINTEGRATION-Befehl ausführen.

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

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

   DESC SECURITY INTEGRATION myint;
   
   +----------------------------------+---------------+----------------------------------------------------------------------+------------------+
   | property                         | property_type | property_value                                                       | property_default |
   |----------------------------------+---------------+----------------------------------------------------------------------+------------------|
   ...
   | OAUTH_CLIENT_RSA_PUBLIC_KEY_FP   | String        | SHA256:MRItnbO/123abc/abcdefghijklmn12345678901234=                  |                  |
   | OAUTH_CLIENT_RSA_PUBLIC_KEY_2_FP | String        |                                                                      |                  |
   ...
   +----------------------------------+---------------+----------------------------------------------------------------------+------------------+
   

   Copy

   Bemerkung

   Eine Beschreibung der Eigenschaft OAUTH_CLIENT_RSA_PUBLIC_KEY_2_FP finden Sie unter Schlüsselrotation (unter diesem Thema).

5. Ändern Sie den unten stehenden Beispielcode, und führen Sie ihn aus. Der Code verwendet den privaten Schlüssel, um ein JWT zu kodieren, und übergibt dieses Token dann an den Snowflake-Autorisierungsserver:

   • Aktualisieren Sie die Sicherheitsparameter:

     • <Privater_Schlüssel>: Öffnen Sie die Datei rsa_key.p8 in einem Texteditor, und kopieren Sie die Zeilen zwischen der Kopfzeile BEGIN und der Fußzeile END.

   • Aktualisieren Sie die Sitzungsparameter:

     • <account_identifier>: Gibt den vollen Namen Ihres Kontos an (bereitgestellt von Snowflake).

   • Aktualisieren Sie die JWT-Felder (JSON Web Token):

     post body

     Ein JSON-Objekt mit den folgenden Standardfeldern („Ansprüche“):

     Attribut	Datentyp	Erforderlich	Beschreibung
     iss	String	Ja	Gibt den Prinzipal an, der das JWT im Format client_id.public_key_fp ausgegeben hat, wobei client_id die Client-ID der OAuth-Clientintegration und public_key_fp der Fingerabdruck des öffentlichen Schlüssels ist, der bei der Überprüfung verwendet wird.
     sub	String	Ja	Subjekt des JWT im Format account_identifier.client_id, wobei account_identifier der vollständige Name des Snowflake-Kontos und client_id die Client-ID der OAuth-Clientintegration ist. Abhängig von der Cloudplattform (AWS oder Azure) und der Region, in der Ihr Konto gehostet wird, erfordert der vollständige Kontoname möglicherweise zusätzliche Segmente. Weitere Informationen dazu finden Sie in der Beschreibung der account-Variablen unter Token-Endpunkt.
     iat	Zeitstempel	Nein	Zeitpunkt, zu dem das Token ausgestellt wurde.
     exp	Zeitstempel	Ja	Zeitpunkt, zu dem das Token ablaufen soll. Dieser Zeitraum sollte relativ kurz sein (z. B. einige Minuten).

   Beispielcode

   Beachten Sie, dass der Wert private_key die Kopfzeile -----BEGIN und die Fußzeile -----END umfasst.

   import datetime
   import json
   import urllib
   
   import jwt
   import requests
   
   private_key = """
   <private_key>
   """
   
   public_key_fp = "SHA256:MR..."
   
   
   def _make_request(payload, encoded_jwt_token):
       token_url = "https://<account_identifier>.snowflakecomputing.com/oauth/token-request"
       headers = {
               u'Authorization': "Bearer %s" % (encoded_jwt_token),
               u'content-type': u'application/x-www-form-urlencoded'
       }
       r = requests.post(
               token_url,
               headers=headers,
               data=urllib.urlencode(payload))
       return r.json()
   
   
   def make_request_for_access_token(oauth_az_code, encoded_jwt_token):
       """ Given an Authorization Code, make a request for an Access Token
       and a Refresh Token."""
       payload = {
           'grant_type': 'authorization_code',
           'code': oauth_az_code
       }
       return _make_request(payload, encoded_jwt_token)
   
   
   def make_request_for_refresh_token(refresh_token, encoded_jwt_token):
       """ Given a Refresh Token, make a request for another Access Token."""
       payload = {
           'grant_type': 'refresh_token',
           'refresh_token': refresh_token
       }
       return _make_request(payload, encoded_jwt_token)
   
   
   def main():
       account_identifier = "<account_identifier>"
       client_id = "1234"  # found by running DESC SECURITY INTEGRATION
       issuer = "{}.{}".format(client_id, public_key_fp)
       subject = "{}.{}".format(account_identifier, client_id)
       payload = {
           'iss': issuer,
           'sub': subject,
           'iat': datetime.datetime.utcnow(),
           'exp': datetime.datetime.utcnow() + datetime.timedelta(seconds=30)
       }
       encoded_jwt_token = jwt.encode(
               payload,
               private_key,
               algorithm='RS256')
   
       data = make_request_for_access_token(oauth_az_code, encoded_jwt_token)
       refresh_token = data['refresh_token']
       data = make_request_for_refresh_token(refresh_token, encoded_jwt_token)
       access_token = data['access_token']
   
   
   if __name__ == '__main__':
       main()
   

   Copy

   Nachdem das Token erstellt wurde, senden Sie es auf Anforderung an den Token-Endpunkt. Anforderungen erfordern das Bearer-Autorisierungsformat als Autorisierungsheader anstelle des Standardautorisierungsformats, das normalerweise für die Client-ID und das Clientgeheimnis verwendet wird, wie folgt:

   "Authorization: Bearer JWT_TOKEN"
   

   Copy

Fehlercodes¶

Unter Fehlercodes finden Sie eine Liste der mit OAuth in Verbindung stehenden Fehlercodes und der im JSON-Blob zurückgegeben Fehler, die während des Autorisierungsablaufs, der Tokenanforderung oder des Tokenaustauschs oder beim Erstellen einer Snowflake-Sitzung nach Abschluss des OAuth-Ablaufs aufgetreten sind.

Vorautorisierung der Benutzerzustimmung für eine Rolle¶

Sicherheitsadministratoren (d. h. Benutzer mit der Rolle SECURITYADMIN) oder höher können einem Client vorab die Genehmigung erteilen, für einen Benutzer unter Verwendung einer bestimmten Rolle und Integration eine Sitzung zu initiieren. Diese Zustimmung wird unter Verwendung von ALTER USER mit den Schlüsselwörtern ADD DELEGATED AUTHORIZATION erteilt. Ohne diese delegierte Autorisierung muss ein Benutzer nach der Authentifizierung die Zustimmung für die Rolle erteilen. Diese delegierte Berechtigung kann auch widerrufen werden.

Weitere Informationen dazu finden Sie unter Verwalten der Benutzerzustimmung für OAuth.