エージェントで API プラグインの認証を構成する

[アーティクル]
01/10/2025

Microsoft 365 Copilotで実行されているエージェントで API プラグインの認証を構成するには、サポートされている 4 つの認証スキームのいずれかを使用してバックエンド API にシームレスに接続します。

OAuth 2.0 認証コードフロー
シングルサインオン (SSO) 認証のMicrosoft Entra ID
API キー認証
認証なし (匿名)

OAuth 2.0 認証コードフロー

プラグインは、オプションの Proof Key for Code Exchange (PKCE) サポートを使用して、OAuth 2.0 承認コードフローを介して取得されたベアラートークンを使用して API にアクセスできます。

開始する前に、OAuth 2.0 プロバイダーに登録して、クライアント ID とシークレットを取得する必要があります。 OAuth プロバイダーで、アプリの登録中に許可されたリダイレクト URI を指定する必要がある場合は、必ず一覧に https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect を含めます。

重要

OAuth 2.0 の API プラグインのサポートには、次の制限があります。

API プラグインは、OAuth 2.0 の承認コードフローのみをサポートします。
トークンエンドポイントから HTTP 状態コードを返す OAuth 2.0 サーバーはサポートされていません。

このスキームは、OpenAPI ドキュメントの securitySchemes プロパティで定義できます。詳細については、「 OAuth 2.0」を参照してください。

securitySchemes:
  OAuth2:
    type: oauth2
    flows:
      authorizationCode:
        authorizationUrl: <authorization_url>
        tokenUrl: <token_url>
        refreshUrl: <refresh_url>
        scopes:
          scope: description

OAuth 2.0 認証を有効にするには、Teams 開発者ポータルで OAuth クライアントを登録する必要があります。 Visual Studio Code で、または Teams 開発者ポータルで手動で登録することで、OAuth クライアントを Teams Toolkit に登録できます。

Teams Toolkit に OAuth クライアントを登録する

Teams Toolkit は、既存の OpenAPI ドキュメントから API プラグインを使用してエージェントを作成するときに、OAuth クライアントを登録し、アプリパッケージを更新します。 OpenAPI ドキュメントで securitySchemes プロパティを定義する必要があります。

OAuth プロバイダーが PKCE をサポートしている場合は、エージェントをプロビジョニングする前に、エージェントプロジェクトのteamsapp.ymlで次のコード行のコメントを解除します。

# isPKCEEnabled: true

Teams 開発者ポータルで OAuth クライアントを登録する

Teams 開発者ポータルを開きます。 [ ツール] ->[OAuth クライアントの登録] を選択します。
既存の登録がない場合は、[クライアントの登録] を選択します。既存の登録がある場合は、[ 新しい OAuth クライアントの登録] を選択します。
次のフィールドに入力します。
- 登録名: 登録のフレンドリ名。
- ベース URL: API のベース URL。この値は、OpenAPI ドキュメントの servers 配列内のエントリに対応している必要があります。
- クライアント ID: OAuth 2.0 プロバイダーによって発行されたクライアント ID またはアプリケーション ID。
- クライアントシークレット: OAuth 2.0 プロバイダーによって発行されたクライアントシークレット。
- 承認エンドポイント: アプリが承認コードを要求するために使用する OAuth 2.0 プロバイダーからの URL
- トークンエンドポイント: OAuth 2.0 プロバイダーからの URL。アプリがアクセストークンのコードを引き換えるために使用する URL
- 更新エンドポイント: アプリがアクセストークンの更新に使用する OAuth 2.0 プロバイダーからの URL
- スコープ: アクセスを許可する API によって定義されたアクセス許可スコープ。
- Code Exchange (PKCE) の Proof Key を有効にする: OAuth プロバイダーが PKCE をサポートしている場合は、この設定を有効にします。
[保存] を選択します。
登録を完了すると、 OAuth クライアント登録 ID が生成されます。

クライアント登録 ID をプラグインマニフェストに追加する

API プラグインに OAuth 2.0 認証を使用するには、ランタイム認証オブジェクトの type プロパティを OAuthPluginVault に設定し、reference_idを Teams 開発者ポータルのクライアント登録 ID に設定します。

"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "auth registration ID"
},

MICROSOFT ENTRA ID SSO 認証

Microsoft Entra ID SSO 認証を使用すると、シームレスなシングルサインオン (SSO) 統合が可能になり、ユーザーは既存のMicrosoft Entra ID資格情報で認証できます。この統合により、アクセス管理が簡素化され、追加の資格情報を必要とせずに API への安全な接続が確保されます。 API では、Microsoft Entra IDを使用してアクセスを制御する必要があります。

