Demander aux consommateurs une autorisation OAuth¶

Ce chapitre décrit comment utiliser le type de configuration SECRET_AUTHORIZATION pour activer un flux d’autorisation OAuth par code dans une Snowflake Native App. Il s’agit d’un flux spécialisé pour le type d’intégration de sécurité``AUTHORIZATION_CODE`` décrit dans Demande de connexion OAuth.

Vue d’ensemble¶

Certaines Snowflake Native Apps exigent des consommateurs qu’ils s’authentifient auprès d’un service tiers avant que l’application puisse accéder aux ressources externes en leur nom. Le flux d’autorisation par code d’autorisation permet aux consommateurs de procéder directement à l’authentification OAuth, sans fournir des identifiants de connexion au fournisseur de l’application.

Le fournisseur configure l’intégration OAuth et le secret dans le script d’installation de l’application. Le consommateur complète ensuite un flux de consentement OAuth standard pour autoriser la connexion. Une fois le consommateur authentifié, l’application peut utiliser les jetons résultants pour accéder aux ressources externes.

Configuration du fournisseur¶

Étape 1 : Créer une intégration de sécurité¶

Créez une intégration de sécurité de type``API_AUTHENTICATION`` avec le flux d’autorisation par code d’autorisation. Pour plus d’informations, voir CREATE SECURITY INTEGRATION (authentification API externe).

CREATE SECURITY INTEGRATION oauth_integration
  TYPE = API_AUTHENTICATION
  AUTH_TYPE = OAUTH2
  OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_POST
  OAUTH_CLIENT_ID = '<client_id>'
  OAUTH_CLIENT_SECRET = '<client_secret>'
  OAUTH_GRANT = 'AUTHORIZATION_CODE'
  OAUTH_TOKEN_ENDPOINT = 'https://provider.example.com/oauth2/token'
  OAUTH_AUTHORIZATION_ENDPOINT = 'https://provider.example.com/oauth2/authorize'
  ENABLED = TRUE;

Étape 2 : Créer un secret¶

Créez un secret lié à l’intégration de sécurité :

CREATE SECRET app_schema.oauth_secret
  TYPE = oauth2
  API_AUTHENTICATION = oauth_integration;

Étape 3 : Créer une spécification d’application¶

Créez une spécification d’application pour l’intégration de sécurité afin que le consommateur puisse examiner et approuver les détails de la connexion OAuth. Pour plus d’informations, voir Demande de connexion OAuth.

ALTER APPLICATION SET SPECIFICATION oauth_spec
  TYPE = SECURITY_INTEGRATION
  LABEL = 'OAuth connection to external provider'
  DESCRIPTION = 'Connects to external provider using Authorization Code grant'
  OAUTH_TYPE = 'AUTHORIZATION_CODE'
  OAUTH_TOKEN_ENDPOINT = 'https://provider.example.com/oauth2/token'
  OAUTH_AUTHORIZATION_ENDPOINT = 'https://provider.example.com/oauth2/authorize';

L’approbation de la spécification de l’application permet au consommateur d’approuver les métadonnées de connexion OAuth, mais il ne complète pas l’authentification. Le consommateur doit également compléter le flux OAuth décrit dans Authentification du consommateur, qui est piloté par la configuration que vous créez à l’étape 5.

Étape 4 : Accorder l’accès aux rôles d’application pour compléter le flux OAuth¶

Autorisez USAGE sur l’intégration de sécurité et MODIFY sur le secret aux rôles d’application qui ont besoin d’un accès :

GRANT USAGE ON INTEGRATION oauth_integration TO APPLICATION ROLE app_user;
GRANT MODIFY ON SECRET app_schema.oauth_secret TO APPLICATION ROLE app_user;

Sans ces autorisations, les consommateurs ne peuvent pas compléter le flux OAuth et peuvent rencontrer une erreur d’autorisation sans contexte supplémentaire.

Étape 5 : Créer la configuration SECRET_AUTHORIZATION¶

Créez une configuration SECRET_AUTHORIZATION qui coordonne le flux OAuth côté consommateur :

