CREATE SECURITY INTEGRATION (External OAuth)

Erstellt eine neue External OAuth-Sicherheitsintegration im Konto oder ersetzt eine vorhandene Integration. Eine External OAuth-Sicherheitsintegration ermöglicht es einem Client, einen Autorisierungsserver eines Drittanbieters zu verwenden, um die für die Interaktion mit Snowflake erforderlichen Zugriffstoken zu erhalten.

Weitere Informationen zum Erstellen anderer Typen von Sicherheitsintegrationen (z. B. Snowflake OAuth) finden Sie unter CREATE SECURITY INTEGRATION.

Siehe auch:

ALTER SECURITY INTEGRATION (External OAuth), DROP INTEGRATION, SHOW INTEGRATIONS

Syntax

CREATE [ OR REPLACE ] SECURITY INTEGRATION [IF NOT EXISTS]
  <name>
  TYPE = EXTERNAL_OAUTH
  ENABLED = { TRUE | FALSE }
  EXTERNAL_OAUTH_TYPE = { OKTA | AZURE | PING_FEDERATE | CUSTOM }
  EXTERNAL_OAUTH_ISSUER = '<string_literal>'
  EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = { '<string_literal>' | ('<string_literal>' [ , '<string_literal>' , ... ] ) }
  EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = { 'LOGIN_NAME' | 'EMAIL_ADDRESS' }
  [ EXTERNAL_OAUTH_JWS_KEYS_URL = { '<string_literal>' | ('<string_literal>' [ , '<string_literal>' , ... ] ) } ]
  [ EXTERNAL_OAUTH_BLOCKED_ROLES_LIST = ( '<role_name>' [ , '<role_name>' , ... ] ) ]
  [ EXTERNAL_OAUTH_ALLOWED_ROLES_LIST = ( '<role_name>' [ , '<role_name>' , ... ] ) ]
  [ EXTERNAL_OAUTH_RSA_PUBLIC_KEY = <public_key1> ]
  [ EXTERNAL_OAUTH_RSA_PUBLIC_KEY_2 = <public_key2> ]
  [ EXTERNAL_OAUTH_AUDIENCE_LIST = { '<string_literal>' | ('<string_literal>' [ , '<string_literal>' , ... ] ) } ]
  [ EXTERNAL_OAUTH_ANY_ROLE_MODE = { DISABLE | ENABLE | ENABLE_FOR_PRIVILEGE } ]
  [ EXTERNAL_OAUTH_SCOPE_DELIMITER = '<string_literal>' ]
  [ EXTERNAL_OAUTH_SCOPE_MAPPING_ATTRIBUTE = '<string_literal>' ]
  [ COMMENT = '<string_literal>' ]
Copy

Erforderliche Parameter

name

Zeichenfolge, die den Bezeichner (d. h. den Namen) für die Integration angibt. Muss in Ihrem Konto eindeutig sein.

Darüber hinaus muss der Bezeichner mit einem Buchstaben beginnen und darf keine Leer- oder Sonderzeichen enthalten, es sei denn, die gesamte Bezeichnerzeichenfolge wird in doppelte Anführungszeichen gesetzt (z. B. "My object"). Bei Bezeichnern, die in doppelte Anführungszeichen eingeschlossen sind, ist auch die Groß-/Kleinschreibung zu beachten.

Weitere Details dazu finden Sie unter Anforderungen an Bezeichner.

TYPE = EXTERNAL_OAUTH

Unterscheidet die External OAuth-Integration von einer Snowflake OAuth-Integration.

ENABLED = { TRUE | FALSE }

Gibt an, ob die Integrationsoperation gestartet oder angehalten werden soll.

  • TRUE ermöglicht die Ausführung der Integration basierend auf den in der Pipedefinition angegebenen Parametern.

  • FALSE hält die Integration für Wartungszwecke an. Eine Integration zwischen Snowflake und einem Drittanbieterdienst funktioniert nicht.

EXTERNAL_OAUTH_TYPE = { OKTA | AZURE | PING_FEDERATE | CUSTOM }

Gibt den OAuth 2.0-Autorisierungsserver als Okta, Microsoft Azure AD, Ping Identity PingFederate oder einen kundenspezifischen OAuth 2.0-Autorisierungsserver an.

EXTERNAL_OAUTH_ISSUER = 'string_literal'

Gibt die URL für die Definition des OAuth 2.0-Autorisierungsservers an.

EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = { 'string_literal' | ('string_literal' [ , 'string_literal' , ... ] ) }

Gibt den Zugriffstoken-Anspruch oder Ansprüche an, um das Zugriffstoken einem Benutzerdatensatz zuzuordnen.

