Microsoft TeamsおよびMicrosoft 365 Copilot対応のCortex Agents¶

OAuth リソースプリンシパルへの同意の付与¶

Cortex Agents Bot OAuth リソースアプリケーションのサービスプリンシパルに同意を付与するには、以下を実行します。

1. ブラウザーで、https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=5a840489-78db-4a42-8772-47be9d833efe にナビゲートします。この場合、tenant-id は組織のMicrosoftテナント ID です。

   まだサインインしていない場合は、サインインするよう求められます。

   Permission requested ダイアログが表示され、アプリケーションが必要とする権限が表示されます。

2. Accept を選択し、リクエストされた権限を付与します。

OAuth クライアントプリンシパルへの同意の付与¶

このプロセスは、2つのダイアログを表示します。どちらも OAuth リソースプリンシパルのものと似ていますが、リクエストされる権限は異なります。

Cortex Agents Bot Snowflake OAuth クライアントアプリケーションのサービスプリンシパルに同意を付与するには、以下を実行します。

1. ブラウザーで、https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=bfdfa2a2-bce5-4aee-ad3d-41ef70eb5086 にナビゲートします。この場合、tenant-id は組織のMicrosoftテナント ID です。

   Permissions requested (1 of 2) ダイアログが表示され、アプリケーションが必要とする権限のセットが 1 つ表示されます。

2. Accept を選択して、リクエストされた権限を付与します。

   2 つ目の権限ダイアログが表示されます（Permissions requested (2 of 2)）。

3. Accept を選択して、リクエストされた権限を付与します。

{
  "error": {
    "code": "ServiceError",
    "message": "Missing required query string parameter: code. Url = https://unitedstates.token.botframework.com/.auth/web/redirect?admin_consent=True&tenant=<TENANT-ID>"
  }
}

権限の付与の確認¶

両方のアプリケーションに同意を付与した後、Microsoft Entra ID ポータルの Enterprise applications セクションを確認すると、権限が正常に付与されたことを確認できます。

1. 必要に応じて、Microsoft Entra管理者センター にログインします。

2. 検索ボックスに「enterprise applications」と入力し、検索結果の Enterprise applications を選択してエンタープライズアプリケーションに移動します。

3. All applications リストに、同意を付与したばかりの2つのアプリケーション（Snowflake Cortex Agents Bot OAuth リソースとSnowflake Cortex Agents Bot OAuth クライアント）があります。これを簡単に行うには、「Snowflake Cortex Agent」を検索します。

   両方のアプリケーションがリストに表示されれば、権限は正しく付与されています。アプリケーションの1つまたは両方が見つからない場合は、再度同意を付与してみてください。

Entra ID を外部 OAuth プロバイダーとして有効化する¶

Snowflakeセキュリティ統合オブジェクトは、外部 OAuth プロバイダー（この場合はMicrosoft Entra ID）との統合を表しています。この統合により、SnowflakeはMicrosoft TeamsまたはCopilotにログインしているユーザーを認証できるようになります。

次の SQL ステートメントは、統合を作成するための注釈付きのテンプレートです。このコマンドは、ACCOUNTADMIN 権限を持つロールによって実行する必要があります。tenant-id プレースホルダーをMicrosoft Tenant ID に置き換えます。

CREATE OR REPLACE SECURITY INTEGRATION entra_id_cortex_agents_integration
    TYPE = EXTERNAL_OAUTH
    ENABLED = TRUE
    EXTERNAL_OAUTH_TYPE = AZURE
    EXTERNAL_OAUTH_ISSUER = 'https://login.microsoftonline.com/<tenant-id>/v2.0'
    EXTERNAL_OAUTH_JWS_KEYS_URL = 'https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys'
    EXTERNAL_OAUTH_AUDIENCE_LIST = ('5a840489-78db-4a42-8772-47be9d833efe')
    EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = ('email', 'upn')
    EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'email_address'
    EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE'

このコマンドで使用可能なパラメーターの完全なリファレンスについては、CREATE SECURITY INTEGRATION （外部 OAuth） をご参照ください。

また、 EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM および EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE パラメーターはEntra ID IDをSnowflake IDにリンクさせます。認証が成功するようにするには、JWT で指定されたクレームの値がSnowflakeのユーザーオブジェクトで指定された属性の値と完全に一致する必要があります。Snowflakeが推奨する2つの主な構成は次のとおりです。

• ユーザープリンシパル名によるマッピング（UPN）：EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM パラメーターを 'upn' に設定し、EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE パラメーターを 'LOGIN_NAME' に設定します。

• メールアドレスによるマッピング：EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM パラメーターを 'email' に設定し、EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE パラメーターを 'EMAIL_ADDRESS' に設定します。

上記のステートメント例では、メールアドレスのマッピング構成を使用していますが、EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM パラメーターで UPN も指定しています。これにより、EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE を変更するだけでマッピングメソッドを変更できます。

