Microsoft Azure AD für External OAuth konfigurieren

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

Unter diesem Thema:

Konfigurationsverfahren

In den folgenden vier Schritten wird davon ausgegangen, dass in Ihrer Umgebung nichts konfiguriert ist, was sich auf Azure AD-OAuth-Autorisierungsserver, OAuth-Clients, Bereiche und erforderliche Metadaten bezieht.

Die Informationen aus den Schritten 1-3 werden verwendet, um eine Sicherheitsintegration in Snowflake zu erstellen.

Wenn Sie bereits einen Azure AD-Autorisierungsserver und -Client konfiguriert haben, müssen Sie nicht alle folgenden Schritte ausführen. Überspringen Sie stattdessen die folgenden drei Schritte, und stellen Sie sicher, dass Sie die gewünschten Informationen erhalten, Bereiche erstellen, Bereiche zu einer oder mehreren Richtlinien zuweisen und auf die Metadaten zugreifen können.

Wenn Sie keinen Azure AD-OAuth-Autorisierungsserver und -Client konfiguriert haben, führen Sie alle folgenden vier Schritte aus.

Wichtig

Die Schritte unter diesem Thema sind ein repräsentatives Beispiel zum Konfigurieren von Azure AD für External OAuth.

Sie können Azure AD 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.

Die Schritte 1–3 wurden von der Azure AD-Dokumentation zu OAuth 2.0 und Authentifizierung abgeleitet. Weitere Informationen dazu, wie Microsoft seine Begriffe, seine Benutzeroberfläche und Optionen in Bezug auf OAuth 2.0 und Authentifizierung definiert, finden Sie in den folgenden Azure AD-Handbüchern:

Vorbereitender Schritt: OAuth-Ablauf in Azure AD bestimmen

Azure AD unterstützt zwei verschiedene OAuth-Abläufe, in denen ein OAuth-Client ein Zugriffstoken erhalten kann.

  1. Der Autorisierungsserver kann dem OAuth-Client im Namen des Benutzers ein Zugriffstoken gewähren.

  2. Der Autorisierungsserver kann dem OAuth-Client ein Zugriffstoken für den OAuth-Client selbst gewähren.

Im ersten Ablauf verweist die Identität im Zugriffstoken auf den Benutzer. Im zweiten Ablauf verweist die Identität im Zugriffstoken auf den OAuth-Client.

Microsoft Azure AD lässt nicht für beiden OAuth-Abläufe dasselbe Rollenformat zu. Das zu verwendende Rollenformat hängt von dem verwendeten OAuth-Ablauf ab. Nach Festlegen des zu verwendenden OAuth-Ablaufs:

