コンシューマーからの OAuth 認証リクエスト¶

このトピックでは、 SECRET_AUTHORIZATION 構成タイプを使用して Snowflake Native App で OAuth 認証コード付与フローを有効にする方法について説明します。これは、 Request OAuth connection で説明されている AUTHORIZATION_CODE セキュリティ統合型に特化したフローです。

概要¶

一部の Snowflake Native Apps では、アプリが代わりに外部リソースにアクセスする前に、サードパーティのサービスでコンシューマーに認証する必要があります。認証コード付与フローにより、コンシューマーはアプリのプロバイダーと認証情報を共有することなく、直接 OAuth 認証を完了できます。

プロバイダーは、アプリのセットアップスクリプトで OAuth 統合とシークレットを構成します。その後、コンシューマーは接続を承認するための標準 OAuth 同意フローを完了します。コンシューマーが認証を完了すると、アプリは生成されたトークンを使用して外部リソースにアクセスできます。

プロバイダーのセットアップ¶

ステップ1：セキュリティ統合を作成する¶

認証コード付与フローを使用して API_AUTHENTICATION 型のセキュリティ統合を作成します。詳細については、 CREATE SECURITY INTEGRATION （外部 API 認証）をご参照ください。

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;

ステップ2：シークレットを作成¶

セキュリティ統合にリンクされたシークレットを作成します。

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

ステップ3：アプリ仕様の作成¶

コンシューマーが OAuth 接続の詳細を確認して承認できるように、セキュリティ統合のアプリ仕様を作成します。詳細については、 Request OAuth connection をご参照ください。

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

アプリの仕様を承認すると、コンシューマーは OAuth 接続メタデータを承認できますが、認証は完了しません。コンシューマーはコンシューマー認証で説明されている OAuth フローも完了する必要があります。これは、ステップ5で作成した構成によって駆動されます。

ステップ4：アプリケーションロールに OAuth フローを完了するためのアクセスを付与します¶

アクセスを必要とするアプリケーションロールのセキュリティ統合に USAGE を付与し、シークレットに MODIFY を付与します。

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

これらの付与がないと、コンシューマーは OAuth フローを完了できず、追加のコンテキストなしで権限エラーが発生する場合があります。

ステップ5：SECRET_AUTHORIZATION 構成を作成する¶

コンシューマー側の OAuth フローを調整する SECRET_AUTHORIZATION 構成を作成します

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);

SECRET パラメーターは、コンシューマーが OAuth フローを完了したときにトークンが入力されるシークレットを指定します。シークレットは <schema_name>.<secret_name>``（アプリ自体のデータベースが暗示されます）または完全修飾 ``<database_name>.<schema_name>.<secret_name> として指定できます。いずれの形式でも、シークレットはアプリケーションに所有されている必要があり、 APPLICATION_ROLES で指定されたアプリケーションロールは、シークレットに対する MODIFY 権限を所有している必要があります。

ステップ6：アプリコードで OAuth トークンを使用する¶

コンシューマーが OAuth フローを完了した後、シークレットには、アプリが外部アクセス呼び出しで使用できるアクセストークンが入力されます。オブジェクトの SECRETS プロパティを介して、シークレットを UDF、ストアドプロシージャ、または Snowpark Container Services コンテナに渡します。

UDFs とストアドプロシージャについては、トークンを取得するために _snowflake.get_oauth_access_token を使用する完全な例として OAuth でGoogle翻訳 API へアクセスするをご参照ください。
Snowpark Container Servicesについては、実行時にコンテナにシークレットを渡す方法について Snowflakeシークレットを使用してコンテナーに認証情報を引き渡すをご参照ください。

コンシューマー認証¶

プロバイダーがアプリをセットアップした後、コンシューマーは Snowsight、 Python Permission SDK または SQL を使用して OAuth 認証を完了します。

重要

OAuth フローを完了する前に、コンシューマーはまず対応するセキュリティ統合アプリ仕様を承認する必要があります。詳細については、 Approve app specifications をご参照ください。

OAuth 構成へのアクセス権限を持つアプリケーションロールが付与されたロールを使用して、 Snowsight にサインインします。OAuth フローを完了するには、構成に MODIFYVALUE 権限が必要です。これはプロバイダーが構成を作成する際に APPLICATION_ROLES パラメーターにリストされたアプリケーションロールに付与されます。

セキュリティ統合アプリの仕様がまだ承認されていない場合、ロールはアカウント上でそれを承認するための MANAGEAPPLICATIONSPECIFICATIONS 権限も必要です。詳細については、 Approve app specifications をご参照ください。
アプリのページに移動します。
アプリケーションページで、 Configurations タブを選択します。
External connections で、 Review をクリックしてセキュリティ統合を承認します。