ALTER APPLICATION SET CONFIGURATION DEFINITION oauth_config
  TYPE = SECRET_AUTHORIZATION
  SECRET = app_schema.oauth_secret
  LABEL = 'Authenticate with external provider'
  DESCRIPTION = 'Complete the OAuth flow to connect the app to the external provider'
  APPLICATION_ROLES = (app_user);

Le paramètre SECRET spécifie le secret qui est renseigné avec les jetons lorsque le consommateur complète le flux OAuth. Vous pouvez spécifier le secret comme <schema_name>.<secret_name> (la propre base de données de l’application est implicite) ou comme <database_name>.<schema_name>.<secret_name> complet. Dans l’une ou l’autre forme, le secret doit être la propriété de l’application et les rôles d’application spécifiés dans``APPLICATION_ROLES`` doivent avoir le privilège MODIFY sur le secret.

Étape 6 : Utiliser des jetons OAuth dans le code de l’application¶

Une fois que le consommateur a complété le flux OAuth, le secret est renseigné par le jeton d’accès que l’application peut utiliser dans les appels d’accès externes. Transmettez le secret à une UDF, une procédure stockée ou un conteneur Snowpark Container Services via la propriété SECRETS de l’objet :

Pour les UDFs et procédures stockées, voir Accès à l’API Google Translate avec OAuth pour un exemple complet qui utilise``_snowflake.get_oauth_access_token`` pour récupérer le jeton.
Pour Snowpark Container Services, voir Transmission d’identifiants de connexion à un conteneur à l’aide de secrets Snowflake pour savoir comment transmettre le secret à un conteneur lors de l’exécution.

Authentification du consommateur¶

Une fois que le fournisseur a configuré l’application, le consommateur complète l’authentification OAuth à l’aide de|sf-web-interface|, le|native-app-perms| ouSQL.

Important

Avant de compléter le flux OAuth, le consommateur doit d’abord approuver la spécification de l’application d’intégration de sécurité correspondante. Pour plus d’informations, voir Approve app specifications.

Connectez-vous à|sf-web-interface| en utilisant un rôle auquel un rôle d’application a été attribué avec accès à la configurationOAuth. Compléter le flux OAuth nécessite le privilège MODIFYVALUE sur la configuration, qui est accordé aux rôles d’application répertoriés dans le paramètre APPLICATION_ROLES lorsque le fournisseur crée la configuration.

Si la spécification de l’application d’intégration de sécurité n’est pas déjà approuvée, le rôle a également besoin du privilège MANAGE APPLICATION SPECIFICATIONS sur le compte pour l’approuver. Pour plus d’informations, voir Approve app specifications.
Accédez à la page de l’application.
Dans la page d’application, sélectionnez l’onglet Configurations.
Sous External connections, cliquez sur Review et approuvez l’intégration de sécurité.

Note

La spécification de l’application d’intégration de sécurité correspondante doit être approuvée avant l’authentification. Si elle n’est pas approuvée, le flux échoue avec l’erreur suivante : Applications can not use security integration without a corresponding approved application specification.
Sous Authentication, cliquez sur Review, puis cliquez sur Authenticate sur la configuration OAuth.
Complétez le flux de consentement OAuth dans la fenêtre contextuelle du navigateur.
Une fois l’authentification réussie, le statut de la configuration est automatiquement mis à jour.

Si l’application dispose d’une interface Streamlit, le fournisseur peut appeler request_application_configuration_value() pour inviter le consommateur à compléter le flux OAuth directement à partir de l’application :

from snowflake.permissions import request_application_configuration_value

request_application_configuration_value(config_names=['oauth_config'])

Le SDK superpose la boîte de dialogue de configuration sur l’application Streamlit. Lorsque le consommateur complète le flux OAuth dans la boîte de dialogue, le statut de la configuration est automatiquement mis à jour. Pour plus d’informations, voir request_application_configuration_value().

Étape 1 : Identifier le nom du secret