Schritt 1: OAuth-Ressource in Azure AD konfigurieren

  1. Navigieren Sie zum Microsoft Azure Portal, und authentifizieren Sie sich.

  2. Navigieren Sie zu Azure Active Directory.

  3. Klicken Sie auf App Registrations.

  4. Klicken Sie auf New Registration.

  5. Geben Sie Snowflake OAuth Resource oder einen ähnlichen Wert als Name ein.

  6. Stellen Sie sicher, dass Supported account types auf Single Tenant eingestellt ist.

  7. Klicken Sie auf Register.

  8. Klicken Sie auf Expose an API.

  9. Klicken Sie neben der Application ID URI auf den Set-Link, um Application ID URI festzulegen.

    Wichtig

    Die Application ID URI muss im Verzeichnis Ihrer Organisation eindeutig sein, z. B. https://your.company.com/4d2a8c2b-a5f4-4b86-93ca-294185f45f2e. Dieser Wert wird in den nachfolgenden Konfigurationsschritten als <SNOWFLAKE_APPLICATION_ID_URI> bezeichnet.

    Die Standardoption in Azure für Application ID URI beginnt mit api://. Dies muss geändert werden, um mit https:// zu beginnen.

    Wenn Sie Hilfe beim Abrufen Ihrer Application ID URI benötigen, wenden Sie sich an Ihren internen Microsoft Azure AD-Administrator.

    Wenn die Application ID URI nicht verwendet wird, muss mithilfe der Snowflake-Konto-URL eine Sicherheitsintegration mit Zielgruppen erstellt werden (d. h. <Konto>.<Region>.snowflakecomputing.com). Weitere Informationen dazu finden Sie in der Zielgruppenintegration in Schritt 4: OAuth-Autorisierungsserver in Snowflake erstellen.

  10. Um eine Snowflake-Rolle als OAuth-Bereich für OAuth-Abläufe hinzuzufügen, in denen der programmgesteuerte Client im Auftrag eines Benutzers handelt, klicken Sie auf Add a scope, und fügen Sie einen Bereich hinzu, der die Snowflake-Rolle darstellt.

    • Geben Sie den Bereich ein, indem Sie den Namen der Snowflake-Rolle mit dem Präfix session:scope: angeben. Geben Sie beispielsweise für die Rolle „Snowflake Analyst“ session:scope:analyst ein.

    • Wählen Sie aus, wer zustimmen kann.

    • Geben Sie unter display name eine Beschreibung für den Bereich ein (z. B. Kontoadministrator).

    • Geben Sie unter description eine Beschreibung für den Bereich ein (z. B. „Kann das Snowflake-Konto verwalten“).

    • Klicken Sie auf Add Scope.

  11. So fügen Sie eine Snowflake-Rolle als Rolle für OAuth-Abläufe hinzu, bei denen der programmgesteuerte Client ein Zugriffstoken für sich selbst anfordert:

    • Klicken Sie auf Manifest.

    • Suchen Sie das Element appRoles.

    • Geben Sie unter App Role eine Anwendungsrolle mit den folgenden Einstellungen ein.

    Einstellung

    Beschreibung

    allowedMemberTypes

    Anwendung

    description

    Eine Beschreibung der Rolle.

    displayName

    Name, der den Benutzern angezeigt wird.

    id

    Eine eindeutige ID. Sie können die Funktion [System.Guid]::NewGuid() von PowerShell verwenden, um bei Bedarf eine eindeutige ID zu generieren.

    isEnabled

    Auf true setzen.

    lang

    Die Sprache. Auf null setzen.

    origin

    Auf Application setzen.

    value

    Stellen Sie den Namen der Snowflake-Rolle mit dem Präfix session:role: ein. . Geben Sie für die Analystenrolle session:role:analyst ein.

    Die App Role definiert sich wie folgt.

    "appRoles":[
        {
            "allowedMemberTypes": [ "Application" ],
            "description": "Account Administrator.",
            "displayName": "Account Admin",
            "id": "3ea51f40-2ad7-4e79-aa18-12c45156dc6a",
            "isEnabled": true,
            "lang": null,
            "origin": "Application",
            "value": "session:role:analyst"
        }
    ]
    
  12. Klicken Sie auf Save.

