API キー認証を構成する

ヒント

推奨事項: サポートされているプロコード宣言型エージェントとプラグイン シナリオ用の Work IQ 開発ツール から始めます。 WIQD クイックスタートを参照してください。 Toolkit ベースの手順は、それらを必要とする既存のプロジェクトおよびワークフローで引き続き使用できます。 ツールを選択する前に 、機能とターゲット エクスペリエンスのサポート を確認します。WIQD はカスタム エンジン エージェントを対象としません。

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

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

注

宣言型エージェント アクションの場合、API キー認証は MCP プラグインではなく、OpenAPI ドキュメントからビルドされた API プラグインに適用されます。 エージェントの MCP プラグインの場合は、OAuth 2.0 (動的クライアント登録を含む) または Microsoft Entra SSO を使用します。 パッケージ レベルのリモート MCP 接続では、別の構成が使用されます。「 アプリケーション マニフェストの認証」を参照してください。

API キー認証を 2 つの手順で構成します。API キーを OpenAPI ドキュメントに追加し、API キー認証構成を作成します。

手順 1: 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

手順 2: API キー認証構成を作成する

API キー認証は、認証構成 (auth config) に依存します。これは、プラグインが API を呼び出すときに Microsoft 365 Copilot が API キーを送信するために使用する Microsoft Enterprise トークン ストアに保存されているレコードです。 サポートされているプロコード プロジェクト用の WIQD から開始します。 Toolkit および Microsoft Teams 開発者ポータルの手順は、引き続き代替として使用できます。 宣言型エージェントの開発者スキルは、MCP プラグインをビルドするため、API キー認証をサポートしていません。

既存の API プラグイン マニフェストの場合は、--plugin-manifest、--auth-name、--auth-type api-key で wiqd agent add auth を使用します。 --api-key-in を header または query に設定し、OpenAPI セキュリティ スキームの名前に--api-key-nameします。 API が代わりにそのキーをベアラー トークンとして受け入れる場合は、[ --auth-type bearer-token] を選択します。

OpenAPI ドキュメントからアクションを追加する場合、 wiqd agent add action は API キーまたはベアラー資格情報の --api-key を受け入れます。 値を省略すると、コマンドは環境プレースホルダーを文書化します。 選択したコマンドの資格情報処理に従って、プロジェクトのプロビジョニング ワークフローを完了します。 これらの API キー オプションは、エージェントの MCP プラグインの API キー サポートを確立しません。

Microsoft 365 Agents Toolkit を使用する

Microsoft 365 Agents Toolkit の既存の OpenAPI ドキュメントから API プラグインを作成すると、ツールキットによって API キーが登録され、認証構成が作成され、プラグイン マニフェストが更新されます。 securitySchemes プロパティは、OpenAPI ドキュメントで定義する必要があります。

Teams 開発者ポータルを使用する

エージェント ツールキットを使用している場合、Teams 開発者ポータルへの登録はオプションです。 認証設定を手動で作成したり、Agents Toolkit がすでに作成した認証設定を管理したりするために使用します。

  1. Teams 開発者ポータルを開きます。 [ ツール] ->API キーの登録 を選択します。

  2. 既存の登録がない場合は、[ API キーの作成] を選択します。 既存の登録がある場合は、[ 新しい API キー] を選択します。

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

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

    • API キー名: 登録のフレンドリ名。
    • ベース URL: API のベース URL。 この値は、OpenAPI ドキュメントの servers 配列 のエントリに対応している必要があります。
    • ターゲット テナント: API アクセスをホーム テナントに制限するか、任意のテナントに許可します。
    • ターゲット Teams アプリ: 最終的なアプリ ID がわからない場合は、[ 任意の Teams アプリ ] を選択します。 アプリを公開した後、この登録を公開済みのアプリ ID にバインドします。
  5. [保存] を選択します。

  6. 登録を完了すると、 認証構成 ID (現在 Teams 開発者ポータルでラベル付けされた API キー登録 ID ) が生成されます。

プラグイン マニフェストに認証構成 ID を追加する

Teams 開発者ポータルで認証構成を手動で作成する場合は、ランタイム認証オブジェクトの type プロパティを ApiKeyPluginVault に設定し、reference_idを認証構成 ID に設定します。 エージェント ツールキットはこれを行います。

"auth": {
  "type": "ApiKeyPluginVault",
  "reference_id": "auth config ID"
},