注釈

認証の前に、対応するセキュリティ統合アプリ仕様を承認する必要があります。承認されない場合、フローは以下のエラーで失敗します。 Applications can not use security integration without a corresponding approved application specification.
Authentication で、 Review をクリックし、次に OAuth 構成の Authenticate をクリックします。
ブラウザーポップアップで OAuth 同意フローを完了します。
認証に成功すると、構成ステータスが自動的に更新されます。

アプリにStreamlitフロントエンドがある場合、プロバイダーは :ref:` request_application_configuration_value（）<label_request_application_configuration_value>` を呼び出して、コンシューマーにアプリから直接 OAuth フローを完了することを促すことができます。

from snowflake.permissions import request_application_configuration_value

request_application_configuration_value(config_names=['oauth_config'])

SDK は、Streamlitアプリの上部にある構成ダイアログをオーバーレイします。コンシューマーがダイアログで OAuth フローを完了すると、構成ステータスは自動的に更新されます。詳細については、 request_application_configuration_value() をご参照ください。

ステップ1:シークレット名を特定する

OAuth フローで使用されるシークレット名は、 <database_name>.<schema_name>.<secret_name> 形式の完全修飾名で、 <database_name> は、コンシューマーアカウントにアプリがインストールされている名前です。

通常、プロバイダーはアプリのインストールガイドにシークレット名を文書化します。ドキュメント化されていない場合は、構成の additionalProperties 列から取得できます。

SHOW CONFIGURATIONS IN APPLICATION example_app;

DESCRIBE CONFIGURATION oauth_config IN APPLICATION example_app;

additionalProperties 列には、シークレット名を持つ JSON 文字列が含まれます：

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

ステップ2:OAuth フローを完了する

シークレット名で SYSTEM$START_OAUTH_FLOW を実行して認証 URL を取得し、次にブラウザーで URL を開き OAuth 同意プロセスを完了します：

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

ブラウザーで同意を完了したら、ブラウザーのリダイレクト URL にあるクエリ文字列を使用して、同じセッションで SYSTEM$FINISH_OAUTH_FLOW を実行します。

SELECT SYSTEM$FINISH_OAUTH_FLOW('query_string_from_redirect');

ステップ3:構成を構成済みに設定する

OAuth フローが完了した後、構成値を configured に設定します。

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

注釈

構成値は configured にのみ設定できます。それ以外の値は受け入れられません。この値を設定すると、アプリに対して OAuth フローが完了したことを通知します。実際のトークンはシークレットに保存されます。構成値は構成コールバックのみをトリガーします。

Snowflake Native App Framework は自動的にシークレットにトークンが格納されていることを確認し、 before_configuration_change および after_configuration_change コールバックをトリガーします。

後で構成を設定解除するには、次を使用します。

ALTER APPLICATION example_app UNSET CONFIGURATION oauth_config;

これは before_configuration_change および after_configuration_change コールバックもトリガーします。

警告

構成の設定を解除しても、シークレットに格納されている OAuth トークンは無効または取り消されません。アプリがトークンを使用しないようにするには、対応するセキュリティ統合アプリ仕様を拒否します。プロバイダーレベルでトークンを完全に取り消すには、サードパーティプロバイダーのトークン失効プロセスを使用します。詳細については、 Approve app specifications をご参照ください。

トークンの有効期限と再認証¶

Snowflakeは、シークレットに保存されている更新トークンを使用して、現在のアクセストークンの有効期限が切れたときに新しいアクセストークンを取得します。更新トークン自体の有効期限が切れているか、サードパーティのプロバイダーによって取り消された場合、アプリからの外部アクセスの呼び出しに失敗し、コンシューマーは再認証する必要があります。

プロバイダーは、 Snowsight および Python Permission SDK または SQL でコンシューマーに再認証を促すことができます。

コンシューマーをアプリページの Configurations タブに誘導します。Authentication で、 OAuth 構成の Reauthenticate をクリックしてトークンを更新します。

アプリにStreamlitフロントエンドがある場合は、 request_application_configuration_value（）を呼び出してStreamlitアプリの構成ダイアログをオーバーレイし、コンシューマーに再認証を求める。

from snowflake.permissions import request_application_configuration_value

request_application_configuration_value(config_names=['oauth_config'])

コンシューマーは、同じシークレットに対して SYSTEM$START_OAUTH_FLOW および SYSTEM$FINISH_OAUTH_FLOW を再実行することでトークンを更新できます。before_configuration_change および after_configuration_change コールバックを再度トリガーするには、コンシューマーは構成値を再度設定する必要があります。

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