Le nom de secret utilisé dans le flux OAuth est le nom complet au format <database_name>.<schema_name>.<secret_name>, où <database_name> est le nom sous lequel l’application est installée dans le compte du consommateur.

Les fournisseurs documentent généralement le nom du secret dans le guide d’installation de leur application. S’il n’est pas documenté, vous pouvez le récupérer à partir de la colonne additionalProperties de la configuration :

SHOW CONFIGURATIONS IN APPLICATION example_app;

DESCRIBE CONFIGURATION oauth_config IN APPLICATION example_app;

La colonne additionalProperties contient une chaîne JSON avec le nom secret :

{
  "secret": "database_name.schema_name.secret_name"
}

Étape 2 : Compléter le flux OAuth

Exécutez SYSTEM$START_OAUTH_FLOW avec le nom secret pour obtenir une URL d’autorisation, puis ouvrez l’URL dans un navigateur pour compléter le processus de consentement OAuth :

SELECT SYSTEM$START_OAUTH_FLOW('database_name.schema_name.secret_name');

Après avoir complété le consentement dans le navigateur, exécutez SYSTEM$FINISH_OAUTH_FLOW dans la même session avec la chaîne de requête de la redirection du navigateur URL :

SELECT SYSTEM$FINISH_OAUTH_FLOW('query_string_from_redirect');

Étape 3 : Définir la configuration sur configuré

Une fois que le flux OAuth est complété, définissez la valeur de la configuration sur configured :

ALTER APPLICATION example_app SET CONFIGURATION oauth_config VALUE = 'configured';

Note

La valeur de la configuration peut uniquement être définie sur configured. Aucune autre valeur n’est acceptée. La définition de cette valeur signale à l’application que le flux OAuth est complété. Les jetons réels sont stockés dans le secret ; la valeur de la configuration ne déclenche que les rappels de configuration.

Le Snowflake Native App Framework vérifie automatiquement que le secret est rempli de jetons, puis déclenche les rappels before_configuration_change et``after_configuration_change``.

Pour annuler la configuration ultérieurement, utilisez :

ALTER APPLICATION example_app UNSET CONFIGURATION oauth_config;

Cela déclenche également les rappels before_configuration_change et after_configuration_change.

Avertissement

La désactivation de la configuration n’invalide pas et ne révoque pas les jetons OAuth stockés dans le secret. Pour empêcher l’application d’utiliser les jetons, déclinez la spécification d’application d’intégration de sécurité correspondante. Pour révoquer complètement les jetons au niveau du fournisseur, utilisez le processus de révocation de jetons du fournisseur tiers. Pour plus d’informations, voir Approve app specifications.

Expiration du jeton et réauthentification¶

Snowflake utilise le jeton d’actualisation stocké dans le secret pour obtenir un nouveau jeton d’accès lorsque le jeton d’accès actuel expire. Si le jeton d’actualisation lui-même expire ou est révoqué par le fournisseur tiers, les appels d’accès externe à partir de l’application échouent et le consommateur doit se réauthentifier.

Les fournisseurs peuvent inviter les consommateurs à se réauthentifier via Snowsight, les Python Permission SDK, ou SQL.

Dirigez les consommateurs vers l’onglet Configurations sur la page de l’application. Sous Authentication, cliquez sur Reauthenticate sur la configuration OAuth pour actualiser les jetons.

Si l’application dispose d’une interface Streamlit, appelez request_application_configuration_value() pour superposer la boîte de dialogue de configuration sur l’application Streamlit et inviter le consommateur à se réauthentifier :

from snowflake.permissions import request_application_configuration_value

request_application_configuration_value(config_names=['oauth_config'])

Les consommateurs peuvent réexécuter SYSTEM$START_OAUTH_FLOW et SYSTEM$FINISH_OAUTH_FLOW sur le même secret pour actualiser les jetons. Pour redéclencher les rappels before_configuration_change et``after_configuration_change``, le consommateur doit définir à nouveau la valeur de la configuration :

ALTER APPLICATION example_app SET CONFIGURATION oauth_config VALUE = 'configured';