API キー認証

API キー認証は、API を使用してメッセージ拡張アプリへのアクセスを認証するために使用される方法です。 これには、ユーザーまたは要求を開始したアプリの ID を確認するために、各 API 要求で渡される一意の API キーの使用が含まれます。 API キーはMicrosoft Teamsに登録する必要があり、ユーザーがメッセージ拡張機能と対話するときに、Teams はシークレットを使用して API を認証します。

次の API キー登録プロパティは、キーをセキュリティで保護し、アプリケーションに制限されていることを確認するのに役立ちます。

• ベース URL: Teams は、このフィールドの値で始まる URL エンドポイントにシークレットを送信します。
• ターゲット テナント: Microsoft 365 テナントまたは任意のテナントへの API アクセスを制限します。
• アプリ ID: 特定のアプリまたは任意のアプリへのキー アクセスを制限します。
• API キー: アプリへのアクセスを認証します。

開発者ポータル for Teams を使用して API キーを登録 し、API キー登録 ID を生成できます。 apiSecretRegistrationId プロパティを使用して、apiSecretServiceAuthConfiguration オブジェクトを使用してアプリ マニフェストを更新します。 このプロパティには、Teams 用開発者ポータルを通じて API キーを送信したときに返される API キー登録 ID が含まれている必要があります。

注意

TEAMS アプリ マニフェストから取得できるため、API キー登録 ID をセキュリティで保護する必要があります。 API キーのセキュリティ保護の詳細については、 ベスト プラクティスに関するページを参照してください。

API 要求が開始されると、システムは暗号化されたデータベースから API キーを取得し、ベアラー トークン スキームを使用して承認ヘッダーに含めます。 API キーを持つ承認ヘッダーは、アプリ マニフェストで定義されているエンドポイントに送信されます。

次の例は、ベアラー トークン スキームを使用した承認ヘッダーを持つペイロードを示しています。

GET https://example.com/search?myQuery=test
Accept-Language: en-US
Authorization: Bearer <MY_API_KEY>

API キーを登録する

API キーを登録するには、次の手順に従います。

1. [ツール>API キーの登録] に移動します。

   

2. [ + 新しい API キー] を選択します。

3. [API キーの登録] ページで、[+ シークレットの追加] を選択します。 [ API キーの追加] ダイアログが表示されます。

4. キーの値を入力し、[保存] を選択 します。

   注意

   最大 2 つの API キーを維持できます。 1 つを置き換える必要がある場合は、更新プロセス中に Teams が他の構成済みキーを使用するため、サービスを中断することなく行うことができます。

   

5. [ API キー名] で、API キーのわかりやすい名前を追加します。 たとえば、Contoso メッセージ拡張機能の API キーなどです。

6. [ ベース URL] で、呼び出す必要があるすべての API エンドポイントの共通ベース URL を指定します。 この URL は https で始まり、完全修飾ドメイン名と必要に応じてパスを含める必要があります。 Teams は、このフィールドの値で始まる URL エンドポイントにキーを送信します。 たとえば、「 https://api.yelp.com 」のように入力します。

   ベース URL を使用すると、別のアプリが API キー登録 ID を不正に取得して独自のアプリに組み込んだ場合でも、キーは安全なままであり、ランダム なエンドポイントに漏洩しないようにします。 API キー構成に登録されている URL が、OpenAPI 仕様で定義されているターゲット エンドポイントのプレフィックスでない場合、呼び出しは削除されます。

   

7. [ ターゲット テナント] で、次のいずれかを選択します。

   • ホーム テナント: API キーは、登録されているテナント内でのみ機能します。
   • 任意のテナント: API キーは、任意のテナントで使用できます。

   

8. [ ターゲット Teams アプリ] で、次のいずれかを選択します。

   • 既存の Teams アプリ: [既存の Teams アプリ ] オプションは、API キー登録 ID を特定の Teams アプリにバインドします。
   • 任意の Teams アプリ: API キーは、任意の Teams アプリで使用できます。

   

   API キー登録 ID が生成されます。

   