Teams 開発者ポータルで SSO クライアントを登録する

Teams 開発者ポータルを開きます。 [ツール] ->Microsoft Entra SSO クライアント ID 登録を選択します。
既存の登録がない場合は、[ クライアント ID の登録] を選択します。既存の登録がある場合は、[ 新しいクライアント登録] を選択します。
次のフィールドに入力します。
- 登録名: 登録のフレンドリ名。
- ベース URL: API のベース URL。この値は、OpenAPI ドキュメントの servers 配列内のエントリに対応している必要があります。
- 組織別の使用を制限する: API エンドポイントにアクセスするためにアプリにアクセスできる Microsoft 365 organizationを選択します。
- アプリ別の使用を制限する: 最終的なアプリ ID がわからない場合は、[ 任意の Teams アプリ ] を選択します。アプリを発行したら、この登録を発行済みのアプリ ID にバインドします。
- クライアント ID: Microsoft Entraに登録されているアプリのクライアント ID。
[保存] を選択します。
登録を完了すると、Microsoft Entra SSO 登録 ID とアプリケーション ID URI が生成されます。

Microsoft Entra アプリの登録を更新する

Microsoft Entra 管理センターを開きます。 Teams 開発者ポータルによって生成されたアプリケーション ID URI を使用して API をセキュリティで保護するMicrosoft Entra アプリの登録を更新します。アプリ登録にマップされている既存のアプリケーション ID URI がある場合は、マニフェストエディターを使用して 、identifierUris セクションに別の URI を追加できます。
```
"identifierUris": [
  "<<URI1>>"
  "<<URI2>>"
]
```
注:

Microsoft Entra 管理センターの UI では、複数の URI の追加はサポートされていません。 UI には、一覧の最初の URI のみが表示されます。複数の URI を追加しても、UI で異なる方法で表示される場合でも、既存の URI とスコープには影響しません。
[管理] の下の [認証] を選択します。 Web プラットフォームのリダイレクト URI にhttps://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirectを追加します。
[管理]の下の[API の公開]を選択します。 [ クライアントアプリケーションの追加] を選択し、Microsoft のエンタープライズトークンストアのクライアント ID を追加 ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b。

SSO 登録 ID をプラグインマニフェストに追加する

ランタイム認証オブジェクトの type プロパティを OAuthPluginVault に設定し、reference_idを Teams 開発者ポータルの Microsoft Entra SSO 登録 ID に設定します。

"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "SSO registration ID"
},

新しいトークン対象ユーザーを API に追加する

トークン対象ユーザーとして新しい識別子 URI を許可するように API を更新します。 API がクライアントアプリケーション ID を検証する場合は、許可されているクライアントアプリケーションとして Microsoft エンタープライズトークンストアのクライアント ID (ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b) が追加されていることを確認します。

ヒント

API で代理フローを使用して、ユーザーが同意を付与する必要がある別の Web API へのアクセスを取得する場合は、 401 Unauthorized エラーを返して、同意を付与するようにエージェントにサインインを求めます。

API キー認証

一部の API では、承認に API キーが使用されます。 API キーは、クライアントが認証とアクセスを取得するための API 要求に含まれる共有シークレットです。 API プラグインでは、次の 3 つの方法で API キーの送信がサポートされています。

Authorization ヘッダーのベアラートークンとして
カスタムヘッダーの値として
クエリパラメーターとして

OpenAPI ドキュメントに API キーを追加する

Microsoft 365 Copilotは、OpenAPI ドキュメントのsecuritySchemesエントリに基づいて API キーを送信する方法を決定します。

ベアラートークン

API がベアラートークンとして API キーを受け入れる場合は、OpenAPI ドキュメントでベアラー認証を有効にします。詳細については、「ベアラー認証」を参照してください。

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer

カスタムヘッダー

API がカスタムヘッダーの API キーを受け入れる場合は、 in プロパティを header に設定し、 name プロパティをヘッダー名に設定して、OpenAPI ドキュメントで API キー認証を有効にします。詳細については、「 API キー」を参照してください。

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-KEY

クエリパラメーター

API がクエリパラメーターで API キーを受け入れる場合は、 in プロパティを query に設定し、 name プロパティをクエリパラメーターの名前に設定して、OpenAPI ドキュメントで API キー認証を有効にします。詳細については、「 API キー」を参照してください。

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: query
    name: api_key

API キーを登録する

API キー認証を有効にするには、Teams 開発者ポータルで API キーを登録する必要があります。 API キーは、Visual Studio Code の Teams Toolkit に登録するか、Teams 開発者ポータルで手動で登録することで登録できます。

