CREATE SECURITY INTEGRATION (External OAuth)

Crée une nouvelle intégration de sécurité External OAuth dans le compte ou remplace une intégration existante. Une intégration de sécurité External OAuth permet à un client d’utiliser un serveur d’autorisation tiers pour obtenir les jetons d’accès nécessaires pour interagir avec Snowflake.

Pour des informations sur la création d’autres types d’intégrations de sécurité (par exemple Snowflake OAuth), voir CREATE SECURITY INTEGRATION.

Voir aussi :

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

Syntaxe

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

Paramètres requis

name

Chaîne spécifiant l’identificateur (c’est-à-dire le nom) de l’intégration ; elle doit être unique sur votre compte.

De plus, l’identificateur doit commencer par un caractère alphabétique et ne peut pas contenir d’espaces ou de caractères spéciaux à moins que toute la chaîne d’identificateur soit délimitée par des guillemets doubles (p. ex. "My object"). Les identificateurs entre guillemets doubles sont également sensibles à la casse.

Pour plus de détails, voir Exigences relatives à l’identificateur.

TYPE = EXTERNAL_OAUTH

Distingue l’intégration External OAuth de l’intégration Snowflake OAuth.

ENABLED = { TRUE | FALSE }

Spécifie s’il faut initier le fonctionnement de l’intégration ou le suspendre.

  • TRUE permet l’exécution de l’intégration en fonction des paramètres spécifiés dans la définition de canal.

  • FALSE suspend l’intégration pour la maintenance. Toute intégration entre Snowflake et un service tiers échoue.

EXTERNAL_OAUTH_TYPE = { OKTA | AZURE | PING_FEDERATE | CUSTOM }

Indique que le serveur d’autorisation OAuth 2.0 doit être Okta, Microsoft Azure AD, Ping Identity PingFederate ou un serveur d’autorisation personnalisé OAuth 2.0.

EXTERNAL_OAUTH_ISSUER = 'string_literal'

Spécifie l’URL pour définir le serveur d’autorisation OAuth 2.0.

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

Spécifie la ou les revendications de jeton d’accès qui peuvent être utilisées pour mapper le jeton d’accès à un enregistrement utilisateur.

Le type de données de la revendication doit être une chaîne ou une liste de chaînes.

EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = { 'LOGIN_NAME' | 'EMAIL_ADDRESS' }

Indique quel attribut d’enregistrement utilisateur Snowflake doit être utilisé pour mapper le jeton d’accès à un enregistrement utilisateur.

Paramètres facultatifs

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

Spécifie l’URL ou une liste d’URLs à partir desquelles vous pouvez télécharger les clés publiques ou les certificats pour valider un jeton d’accès External OAuth.

Si vous réglez le paramètre EXTERNAL_OAUTH_TYPE sur AZURE, vous pouvez spécifier un maximum de trois URLs. Par exemple, pour spécifier deux URLs, utilisez la syntaxe suivante :

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

Si le paramètre EXTERNAL_OAUTH_TYPE est défini sur OKTA, PING_FEDERATE ou CUSTOM, vous ne pouvez spécifier qu’une seule URL. Par exemple :

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

Spécifie une clé publique RSA d’encodage Base64, sans les en-têtes -----BEGIN PUBLIC KEY----- et -----END PUBLIC KEY-----.

EXTERNAL_OAUTH_RSA_PUBLIC_KEY_2 = public_key2

Spécifie une deuxième clé publique RSA, sans les en-têtes -----BEGIN PUBLIC KEY----- et -----END PUBLIC KEY-----. Utilisée pour la rotation des clés.

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

Spécifie la liste des rôles qu’un client ne peut pas définir comme rôle principal. Un rôle de cette liste ne peut pas être utilisé lors de la création d’une session Snowflake basée sur le jeton d’accès du serveur d’autorisation External OAuth.

Par défaut, cette liste comprend les rôles ACCOUNTADMIN, ORGADMIN et SECURITYADMIN. Pour supprimer ces rôles à hauts privilèges de la liste, utilisez la commande ALTER ACCOUNT pour définir le paramètre de compte EXTERNAL_OAUTH_ADD_PRIVILEGED_ROLES_TO_BLOCKED_LIST sur FALSE.

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

Spécifie la liste des rôles que le client peut définir comme rôle principal.

Un rôle de cette liste peut être utilisé lors de la création d’une session Snowflake basée sur le jeton d’accès du serveur d’autorisation External OAuth.

Prudence

Ce paramètre prend en charge les rôles système ACCOUNTADMIN, ORGADMIN et SECURITYADMIN.

Faites preuve de prudence lorsque vous créez une session Snowflake avec ces rôles à hauts privilèges définis comme rôle principal.

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