Schritt 2: OAuth-Client in Azure AD erstellen

  1. Navigieren Sie zum Microsoft Azure Portal, und authentifizieren Sie sich.

  2. Navigieren Sie zu Azure Active Directory.

  3. Klicken Sie auf App Registrations.

  4. Klicken Sie auf New Registration.

  5. Geben Sie einen Namen für den Client ein, z. B. Snowflake OAuth Client.

  6. Stellen Sie sicher, dass die unterstützten Kontotypen auf „Single Tenant“ (Einzelner Mandant) eingestellt sind.

  7. Klicken Sie auf Register.

  8. Kopieren Sie im Abschnitt Overview die ClientID aus dem Feld Application (client) ID. Diese wird in den folgenden Schritten als <OAUTH_CLIENT_ID> bezeichnet.

  9. Klicken Sie auf Certificates & secrets und dann auf New client secret.

  10. Fügen Sie eine Beschreibung des Geheimnisses hinzu.

  11. Wählen Sie never expire (Niemals ablaufen) aus. Wählen Sie zu Testzwecken Geheimnisse aus, die niemals ablaufen.

  12. Klicken Sie auf Add. Kopieren Sie das Geheimnis. Dies wird in den folgenden Schritten als <OAUTH_CLIENT_SECRET> bezeichnet.

  13. Konfigurieren Sie für programmgesteuerte Clients, die im Namen eines Benutzers ein Zugriffstoken anfordern, die delegierten Berechtigungen für Anwendungen wie folgt.

    • Klicken Sie auf API Permissions.

    • Klicken Sie auf Add Permission.

    • Klicken Sie auf My APIs.

    • Klicken Sie auf den Clientnamen Snowflake OAuth Resource, den Sie in Schritt 1: Konfigurieren der OAuth-Ressource in Azure AD erstellt haben.

    • Klicken Sie auf das Feld Delegated Permissions.

    • Überprüfen Sie die Berechtigung für die in der Anwendung definierten Bereiche, die Sie diesem Client erteilen möchten.

    • Klicken Sie auf Add Permissions.

    • Klicken Sie auf die Schaltfläche Grant Admin Consent, um dem Client die Berechtigungen zu erteilen. Beachten Sie, dass das Konfigurieren der Berechtigungen auf diese Weise zu Testzwecken erfolgt. In einer Produktionsumgebung ist es nicht ratsam, Berechtigungen auf diese Weise zu erteilen.

    • Klicken Sie auf Yes.

  14. Konfigurieren Sie API permissions for Applications für programmgesteuerte Clients, die ein Zugriffstoken für sich selbst anfordern, wie folgt.

    • Klicken Sie auf API Permissions.

    • Klicken Sie auf Add Permission.

    • Klicken Sie auf My APIs.

    • Klicken Sie auf den Clientnamen Snowflake OAuth Resource, den Sie in Schritt 1: Konfigurieren der OAuth-Ressource in Azure AD erstellt haben.

    • Klicken Sie auf Application Permissions.

    • Überprüfen Sie unter Permission die Berechtigung in Bezug auf die Rollen, die manuell im Manifest für die Anwendung definiert sind, die Sie diesem Client gewähren möchten.

    • Klicken Sie auf Add Permissions.

    • Klicken Sie auf die Schaltfläche Grant Admin Consent, um dem Client die Berechtigungen zu erteilen. Beachten Sie, dass die Konfiguration der Berechtigungen auf diese Weise zu Testzwecken erfolgt. In einer Produktionsumgebung ist es nicht ratsam, Berechtigungen auf diese Weise zu erteilen.

    • Klicken Sie auf Yes.

Schritt 3: Azure AD-Informationen für Snowflake erfassen

  1. Navigieren Sie zum Microsoft Azure Portal, und authentifizieren Sie sich.

  2. Navigieren Sie zu Azure Active Directory.

  3. Klicken Sie auf App Registrations.

  4. Klicken Sie auf den Clientnamen Snowflake OAuth Resource, den Sie in Schritt 1: Konfigurieren der OAuth-Ressource in Azure AD erstellt haben.

  5. Klicken Sie auf der Overview-Benutzeroberfläche auf Endpoints.

  6. Kopieren Sie auf der rechten Seite den OAuth 2.0 token endpoint (v2), und notieren Sie die URLs für OpenID Connect metadata und Federation Connect metadata.

    • Der OAuth 2.0 token endpoint (v2) wird in den folgenden Konfigurationsschritten als <AZURE_AD_OAUTH_TOKEN_ENDPOINT> bezeichnet. Der Endpunkt sollte https://login.microsoftonline.com/90288a9b-97df-4c6d-b025-95713f21cef9/oauth2/v2.0/token ähneln.

    • Öffnen Sie für die OpenID Connect metadata ein neues Browserfenster.

      • Suchen Sie den Parameter "jwks_uri", und kopieren Sie seinen Wert.

      • Dieser Parameterwert wird in den folgenden Konfigurationsschritten als <AZURE_AD_JWS_KEY_ENDPOINT> bezeichnet. Der Endpunkt sollte https://login.microsoftonline.com/90288a9b-97df-4c6d-b025-95713f21cef9/discovery/v2.0/keys ähneln.

    • Öffnen Sie die URL des Federation metadata document in einem neuen Browserfenster.

      • Suchen Sie in XML Root Element den Parameter "entityID", und kopieren Sie den Wert.

      • Dieser Parameterwert wird in den folgenden Konfigurationsschritten als <AZURE_AD_ISSUER> bezeichnet. Der entityID-Wert sollte https://sts.windows.net/90288a9b-97df-4c6d-b025-95713f21cef9/) ähneln.

Schritt 4: OAuth-Autorisierungsserver in Snowflake erstellen

