Benutzerdefinierte Clients für External OAuth konfigurieren

Unter diesem Thema wird beschrieben, wie Sie Snowflake als OAuth-Ressource und ein benutzerdefinierter Client als External OAuth-Autorisierungsserver konfigurieren, um einen sicheren, programmgesteuerten Zugriff auf Snowflake-Daten zu ermöglichen.

Unter diesem Thema:

Übersicht

Snowflake unterstützt eine benutzerdefinierte Integration für Identitätsanbieter (IdPs), die ansonsten nicht unterstützt werden, um Benutzer zu verifizieren und OAuth-Zugriffstoken zu generieren und so einen sicheren, programmgesteuerten Zugriff auf Snowflake-Daten zu ermöglichen.

Nutzdatenanforderungen für External OAuth-Token

Für benutzerdefinierte External OAuth-Clients sind in der folgenden Tabelle die erforderlichen Nutzdateninformationen aufgeführt, die das External OAuth-Zugriffstoken enthalten muss, damit Snowflake das Zugriffstoken verarbeiten kann. Weitere Informationen zur Spalte „Ansprüche“ finden Sie unter JWT-Ansprüche.

Ansprüche

Beschreibung

scp

Bereiche. Eine Liste der Bereiche im Zugriffstoken.

scope

Bereiche. Eine durch Kommas getrennte Zeichenfolge von Bereichen im Zugriffstoken.

aud

Zielgruppe. Identifiziert die Empfänger, für die das Zugriffstoken bestimmt ist, als Zeichenfolgen-URI.

exp

Ablaufzeit. Gibt die Ablaufzeit an, nach der das Zugriffstoken nicht mehr zur Verarbeitung akzeptiert wird.

iss

Aussteller. Identifiziert den Prinzipal, der das Zugriffstoken ausgegeben hat, als Zeichenfolge-URI.

iat

Ausgestellt am. Erforderlich. Gibt den Zeitpunkt an, zu dem das JWT ausgestellt wurde.

Bemerkung

Snowflake unterstützt den nbf-Anspruch (not before), der den Zeitpunkt angibt, bis zu dem das Zugriffstoken nicht zur Verarbeitung akzeptiert wird.

Wenn Ihr Autorisierungsserver den nbf-Anspruch (not before) unterstützt, können Sie den nbf-Anspruch optional in das Zugriffstoken aufnehmen.

Um zu überprüfen, ob Ihr Token die erforderlichen Informationen enthält, können Sie das Token auf der JSON Web Tokens-Website testen.

Als typisches Beispiel zeigt die PAYLOAD: DATA-Schnittstelle die Token-Nutzdaten wie folgt an.

{
  "aud": "<audience_url>",
  "iat": 1576705500,
  "exp": 1576709100,
  "iss": "<issuer_url>",
  "scp": [
    "session:role:analyst"
  ]
}

Konfigurationsverfahren

Bei den folgenden Schritten wird davon ausgegangen, dass Ihr IdP und Ihre Umgebung so konfiguriert werden können, dass die erforderlichen Werte zum Erstellen der Snowflake-Sicherheitsintegration abgerufen werden.

Wichtig

Die Schritte unter diesem Thema sind ein repräsentatives Beispiel für das Konfigurieren von benutzerdefinierten Clients für External OAuth.

Sie können Ihre Umgebung in einem beliebigen Status konfigurieren und einen beliebigen OAuth-Ablauf verwenden, sofern Sie die erforderlichen Informationen für die Sicherheitsintegration (unter diesem Thema) erhalten.

Beachten Sie, dass die folgenden Schritte als Leitfaden dienen, um die erforderlichen Informationen zum Erstellen der Sicherheitsintegration in Snowflake abzurufen.

Beachten Sie bei der Konfiguration eines Autorisierungsservers unbedingt Ihre internen Sicherheitsrichtlinien, damit Ihre Organisation alle erforderlichen Vorschriften und Compliance-Anforderungen erfüllt.

Schritt 1: Wichtige Umgebungswerte zur Verwendung von External OAuth erhalten

Konfigurieren Sie Ihren IdP und Autorisierungsserver. Es ist erforderlich, die folgenden Werte zu identifizieren, die im nächsten Schritt in die Snowflake-Sicherheitsintegration aufgenommen werden sollen.