Der Datentyp des Anspruchs muss eine Zeichenfolge oder eine Liste von Zeichenfolgen sein.

EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = { 'LOGIN_NAME' | 'EMAIL_ADDRESS' }

Gibt an, welches Attribut des Snowflake-Benutzerdatensatzes verwendet werden soll, um das Zugriffstoken einem Benutzerdatensatz zuzuordnen.

Optionale Parameter

EXTERNAL_OAUTH_JWS_KEYS_URL = { 'string_literal' | ('string_literal' [ , 'string_literal' , ... ] ) }

Gibt die URL oder eine Liste von URLs an, von denen Sie öffentliche Schlüssel oder Zertifikate herunterladen können, um ein External OAuth-Zugriffstoken zu validieren.

Wenn Sie den Parameter EXTERNAL_OAUTH_TYPE auf AZURE setzen, können Sie maximal drei URLs angeben. Um beispielsweise zwei URLs anzugeben, verwenden Sie die folgende Syntax:

EXTERNAL_OAUTH_JWS_KEYS_URL = ('https://example.ca', 'https://example.co.uk')
Copy

Wenn Sie den Parameter EXTERNAL_OAUTH_TYPE auf OKTA, PING_FEDERATE oder CUSTOM setzen, können Sie nur eine URL angeben. Beispiel:

EXTERNAL_OAUTH_JWS_KEYS_URL = 'https://example.ca'
Copy
EXTERNAL_OAUTH_RSA_PUBLIC_KEY = public_key1

Gibt einen Base64-codierten öffentlichen RSA-Schlüssel ohne die Header -----BEGIN PUBLIC KEY----- und -----END PUBLIC KEY----- an.

EXTERNAL_OAUTH_RSA_PUBLIC_KEY_2 = public_key2

Gibt einen zweiten öffentlichen RSA-Schlüssel ohne die Header -----BEGIN PUBLIC KEY----- und -----END PUBLIC KEY----- an. Wird für die Schlüsselrotation verwendet.

EXTERNAL_OAUTH_BLOCKED_ROLES_LIST = ( 'role_name' [ , 'role_name' , ... ] )

Gibt die Liste der Rollen an, die ein Client nicht als Primärrolle festlegen darf. Eine Rolle in dieser Liste darf nicht verwendet werden, wenn eine Snowflake-Sitzung auf Basis des Zugriffstokens vom externen OAuth-Autorisierungsserver erstellt wird.

Diese Liste enthält standardmäßig die Rollen ACCOUNTADMIN, ORGADMIN und SECURITYADMIN. Um diese mit Berechtigungen ausgestatteten Rollen aus der Liste zu entfernen, setzen Sie mit dem Befehl ALTER ACCOUNT den Kontoparameter EXTERNAL_OAUTH_ADD_PRIVILEGED_ROLES_TO_BLOCKED_LIST auf FALSE.

EXTERNAL_OAUTH_ALLOWED_ROLES_LIST = ( 'role_name' [ , 'role_name' , ... ] )

Gibt die Liste der Rollen an, die ein Client als Primärrolle festlegen kann.

Eine Rolle in dieser Liste darf verwendet werden, wenn eine Snowflake-Sitzung auf Basis des Zugriffstokens vom externen OAuth-Autorisierungsserver erstellt wird.

Vorsicht

Dieser Parameter unterstützt die Systemrollen ACCOUNTADMIN, ORGADMIN und SECURITYADMIN.

Seien Sie vorsichtig, wenn Sie beim Erstellen einer Snowflake-Sitzung eine Rolle mit derart umfangreichen Berechtigungen als Primärrolle auswählen.

EXTERNAL_OAUTH_AUDIENCE_LIST = { 'string_literal' | ('string_literal' [ , 'string_literal' , ... ] ) }

Gibt zusätzlich zur Verwendung der Snowflake-Konto-URL des Kunden weitere Werte für Zielgruppenvalidierung des Zugriffstokens an (d. h. <Kontobezeichner>.snowflakecomputing.com). Weitere Informationen dazu finden Sie unter Kontobezeichner.

Weitere Informationen zu diesem Parameter bei Verwendung von Power BI SSO finden Sie unter Power BI SSO-Sicherheitsintegrationen.

Derzeit können mehrere Zielgruppen-URLs nur für kundenspezifische External OAuth-Clients angegeben werden. Jede URL muss in einfache Anführungszeichen gesetzt werden, wobei jede URL durch ein Komma getrennt wird. Beispiel:

EXTERNAL_OAUTH_AUDIENCE_LIST = ('https://example.com/api/v2/', 'https://example.com')
Copy
EXTERNAL_OAUTH_ANY_ROLE_MODE = { DISABLE | ENABLE | ENABLE_FOR_PRIVILEGE }