ステートメント例は、ユーザーの既定のロールが使用されるように EXTERNAL_OAUTH_ANY_ROLE_MODE も有効にしています。

OAuth スコープの詳細については、スコープ をご参照ください。

ユーザープロビジョニング要件¶

前述のマッピング構成を使用して認証を成功させるには、確実に以下の要件が満たされているようにします。

• Entra ID ユーザーとSnowflake ユーザーとの間に厳密な1対1のマッピングが存在すること。統合を使用するすべてのEntra ID ユーザーに対し、Snowflakeユーザーを指定または作成します。

• 各Entra ID ユーザーを正確に1つのSnowflakeユーザーにマッピングすること。メールマッピングの場合、Entra ID プライマリメールはSnowflakeユーザーの EMAIL_ADDRESS と正確に一致する必要があります。UPN マッピングの場合、Entra ID UPN はSnowflakeユーザーの LOGIN_NAME と正確に一致する必要があります。

手動の管理作業を削減するために、オプションで、Entra ID からSnowflakeへの自動ユーザープロビジョニングとデプロビジョニングを構成できます。`自動プロビジョニングの構成 <https://learn.microsoft.com/en-us/entra/identity/saas-apps/snowflake-provisioning-tutorial>`__をご参照ください。

Cortex Agentを作成して構成する¶

セキュリティ統合を作成した後、TeamsまたはMicrosoft 365 Copilot統合が使用するSnowflakeアカウントに1つ以上の:doc:Cortex Agent オブジェクト </user-guide/snowflake-cortex/cortex-agents-rest-api> があることを確認します。

使用したいエージェントがすでに機能している場合は、このステップにこれ以上のアクションは必要ありません。

新しいエージェントを作成するには、次の:ref:`指示 <label_snowflake_agents_create>`に従います。

Teamsストアからアプリをインストールする¶

すべてのユーザーは、Microsoft TeamsストアからCortex Agentアプリをインストールする必要があります。アプリをインストールするには、Teamsアプリストアで「Snowflake Cortex Agents」を検索し、Add をクリックします。

SnowflakeアカウントをTeamsアプリに接続する¶

TeamsでCortex Agentアプリを操作する最初のユーザーは、Snowflakeアカウントをアプリに接続するよう促されます。このステップを成功させるために、このユーザーはSnowflakeで ACCOUNTADMIN または SECURITYADMINロールを持っている必要があります。

要約すると、Snowflakeの全ユーザーの既定のロールは、Cortex Agentsトピックの アクセス制御要件セクション で説明されているように、エージェントのオブジェクトにアクセスするために必要な権限を持っている必要があります。

セキュリティ統合は、デフォルトで主要なSnowflake管理者ロールをブロックします。したがって、Teams Botを設定するユーザーに既定のロールとして ACCOUNTADMIN などの管理者ロールを使用することはできません。この制限の詳細については、CREATE SECURITY INTEGRATION トピックの BLOCKED_ROLES_LIST をご参照ください。

Snowflakeでは、必要な権限を持つ専用の非管理者ロールを作成し、セットアップユーザーのデフォルトとして設定することを推奨します。もしくは以下のように SECONDARY ROLES メカニズムを使用して、ユーザーが持つプライマリの既定のロールを変更することなく、追加の権限を付与します。

GRANT ROLE <integration_specific_role> TO USER <user_name>;
ALTER USER <user_name> SET DEFAULT_SECONDARY_ROLES = ('ALL');

Teams Botを設定するには、以下の手順に従います。

1. プロセスを開始するには、 :ui:`I'm the Snowflake administrator`をクリックします。これは、管理者がTeams用にSnowflakeを構成する必要があることを知らせる通知の下にあります。

2. 示されているSnowflakeアカウント URL を提供し、Connect Snowflake account を選択します。

   アカウント URL を見つけるには、Snowsightにログインし、ページの左下隅にあるアカウントセレクターをクリックします。URL のホスト名部分はメニューの上部に your-organization-your-account 形式で表示されます。完全な URL は your-organization-your-account.snowflakecomputing.com です。

   設定ウィザードは URL がAzure US 東部2リージョンの有効なSnowflakeインスタンスにつながっていることを検証し、ユーザーがそのインスタンスへのアクセスを持ち、必要な管理者権限を持っていることを確認します。

設定が最終検証に合格すると、TeamsアプリがSnowflakeアカウントに接続され、エージェントを使用できるようになります。

既定のロールの設定¶

アクセスの問題をトラブルシューティングするには、まずユーザーの既定のロール設定を確認します。この設定を確認するには、DESCRIBE USER コマンドを使用します。出力の DEFAULT_ROLE プロパティをチェックします。ユーザーの既定のロールが正しくない場合は、ALTER USER コマンドを使用して変更します。