Aussteller-URL

Fügen Sie diese URL in den Parameter external_oauth_issuer ein.

Öffentlicher RSA-Schlüssel

Fügen Sie diesen Wert in external_oauth_rsa_public_key_value ein.

Zielgruppen-URLs

Wenn mehr als eine Zielgruppen-URL erforderlich ist, trennen Sie jede URL im Parameter external_oauth_audience_list durch ein Komma.

Bereichsattribut

Dieser Wert kann entweder für scp oder scope konfiguriert werden. Fügen Sie diesen Wert in external_oauth_scope_mapping_attribute ein. Weitere Informationen dazu finden Sie unter Nutzdatenanforderungen für External OAuth-Token.

Benutzerattribut

Dieses Attribut bezieht sich auf ein Attribut zur Identifizierung von Benutzern in Ihrem IdP. Fügen Sie diesen Attributwert in external_oauth_user_mapping_claim ein.

Snowflake-Benutzerattribut

Das Attribut in Snowflake zur Identifizierung von Benutzern. Fügen Sie diesen Wert in external_oauth_snowflake_user_mapping_attribute ein.

Schritt 2: OAuth-Autorisierungsserver in Snowflake erstellen

In diesem Schritt wird eine Sicherheitsintegration in Snowflake erstellt. Die Sicherheitsintegration stellt sicher, dass Snowflake sicher mit Token von Ihrem IdP kommunizieren und diese validieren kann und Benutzern den entsprechenden Snowflake-Datenzugriff basierend auf der dem OAuth-Token zugeordneten Benutzerrolle bietet. Weitere Informationen dazu finden Sie unter CREATE SECURITY INTEGRATION.

Wichtig

Dieser SQL-Befehl kann nur von Kontoadministratoren oder von Rollen mit der globalen Berechtigung CREATE INTEGRATION ausgeführt werden.

Bei den Werten der Sicherheitsintegrationsparameter wird zwischen Groß- und Kleinschreibung unterschieden, und die Werte, die Sie in die Sicherheitsintegration eingeben, müssen mit diesen Werten in Ihrer Umgebung übereinstimmen. Wenn die Schreibung nicht übereinstimmt, wird das Zugriffstoken möglicherweise nicht validiert, was zu einem fehlgeschlagenen Authentifizierungsversuch führt.

OAuth-Autorisierungsserver in Snowflake erstellen

create security integration external_oauth_custom
    type = external_oauth
    enabled = true
    external_oauth_type = custom
    external_oauth_issuer = '<your_authorization_server_url>'
    external_oauth_rsa_public_key = '<public_key_value>'
    external_oauth_audience_list=('<audience_url_1>', '<audience_url_2>')
    external_oauth_scope_mapping_attribute = 'scp'
    external_oauth_token_user_mapping_claim='upn'
    external_oauth_snowflake_user_mapping_attribute='login_name';

Ändern Ihrer External OAuth-Sicherheitsintegration

Sie können Ihre External OAuth-Sicherheitsintegration aktualisieren, indem Sie auf der Sicherheitsintegration eine ALTER-Anweisung ausführen.

Weitere Informationen dazu finden Sie unter ALTER SECURITY INTEGRATION.

Verwenden der Rolle ANY mit External OAuth

Im Konfigurationsschritt zum Erstellen einer Sicherheitsintegration in Snowflake enthält das OAuth-Zugriffstoken die Bereichsdefinition. Daher können zur Laufzeit mit der External OAuth-Sicherheitsintegration weder OAuth-Client noch -Benutzer eine undefinierte Rolle im OAuth-Zugriffstoken verwenden.

Nach dem Überprüfen des Zugriffstokens und dem Erstellen einer Sitzung kann die Rolle ANY dem OAuth-Client und -Benutzer ermöglichen, ihre Rolle zu bestimmen. Bei Bedarf kann der Client oder der Benutzer zu einer Rolle wechseln, die sich von der im OAuth-Zugriffstoken definierten Rolle unterscheidet.

