Microsoft 365 Copilot用 API プラグインの認証スキーム

  • [アーティクル]

重要

API プラグインは現在、 宣言型エージェント内のアクションとしてのみサポートされています。 Microsoft 365 Copilotでは有効になっていません。 宣言型エージェント に API プラグイン を追加する例については、「プラグインの追加」を参照してください。

Microsoft 365 Copilot用の API プラグインでは、バックエンド API に接続するための 3 つの認証スキームがサポートされています。

  • OAuth 2.0 認証コード フロー
  • ベアラー認証による API キー
  • 認証なし (匿名)

OAuth 2.0 認証コード フロー

この認証スキームにより、プラグインは OAuth 2.0 承認コード フローによって取得されたベアラー トークンを使用して API にアクセスできます。 このスキームは、 securitySchemes プロパティの OpenAPI ドキュメントで表すことができます。 詳細については、「 OAuth 2.0 」を参照してください。

重要

API プラグインは、OAuth 2.0 の承認コード フローのみをサポートします。

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

プラグインでこの認証スキームを使用するには、 Teams 開発者ポータルで OAuth クライアントを登録する必要があります。

ヒント

OpenAPI ドキュメントに securitySchemes プロパティが含まれている場合、Teams Toolkit は OAuth クライアントを登録し、 既存の API からプラグインを生成するときにマニフェストを更新できます。

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

  1. ブラウザーを開き、 Teams アプリ開発者ポータルを参照します。 左側のナビゲーションで [ ツール ] を選択します。

  2. [ OAuth クライアントの登録] を選択します。 既存の登録がない場合は、[クライアントの 登録] を選択します。既存の登録がある場合は、[ 新しい OAuth クライアントの登録] を選択します。

  3. 次のフィールドに入力します。

    • 登録名: 登録のフレンドリ名
    • ベース URL: API のベース URL
    • クライアント ID: OAuth 2.0 サーバーによって発行されたクライアント ID またはアプリケーション ID
    • クライアント シークレット: OAuth 2.0 サーバーによって発行されたクライアント シークレット
    • 承認エンドポイント: アプリが承認コードを要求するために使用する OAuth 2.0 サーバーからの URL
    • トークン エンドポイント: アプリがアクセス トークンのコードを引き換えるために使用する OAuth 2.0 サーバーからの URL
    • 更新エンドポイント: アプリがアクセス トークンの更新に使用する OAuth 2.0 サーバーからの URL
    • スコープ: アクセスを許可する API によって定義されたアクセス許可スコープ。

  4. [保存] を選択します。

登録を完了すると、OAuth クライアント登録 ID が生成されます。

プラグイン マニフェストへの OAuth 2.0 認証の追加

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

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

ベアラー認証を使用した API キー

この認証スキームにより、プラグインは有効期間の長い API キーまたはトークンを使用して API にアクセスできます。 このトークンは、 Authorization ヘッダーの API 要求でベアラー トークンとして送信されます。 このスキームは、 securitySchemes プロパティの OpenAPI ドキュメントで表すことができます。 詳細については、「 ベアラー認証」 を参照してください。

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer

注:

API プラグインは、OpenAPI API キーのセキュリティ スキームをサポートしていません。 認証に API キーを使用する API では、ベアラー認証セキュリティ スキームを使用し、 Authorization ヘッダーで API キーを受け入れる必要があります。 カスタム ヘッダーを定義したり、クエリ パラメーターまたは Cookie としてキーを送信したりすることはできません。

プラグインでこの認証スキームを使用するには、 Teams 開発者ポータルで API キーを登録する必要があります。

ヒント

OpenAPI ドキュメントに securitySchemes プロパティが含まれている場合、Teams Toolkit は API キーを登録し、 既存の API からプラグインを生成するときにマニフェストを更新できます。

API キーを登録する

  1. ブラウザーを開き、 Teams アプリ開発者ポータルを参照します。 左側のナビゲーションで [ ツール ] を選択します。

  2. [ API キーの登録] を選択します。 既存の登録がない場合は、[クライアントの 登録] を選択します。既存の登録がある場合は、[ 新しい API キー] を選択します。

  3. [ シークレットの追加] を選択し、API キーを入力します。

  4. 次のフィールドに入力します。

    • API キー名: 登録のフレンドリ名
    • ベース URL: API のベース URL

  5. [保存] を選択します。

登録を完了すると、アプリ キー登録 ID が生成されます。

プラグイン マニフェストへの API キー認証の追加

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

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

認証なし (匿名)

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

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