ALTER USER <user_name> SET DEFAULT_ROLE = '<correct_role>';

ユーザーのプライマリ DEFAULT_ROLE の変更ができない場合は、Snowflakeのセカンダリロールメカニズムを使用します。ユーザーは、プライマリロールとアクティブなセカンダリロールの権限を組み合わせてアクションを実行できます。これにより、ユーザーのプライマリロールを変更することなく、統合固有の追加ロールをユーザーに付与できます。

Cortex Agent統合のセカンダリロールを追加するには、以下のように SQL コマンドを使用します。

GRANT ROLE <integration_specific_role> TO USER <user_name>;
ALTER USER <user_name> SET DEFAULT_SECONDARY_ROLES = ('ALL');

必要な権限¶

それにより統合を実行するロール（各ユーザーの既定のロールまたは許可されたセカンダリロール）に、アクセス制御の要件のセクション で説明されている付与があることを確認します。

無効な OAuth アクセストークン（エラーコード390303）¶

このエラーは、セキュリティ統合の1つ以上のプロパティ値が正しくなく、SnowflakeがEntra ID から受信したアクセストークンの検証を妨げていることを示している可能性があります。これを修正するには、セキュリティ統合の以下のフィールドをチェックします。特に、URLs のテナント ID が正しいか確認します。

• EXTERNAL_OAUTH_ISSUER: これは正しいEntra ID 発行者 URL に設定する必要があります。形式は https://login.microsoftonline.com/tenant-id/v2.0 で、tenant-id は組織のMicrosoftテナント ID です。

• EXTERNAL_OAUTH_JWS_KEYS_URL: これは正しい JWS キー URL に設定する必要があります。形式は https://login.microsoftonline.com/tenant-id/discovery/v2.0/keys で、tenant-id は組織のMicrosoftテナント ID です。

• EXTERNAL_OAUTH_AUDIENCE_LIST： これには、Cortex Agents Bot OAuth リソースの正しいオーディエンスが含まれている必要があります。これはアプリケーション ID 5a840489-78db-4a42-8772-47be9d833efe です。

ALTER SECURITYINTEGRATION コマンドを使用して誤った値を更新します。

ユーザー名またはパスワードが正しくありません（エラーコード390304）¶

このエラーメッセージは、Entra ID によって送信されたユーザー識別子とSnowflakeの対応するユーザーの記録が一致していないことを示しています。この原因は通常、Entra ID ユーザーIDがSnowflakeユーザーに正確にマッピングされていないことです。これは、Snowflakeユーザーが存在しない場合や、マップされた UPN またはメールアドレスが正しくない場合、またはマッピングが複数のSnowflakeユーザーに解決される場合（例：マッピングがメールアドレスを使用して実行され、複数のユーザーが同じアドレスを共有している場合）に起こることがあります。

エラーメッセージには、ユーザーがログインしようとしている UPN とメールアドレスが含まれます。この情報を使用し、DESCRIBE USER コマンドを使用して影響を受けるユーザーの設定を確認します。ユーザーの NAME または EMAIL プロパティが、Entra ID の対応するユーザーの同じプロパティ値と一致していることを確認します。メールアドレスマッピングを使用する場合、統合を使用するSnowflakeアカウントの各ユーザーは、一意のメールアドレスを持っている必要があります。

ロールがアクセストークンにリストされていないか、除外されました（エラーコード390317）¶

このエラーは、OAuth アクセストークンの情報に基づいて、Snowflakeがユーザーにロールを割り当てることができない場合に発生します。アクセストークンは session:role-any スコープで構成され、ユーザーはSnowflakeで割り当てられたロールを引き受けることができます。ただし、この動作を許可するようにセキュリティ統合を明示的に構成する必要があります。

DESCRIBE SECURITY INTEGRATION コマンドを使用して、EXTERNAL_OAUTH_ANY_ROLE_MODE プロパティの値を確認し、ENABLE または ENABLE_FOR_LOGIN に変更します。

DESCRIBE SECURITY INTEGRATION entra_id_cortex_agents_integration;

ALTER SECURITY INTEGRATION entra_id_cortex_agents_integration
    SET EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE';

接続文字列で指定されたロールは、このユーザーに付与されていません（エラーコード390186）¶

このエラーは、Snowflakeセキュリティ統合が、ユーザーの既定のロールにセキュリティ統合の使用を許可していない場合に発生します。

この問題を解決するには、DESCRIBE SECURITY INTEGRATION の出力にある次のプロパティを確認します。

• EXTERNAL_OAUTH_ALLOWED_ROLES_LIST:パラメーターが有効になっている場合は、そのパラメーターにユーザーの既定のロールが含まれていることを確認します。

• EXTERNAL_OAUTH_BLOCKED_ROLES_LIST:パラメーターが有効になっている場合は、そのパラメーターにユーザーの既定のロールが含まれていないことを確認します。