Beim Konfigurieren der ANY-Rolle definieren Sie den Bereich als SESSION:ROLE-ANY und konfigurieren dann die Sicherheitsintegration mit dem Parameter external_oauth_any_role_mode. Dieser Parameter kann drei mögliche Zeichenfolgenwerte haben:

  • DISABLE erlaubt dem OAuth-Client oder -Benutzer nicht, die Rollen zu wechseln (d. h. use role <Rolle>;). Standard.

  • ENABLE ermöglicht dem OAuth-Client oder -Benutzer, die Rollen zu wechseln.

  • ENABLE_FOR_PRIVILEGE ermöglicht dem OAuth-Client oder -Benutzer, die Rollen nur für einen Client oder Benutzer mit der Berechtigung USE_ANY_ROLE zu wechseln. Diese Berechtigung kann einer oder mehreren dem Benutzer zur Verfügung stehenden Rollen erteilt und entzogen werden. Beispiel:

    grant USE_ANY_ROLE on integration external_oauth_1 to role1;
    
    revoke USE_ANY_ROLE on integration external_oauth_1 from role1;
    

Definieren Sie die Sicherheitsintegration wie folgt:

create security integration external_oauth_1
    type = external_oauth
    enabled = true
    external_oauth_any_role_mode = 'ENABLE'
    ...

Verwenden von Netzwerkrichtlinien mit External OAuth

Derzeit können keine Netzwerkrichtlinien zu Ihrer External OAuth-Sicherheitsintegration hinzugefügt werden.

Wenn für Ihren Anwendungsfall OAuth und eine Snowflake-Netzwerkrichtlinie erforderlich sind, verwenden Sie Snowflake OAuth.

Weitere Informationen dazu finden Sie unter OAuth und Netzwerkrichtlinien.

Testverfahren

Im Zusammenhang mit dem Testen von OAuth unter Verwendung von benutzerdefinierten Clients als Autorisierungsserver müssen Sie Folgendes tun:

  1. Stellen Sie sicher, dass der Testbenutzer in Ihrem IdP vorhanden ist und über ein Kennwort verfügt.

  2. Stellen Sie sicher, dass der Testbenutzer in Snowflake vorhanden ist und der Attributwert login_name auf <external_oauth_token_user_mapping_claim> gesetzt ist.

  3. OAuth-Client registrieren

  4. Ermöglichen Sie dem OAuth-Client, wie folgt eine POST-Anforderung an den benutzerdefinierten Token-Endpunkt zu senden:

    • Gewährungstyp auf „Ressource Owner“ setzen

    • HTTP-Basic Authorization-Header, der clientID und Geheimnis enthält

    • FORM-Daten, die den Benutzernamen und das Kennwort des Benutzers enthalten

    • Bereiche einschließen

Der Beispielbefehl fordert den Analysten an und setzt voraus, dass session:role:analyst auf Ihrem OAuth-Autorisierungsserver definiert wurde.

Hier ist ein Beispiel für das Abrufen eines Zugriffstokens mit cURL.

curl -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
  --user <OAUTH_CLIENT_ID>:<OAUTH_CLIENT_SECRET> \
  --data-urlencode "username=<IdP_USER_USERNAME>" \
  --data-urlencode "password=<IdP_USER_PASSWORD>" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "scope=session:role:analyst" \
  <IdP_TOKEN_ENDPOINT>

Herstellen einer Verbindung zu Snowflake mit External OAuth

Nachdem Sie Ihre Sicherheitsintegration konfiguriert und Ihr Zugriffstoken erhalten haben, können Sie eine der folgenden Verbindungen zu Snowflake herstellen:

Beachten Sie Folgendes:

  • Es ist notwendig, den Parameter authenticator auf oauth und den Parameter token auf external_oauth_access_token zu setzen.

  • Wenn Sie den token-Wert als URL-Abfrageparameter übergeben, muss der token-Wert als URL codiert werden.

  • Wenn Sie den token-Wert an ein Properties-Objekt übergeben (z. B. JDBC-Treiber), sind keine Anpassungen erforderlich.

Wenn Sie beispielsweise den Python-Konnektor verwenden, legen Sie die Verbindungszeichenfolge wie unten gezeigt fest.

ctx = snowflake.connector.connect(
   user="<username>",
   host="<hostname>",
   account="<account_name>",
   authenticator="oauth",
   token="<external_oauth_access_token>",
   warehouse="test_warehouse",
   database="test_db",
   schema="test_schema"
)

Sie können jetzt External OAuth verwenden, um eine sichere Verbindung zu Snowflake herzustellen.