Spécifie des valeurs supplémentaires pour la validation de l’audience du jeton d’accès en plus de l’utilisation de l’URL du compte Snowflake du client (c’est-à-dire, <identificateur_de_compte>.snowflakecomputing.com). Pour plus d’informations, voir Identificateurs de compte.

Pour plus de détails sur ce paramètre lorsque vous utilisez Power BI SSO, reportez-vous à Intégrations de sécurité Power BI SSO.

Actuellement, plusieurs URLs d’audience ne peuvent être spécifiées que pour les clients personnalisés External OAuth. Chaque URL doit être placée entre guillemets simples, avec une virgule séparant chaque URL. Par exemple :

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

Spécifie si le client ou l’utilisateur OAuth peut utiliser un rôle qui n’est pas défini dans le jeton d’accès OAuth. Notez qu’avec une intégration Power BI à Snowflake, l’utilisateur PowerBI ne peut pas changer de rôle même si ce paramètre est activé.

  • DISABLE n’autorise pas le client ou l’utilisateur OAuth à changer de rôle (c’est-à-dire USE ROLE role;). Par défaut.

  • ENABLE permet au client ou à l’utilisateur OAuth de changer de rôle.

  • ENABLE_FOR_PRIVILEGE permet au client ou à l’utilisateur OAuth de changer de rôle uniquement pour un client ou un utilisateur avec le privilège USE_ANY_ROLE. Ce privilège peut être accordé et révoqué à un ou plusieurs rôles disponibles pour l’utilisateur. Par exemple :

    GRANT USE_ANY_ROLE ON INTEGRATION external_oauth_1 TO role1;
    
    Copy
    REVOKE USE_ANY_ROLE ON INTEGRATION external_oauth_1 FROM role1;
    
    Copy

Notez que la valeur peut éventuellement être placée entre guillemets simples (par exemple, DISABLE ou 'DISABLE').

EXTERNAL_OAUTH_SCOPE_DELIMITER = 'string_literal'

Spécifie le délimiteur de champ d’application dans le jeton d’autorisation, supprimant ainsi le délimiteur par défaut, ','. Le délimiteur peut être un caractère unique quelconque, tel qu’une virgule (',') ou un espace (' ').

Vous ne pouvez utiliser cette propriété que si vous définissez le paramètre EXTERNAL_OAUTH_TYPE sur CUSTOM.

EXTERNAL_OAUTH_SCOPE_MAPPING_ATTRIBUTE = 'string_literal'

Spécifie la revendication de jeton d’accès qui peut être utilisée pour mapper le jeton d’accès à un rôle de compte.

Vous pouvez uniquement définir ce paramètre sur scp ou scope.

Vous ne pouvez utiliser ce paramètre que si vous définissez le paramètre EXTERNAL_OAUTH_TYPE sur CUSTOM.

COMMENT = 'string_literal'

Spécifie un commentaire pour l’intégration.

Par défaut : aucune valeur

Exigences en matière de contrôle d’accès

Un rôle utilisé pour exécuter cette commande SQL doit avoir les privilèges suivants définis au minimum ainsi :

Privilège

Objet

Remarques

CREATE INTEGRATION

Compte

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

Pour obtenir des instructions sur la création d’un rôle personnalisé avec un ensemble spécifique de privilèges, voir Création de rôles personnalisés.

Pour des informations générales sur les rôles et les privilèges accordés pour effectuer des actions SQL sur des objets sécurisables, voir Aperçu du contrôle d’accès.

Notes sur l’utilisation

  • Concernant les métadonnées :

    Attention

    Les clients doivent s’assurer qu’aucune donnée personnelle (autre que pour un objet utilisateur), donnée sensible, donnée à exportation contrôlée ou autre donnée réglementée n’est saisie comme métadonnée lors de l’utilisation du service Snowflake. Pour plus d’informations, voir Champs de métadonnées dans Snowflake.

  • Les instructions CREATE OR REPLACE <objet> sont atomiques. En d’autres termes, lorsqu’un objet est remplacé, l’ancien objet est supprimé et le nouvel objet est créé dans une seule transaction.

Exemples

Exemple Microsoft Azure AD

L’exemple suivant crée une intégration de sécurité External OAuth pour un serveur d’autorisation Microsoft Azure AD OAuth 2.0.

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

Afficher les paramètres d’intégration à l’aide de DESCRIBE INTEGRATION :


Copy

DESC SECURITY INTEGRATION external_oauth_azure_1;

Exemple Okta

L’exemple suivant crée une intégration de sécurité External OAuth pour un serveur d’autorisation Okta OAuth 2.0.

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

Afficher les paramètres d’intégration à l’aide de DESCRIBE INTEGRATION :

DESC SECURITY INTEGRATION external_oauth_okta_1;
Copy

Exemples Microsoft Power BI SSO

Pour des exemples, voir :