Bei diesem Schritt wird eine Sicherheitsintegration in Snowflake erstellt, die dafür sorgt, dass Snowflake sicher mit Microsoft Azure AD kommunizieren, die Token von Azure AD validieren und Benutzern den entsprechenden Snowflake-Datenzugriff basierend auf der dem OAuth-Token zugeordneten Benutzerrolle bereitstellen kann.

Wählen Sie die Sicherheitsintegration aus, die Ihren Anwendungsfällen und Konfigurationsanforderungen am besten entspricht. Wenn Ihre Integration nur auf der vorherigen Konfiguration basiert, verwenden Sie die erste Sicherheitsintegration. Weitere Informationen dazu finden Sie unter CREATE SECURITY INTEGRATION.

Wichtig

Wenn Sie versuchen, eine Sicherheitsintegration für Microsoft Power BI zu erstellen, befolgen Sie die Installationsanweisungen unter Power BI SSO zu Snowflake.

Dieser SQL-Befehl kann nur von Kontoadministratoren (d. h. Benutzern mit der Rolle ACCOUNTADMIN) 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 in Ihrer Umgebung mit diesen Werten übereinstimmen. Wenn der Fall nicht übereinstimmt, wird das Zugriffstoken möglicherweise nicht validiert, was zu einem fehlgeschlagenen Authentifizierungsversuch führt.

Stellen Sie sicher, dass alle Werte genau übereinstimmen. Wenn der Wert für den Aussteller („Issuer“) beispielsweise nicht mit einem Backslash endet und die Sicherheitsintegration mit einem Backslash am Ende der URL erstellt wird, wird eine Fehlermeldung angezeigt. Es wäre dann notwendig, das Sicherheitsintegrationsobjekt zu löschen (mit DROP INTEGRATION) und das Objekt dann erneut mit dem korrekten Ausstellerwert zu erstellen (mit CREATE SECURITY INTEGRATION).

OAuth-Autorisierungsserver erstellen

create security integration external_oauth_azure_1
    type = external_oauth
    enabled = true
    external_oauth_type = azure
    external_oauth_issuer = '<AZURE_AD_ISSUER>'
    external_oauth_jws_keys_url = '<AZURE_AD_JWS_KEY_ENDPOINT>'
    external_oauth_token_user_mapping_claim = 'upn'
    external_oauth_snowflake_user_mapping_attribute = 'login_name';

OAuth-Autorisierungsserver mit Zielgruppen erstellen

Wenn die beim Erstellen der Snowflake OAuth-Ressourcenanwendung in Azure AD eingegebene Application ID URI nicht die Snowflake-Konto-URL (d. h. <Konto>.<Region>.snowflakecomputing.com) ist, fügen Sie dem Befehl den Parameter external_oauth_audience_list mit dem Wert <SNOWFLAKE_APPLICATION_ID_URI> hinzu.

create security integration external_oauth_azure_2
    type = external_oauth
    enabled = true
    external_oauth_type = azure
    external_oauth_issuer = '<AZURE_AD_ISSUER>'
    external_oauth_jws_keys_url = '<AZURE_AD_JWS_KEY_ENDPOINT>'
    external_oauth_audience_list = ('<SNOWFLAKE_APPLICATION_ID_URI>')
    external_oauth_token_user_mapping_claim = 'upn'
    external_oauth_snowflake_user_mapping_attribute = 'login_name';

Ändern der 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 Azure AD als Autorisierungsserver müssen Sie Folgendes tun:

  1. Stellen Sie sicher, dass der Testbenutzer in Azure AD 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 <AZURE_AD_USER_USERNAME> gesetzt ist.

  3. Erteilen Sie diesem Benutzer die Rolle SYSADMIN.

  4. Registrieren Sie einen OAuth-Client.

  5. Ermöglichen Sie dem OAuth-Client, wie folgt eine POST-Anforderung an den Azure AD-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

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" \
  --data-urlencode "client_id=<OAUTH_CLIENT_ID>" \
  --data-urlencode "client_secret=<OAUTH_CLIENT_SECRET>" \
  --data-urlencode "username=<AZURE_AD_USER>" \
  --data-urlencode "password=<AZURE_AD_USER_PASSWORD>" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "scope=<SCOPE_AS_IT_APPEARS_IN_AZURE_APP>" \
  '<AZURE_AD_OAUTH_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.