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 スコープの詳細については、スコープ をご参照ください。

Cortex Agentの定義を準備する¶

セキュリティ統合を構成したら、Snowflake内でエージェントの環境と定義を準備する必要があります。そのために、必要なデータベースオブジェクトを作成し、単一の JSON オブジェクトでエージェントのロジックを定義します。定義は、エージェントの指示、そのツール（Cortex AnalystやCortex Searchなど）、およびそれらのツールのリソースを指定します。スキーマの定義は Cortex Agent API リクエスト本文スキーマ といくつかの追加事項に従います。以下は JSON オブジェクトの最上位構造です。

{
    "model": ...,
    "response_instruction": ...,
    "experimental": ...
    "tools": ...
    "tool_resources": ...
    "tool_choice": ...
    "starter_prompts": ...
}

エージェント定義をSnowflakeステージにアップロードし、エージェントを使用するすべてのエンドユーザーがアクセスできることを確認します。

検索結果と会話ガイダンスの2つのオプションフィールドを設定することで、ユーザーエクスペリエンスを向上させることができます。

• 引用検索では、検索ツールの tool_resources 定義で2つのオプションフィールドを指定することで、判読可能なタイトルとソースドキュメントへの直接リンクが提供されます。

  • title_column は、ドキュメントの判読可能なタイトルを含む列です。

  • id_column は、Cortex Searchがドキュメントへのリンクを構築するために使用する、ドキュメントの一意の識別子を含む列です。

• スタータープロンプトでは、エージェント定義の最上位にある starter_prompts フィールドで質問を作成する際にユーザーにガイドを提供します。

  {
      ....
      "starter_prompts": ["prompt #1", "prompt #2", ...],
      ...
  }
  

  Copy

エンドユーザーに必要な権限を付与する¶

エンドユーザーがTeamsのCortex Agentと正常にやり取りできるようにするには、デフォルトのSnowflakeロール（またはその他の指定されたロール）に、基礎となるオブジェクトすべてに対する権限が付与されている必要があります。

• Cortex Agentsトピックの アクセス制御要件セクション に一覧表示されているすべての付与

• エージェントの JSON 定義を含むステージへの READ アクセス

• エージェントに割り当てられたウェアハウスの USAGE

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

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

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

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

要約すると、Snowflakeの全ユーザーの既定のロールは、Cortex Agentsトピックの アクセス制御要件セクション で説明されているように、エージェントのオブジェクトにアクセスするために必要な権限と、エージェントの JSON 定義を含むステージへ READ アクセスとエージェントのウェアハウスでの USAGE を持っている必要があります。（ユーザーの既定のロールは、ユーザーのプロファイルの DEFAULT_ROLE 設定で指定されます。）

セキュリティ統合は、デフォルトで主要な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 = ('<integration_specific_role>');

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

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

2. 必要に応じてSnowflakeアカウント URL を提供します。

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

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

   注釈

   セキュリティ統合が「Microsoft IDプラットフォームアクセストークンv2.0」を使用していることを確認するように指示する警告が表示される場合があります。この警告は無視しても大丈夫です。Snowflakeセキュリティ統合トークン形式は互換性があります。

3. この検証に合格すると、次の設定の詳細を要求するフォームが表示されます。

   • アカウントエイリアス： Teamsインターフェースに表示されるこのSnowflakeアカウントのユーザーフレンドリーな名前（例：「Sales Analytics」）。

   • エージェント定義パス： Snowflakeステージのエージェントの JSON 定義ファイルへの完全修飾パス。形式は、:samp:`@{stage_name}/{path_to_definition_file}`（:code:`@my_cortex_agents/my_agent.json`など）。

   • デフォルトのウェアハウス： エージェントがクエリを実行するために使用するSnowflakeウェアハウスの名前。

   この情報を入力して、Finalize account configuration をクリックします。

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

既定のロールの設定¶

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

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

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

Cortex Agent統合のセカンダリロールを追加するには、以下のように SQL コマンドを使用します。ユーザーに既に割り当てられているセカンダリロールを削除しないようにするには、DESCRIBE USER の出力の DEFAULT_SECONDARY_ROLES プロパティを確認します。統合固有のロールを追加するときに、これらの既存のロールを含めます。

DESCRIBE USER <user_name>;  -- take note of DEFAULT_SECONDARY_ROLES
GRANT ROLE <integration_specific_role> TO USER <user_name>;
ALTER USER <user_name> SET DEFAULT_SECONDARY_ROLES = ('<pre_existing_role_1>', ....,
    '<integration_specific_role>');

必要な権限¶

ユーザーの既定のロール（またはデフォルトのセカンダリロール）は、以下で説明する権限を持っている必要があります。

• SNOWFLAKE. CORTEX_USER ロール経由のCortex AI 機能アクセス。デフォルトで、このロールは PUBLIC ロールに付与されるので、すべてのユーザーがCortex AI 機能にアクセスできます。組織が PUBLIC から SNOWFLAKE. CORTEX_USER を削除した場合、エージェントが実行されるロールにそれを明示的に付与する必要があります。

• エージェントがCortex Analystツールを使用する場合、そのロールは以下の権限も必要になります。

  • セマンティックモデルで参照されるすべてのデータベースとスキーマでの USAGE

  • セマンティックモデルで参照されるすべてのテーブルとビューでの SELECT

  • セマンティックモデルファイルを含むステージでの READ アクセス

• エージェントがCortex Search Serviceを使用する場合、ロールは使用される特定のサービスでの USAGE を持っている必要があります。

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

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

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

• EXTERNAL_OAUTH_JWS_KEYS_URL： これは正しいEntra JWS キー URL に設定する必要があります。形式はsamp: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 が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:パラメーターが有効になっている場合は、そのパラメーターにユーザーの既定のロールが含まれていないことを確認します。