9. Teams の開発者ポータルで、[ アプリ ] を選択し、API キーを追加するアプリを選択します。

10. [アプリの機能>Message 拡張機能] に移動します。

11. [ 認証] で [ API キー ] を選択し、API キー登録 ID を追加します。

    

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

API キー登録 ID は、アプリ マニフェストの apiSecretRegistrationId プロパティの値として更新されます。 アプリ マニフェストの API キー登録 ID は、開発者ポータル for Teams で確認できます。

アプリ マニフェストの更新

apiSecretRegistrationId プロパティを持つ apiSecretServiceAuthConfiguration オブジェクトを追加します。このオブジェクトには、開発者ポータル for Teams を介して API キーを送信するときに参照 ID が含まれます。 詳細については、「composeExtensions.commands」を参照してください。

"composeExtensions": [
    {
      "composeExtensionType": "apiBased",
      "authorization": {
        "authType": "apiSecretServiceAuth",
        "apiSecretServiceAuthConfiguration": {
            "apiSecretRegistrationId": "9xxxxb0f-xxxx-40cc-xxxx-15xxxxxxxxx3"
        }
      },

ベスト プラクティス

• API キー:

  • API キーには、少なくとも 10 文字、最大 2048 文字が必要です。
  • API キーを更新した後、キーがシステム全体に反映されるまでに最大 1 時間かかります。

• ベース URL:

  • セキュリティで保護された通信を確保するには、ベース URL は https で始まる必要があります。
  • 完全なホスト名を含め、正確なドメインを指定する必要があります。
  • 省略可能なパスを追加して、API の特定のエントリ ポイントを定義できます。

  Teams は、指定したベース URL で始まるエンドポイントに API キーを送信するため、この構造は API キーのセキュリティに不可欠です。

• ターゲット テナント: Microsoft 365 テナント内でアプリを開発するときに、最初に組織 (LOB アプリ) またはカスタム アプリ用に構築されたカスタム アプリとしてテストします。 この段階では、キーがテナントに排他的なままになるように、API キーをターゲット テナントとしてホーム テナント に登録する必要があります。

  テストが完了し、Teams ストアのパートナー センターにアプリ マニフェストを送信する準備ができたら、ターゲット テナントの設定を [任意のテナント] に切り替える必要があります。 この変更により、Teams ストアでアプリを使用できるようになったら、API キー登録 ID をさまざまなテナントで使用できます。

• Teams アプリ ID: Microsoft 365 テナント内でアプリを開発し、組織 (LOB) またはカスタム アプリ用に構築されたカスタム アプリとしてテストを開始するときは、Teams アプリ ID を Any Teams アプリとして API キー登録 ID に設定する必要があります。 この構成を使用すると、カスタム アプリとしてアップロードされた Teams アプリと、組織 (LOB アプリ) 用に構築されたカスタム アプリでキーを使用して、アップロード後に ID を生成できます。 この段階では、アプリの ID は取得できません。

  キーのセキュリティは、引き続き ホーム テナント と ベース URL を通じて維持されます。 アプリを世界にリリースする準備ができたら、[Teams アプリ ID] 設定を [ 既存の Teams アプリ ] に変更し、Teams アプリ ID を入力する必要があります。 最後に、アプリ マニフェストをパートナー センターに送信して、Teams ストアに含めます。 これで、API キーの登録が特定の Teams アプリに関連付けられ、他のユーザーと一緒に使用することはできません。

  組織 (LOB) またはカスタム アプリ用に構築されたカスタム アプリの場合、アクセスが困難な内部アプリ ID があります。 このシナリオでは、アプリが使用されているテナントに構成を制限します。 他のアプリの場合は、API キーの登録を Teams ストアに発行した後、発行済みのアプリ ID にリンクします。

関連項目

• API ベースのメッセージ拡張機能を作成する
• Microsoft Entra IDで API ベースのメッセージ拡張機能を構成する
• Microsoft Teams でユーザーを認証する