Teams Toolkit に API キーを登録する

Teams Toolkit は、既存の OpenAPI ドキュメントから API プラグインを使用してエージェントを作成するときに、API キーを登録し、アプリパッケージを更新します。 OpenAPI ドキュメントで securitySchemes プロパティを定義する必要があります。

注:

Teams Toolkit では、ベアラートークンとして API キーのみがサポートされ、カスタムヘッダーまたはクエリパラメーターを使用する OpenAPI ドキュメントに基づいて API プラグインを作成することはできません。回避策として、 securitySchemes プロパティと security プロパティを OpenAPI から一時的に削除してプラグインパッケージを生成し、プロビジョニングする前にプラグインプロジェクトの OpenAPI ドキュメントに追加し直すことができます。 API キーを手動で登録する必要があります。

Teams 開発者ポータルで API キーを登録する

Teams 開発者ポータルを開きます。 [ツール] ->API キーの登録を選択します
既存の登録がない場合は、[ API キーの作成] を選択します。既存の登録がある場合は、[ 新しい API キー] を選択します。
[ シークレットの追加] を選択し、API キーを入力します。
次のフィールドに入力します。
- API キー名: 登録のフレンドリ名。
- ベース URL: API のベース URL。この値は、OpenAPI ドキュメントの servers 配列内のエントリに対応している必要があります。
- ターゲットテナント: ホームテナントへの API アクセスを制限するかどうか。
- ターゲット Teams アプリ: 最終的 なアプリ ID がわからない場合は、[任意の Teams アプリ] を選択します。アプリを発行したら、この登録を発行済みのアプリ ID にバインドします。
[保存] を選択します。
登録を完了すると、 API キー登録 ID が生成されます。

API キー登録 ID をプラグインマニフェストに追加する

プラグインマニフェストファイルで、ランタイム認証オブジェクトの type プロパティを ApiKeyPluginVault に設定し、reference_idを Teams 開発者ポータルの API キー登録 ID に設定します。

"auth": {
  "type": "ApiKeyPluginVault",
  "reference_id": "app key registration ID"
},

認証なし (匿名)

認証を必要としない API、または認証がまだ実装されていない開発者環境の場合、プラグインは API に匿名でアクセスできます。この場合、ランタイム認証オブジェクトの type プロパティを None に設定します。

"auth": {
  "type": "None"
},

次の方法で共有

エージェントで API プラグインの認証を構成する

OAuth 2.0 認証コードフロー

Teams Toolkit に OAuth クライアントを登録する

Teams 開発者ポータルで OAuth クライアントを登録する

クライアント登録 ID をプラグインマニフェストに追加する

MICROSOFT ENTRA ID SSO 認証

Teams 開発者ポータルで SSO クライアントを登録する

Microsoft Entra アプリの登録を更新する

SSO 登録 ID をプラグインマニフェストに追加する

新しいトークン対象ユーザーを API に追加する

API キー認証

OpenAPI ドキュメントに API キーを追加する

ベアラートークン

カスタムヘッダー

クエリパラメーター

API キーを登録する

Teams Toolkit に API キーを登録する

Teams 開発者ポータルで API キーを登録する

API キー登録 ID をプラグインマニフェストに追加する

認証なし (匿名)

フィードバック

その他のリソース

次の方法で共有

エージェントで API プラグインの認証を構成する

OAuth 2.0 認証コード フロー

Teams Toolkit に OAuth クライアントを登録する

Teams 開発者ポータルで OAuth クライアントを登録する

クライアント登録 ID をプラグイン マニフェストに追加する

MICROSOFT ENTRA ID SSO 認証

Teams 開発者ポータルで SSO クライアントを登録する

Microsoft Entra アプリの登録を更新する

SSO 登録 ID をプラグイン マニフェストに追加する

新しいトークン対象ユーザーを API に追加する

API キー認証

OpenAPI ドキュメントに API キーを追加する

ベアラー トークン

カスタム ヘッダー

クエリ パラメーター

API キーを登録する

Teams Toolkit に API キーを登録する

Teams 開発者ポータルで API キーを登録する

API キー登録 ID をプラグイン マニフェストに追加する

認証なし (匿名)

フィードバック

その他のリソース

OAuth 2.0 認証コードフロー

クライアント登録 ID をプラグインマニフェストに追加する

SSO 登録 ID をプラグインマニフェストに追加する

ベアラートークン

カスタムヘッダー

クエリパラメーター

API キー登録 ID をプラグインマニフェストに追加する