Gibt an, ob der OAuth-Client oder -Benutzer eine Rolle verwenden kann, die nicht im OAuth-Zugriffstoken definiert ist. Beachten Sie, dass bei einer Power BI-Snowflake-Integration der PowerBI-Benutzer keine Rollen wechseln kann, selbst wenn dieser Parameter aktiviert ist.

  • DISABLE erlaubt dem OAuth-Client oder -Benutzer nicht, die Rollen zu wechseln (d. h. USE ROLE role;). 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;
    
    Copy
    REVOKE USE_ANY_ROLE ON INTEGRATION external_oauth_1 FROM role1;
    
    Copy

Beachten Sie, dass der Wert optional in einfache Anführungszeichen gesetzt werden kann (z. B. entweder DISABLE oder 'DISABLE').

EXTERNAL_OAUTH_SCOPE_DELIMITER = 'string_literal'

Gibt das Trennzeichen für die Geltungsbereiche im Autorisierungstoken an, das das Standard-Trennzeichen ',' überschreibt. Das Trennzeichen kann ein beliebiges einzelnes Zeichen sein, z. B. ein Komma (',') oder ein Leerzeichen (' ').

Sie können diese Eigenschaft nur verwenden, wenn Sie den Parameter EXTERNAL_OAUTH_TYPE auf CUSTOM setzen.

EXTERNAL_OAUTH_SCOPE_MAPPING_ATTRIBUTE = 'string_literal'

Gibt den Zugriffstoken-Anspruch an, um das Zugriffstoken einer Kontorolle zuzuordnen.

Sie können diesen Parameter nur auf scp oder scope setzen.

Sie können diesen Parameter nur verwenden, wenn Sie den Parameter EXTERNAL_OAUTH_TYPE auf CUSTOM gesetzt haben.

COMMENT = 'string_literal'

Gibt einen Kommentar für die Integration an.

Standard: Kein Wert

Anforderungen an die Zugriffssteuerung

Eine Rolle, die zur Ausführung dieses SQL-Befehls verwendet wird, muss mindestens die folgenden Berechtigungen haben:

Berechtigung

Objekt

Anmerkungen

CREATE INTEGRATION

Konto

Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

Eine Anleitung zum Erstellen einer kundenspezifischen Rolle mit einem bestimmten Satz von Berechtigungen finden Sie unter Erstellen von kundenspezifischen Rollen.

Allgemeine Informationen zu Rollen und Berechtigungen zur Durchführung von SQL-Aktionen auf sicherungsfähigen Objekten finden Sie unter Übersicht zur Zugriffssteuerung.

Nutzungshinweise

  • Metadaten:

    Achtung

    Kunden müssen sicherstellen, dass bei der Nutzung des Snowflake-Dienstes keine personenbezogenen Daten (außer für ein Objekt „Benutzer“), sensible Daten, exportkontrollierte Daten oder andere regulierte Daten als Metadaten eingegeben werden. Weitere Informationen dazu finden Sie unter Metadatenfelder in Snowflake.

  • CREATE OR REPLACE <Objekt>-Anweisungen sind atomar. Das heißt, wenn ein Objekt ersetzt wird, erfolgt das Löschen des alten Objekts und das Erstellen des neuen Objekts in einer einzigen Transaktion.

Beispiele

Beispiel für Microsoft Azure AD

Im folgenden Beispiel wird eine External OAuth-Sicherheitsintegration für einen Microsoft Azure AD-OAuth 2.0-Autorisierungsserver erstellt.

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';
Copy

Zeigen Sie mit DESCRIBE INTEGRATION die Integrationseinstellungen an:


Copy

DESC SECURITY INTEGRATION external_oauth_azure_1;

Beispiel für Okta

Im folgenden Beispiel wird eine External OAuth-Sicherheitsintegration für einen Okta-OAuth 2.0-Autorisierungsserver erstellt.

CREATE SECURITY INTEGRATION external_oauth_okta_1
    TYPE = external_oauth
    ENABLED = true
    EXTERNAL_OAUTH_TYPE = okta
    EXTERNAL_OAUTH_ISSUER = '<OKTA_ISSUER>'
    EXTERNAL_OAUTH_JWS_KEYS_URL = '<OKTA_JWS_KEY_ENDPOINT>'
    EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = 'sub'
    EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'login_name';
Copy

Zeigen Sie mit DESCRIBE INTEGRATION die Integrationseinstellungen an:

DESC SECURITY INTEGRATION external_oauth_okta_1;
Copy

Beispiel für Microsoft Power BI SSO

Weitere Beispiele finden Sie unter: