API ベースのメッセージ拡張機能の SSO を有効にする

[アーティクル]
10/28/2024

API ベースのメッセージ拡張機能のシングルサインオン (SSO) 認証方法では、アプリユーザーの Teams ID を使用してアプリへのアクセスを提供します。 Teams にサインインしたユーザーは、Teams 環境内のアプリに再度サインインする必要はありません。 Microsoft Entra SSO を使用すると、アプリは、Microsoft Entraによってリソースに対して発行されたユーザートークンをサイレントモードで取得できます。アプリは、このトークンを認証し、ユーザーの同意なしにユーザープロファイル情報を取得できます。

前提条件

開始する前に、次のことを確認してください。

アクティブなサブスクリプションを持つ Azure アカウント。
Microsoft Entra IDと Teams アプリ開発に関する基本的な知識。

次の図は、Teams アプリユーザーが API ベースのメッセージ拡張機能アプリにアクセスしようとしたときの SSO のしくみを示しています。

ユーザーは Teams 内で API ベースのメッセージ拡張アプリを呼び出し、認証を必要とするコマンドを呼び出します。
アプリは、アプリ ID と必要なスコープ (access_as_user) を使用して、Teams バックエンドサービスに要求を送信します。
Teams バックエンドサービスは、ユーザーがアプリとスコープに同意したかどうかを確認します。そうでない場合は、同意画面がユーザーに表示されます。
ユーザーが同意した場合、Microsoft Entraはユーザーとアプリのアクセストークンを生成し、要求の承認ヘッダーでアプリに送信します。
アプリはトークンを検証し、トークンからユーザー情報 (名前、電子メール、オブジェクト ID など) を抽出します。
認証が成功すると、ユーザーには API ベースのメッセージ拡張機能へのアクセス権が付与されます。

API ベースのメッセージ拡張機能に対して SSO 認証を有効にするには、次の手順に従います。

Microsoft Entra IDで新しいアプリを登録します。
アクセストークンのスコープを構成します。
トークンを認証します。
アプリマニフェストを更新します。

Microsoft Entra IDで新しいアプリを登録する

Web ブラウザーで Azure portal を開きます。
[アプリの登録] アイコンを選択します。

[アプリの登録] ページが表示されます。
[+ 新しい登録] アイコンを選択します。

[アプリケーション登録] ページが表示されます。
アプリユーザーに表示するアプリの名前を入力します。必要に応じて、後の段階で名前を変更できます。

アプリにアクセスできるユーザーアカウントの種類を選択します。組織のディレクトリ内の単一またはマルチテナントオプションから選択することも、個人の Microsoft アカウントにのみアクセスを制限することもできます。

サポートされているアカウントの種類のオプション

オプション	これを以下に選択します...
この組織のディレクトリ内のアカウントのみ (Microsoft のみ - シングルテナント)	テナント内のユーザー (またはゲスト) のみが使用するアプリケーションをビルドします。組織 (LOB アプリ) 用に構築されたカスタムアプリと呼ばれることがよくあります。このアプリは、Microsoft ID プラットフォームのシングルテナントアプリケーションです。
任意の組織ディレクトリ内のアカウント (任意のMicrosoft Entra ID テナント - マルチテナント)	任意のMicrosoft Entraテナントのユーザーがアプリケーションを使用できるようにします。このオプションは、たとえば、SaaS アプリケーションを構築していて、複数の組織で使用できるようにする場合に適しています。この種類のアプリは、Microsoft ID プラットフォームのマルチテナントアプリケーションと呼ばれます。
任意の組織ディレクトリ内のアカウント (任意のMicrosoft Entra ID テナント - マルチテナント) と個人用 Microsoft アカウント (Skype、Xbox など)	最も幅広い顧客のセットをターゲットにします。このオプションを選択すると、個人用 Microsoft アカウントを持つアプリユーザーをサポートできるマルチテナントアプリケーションを登録します。
個人用 Microsoft アカウントのみ	個人の Microsoft アカウントを持つユーザー専用のアプリケーションをビルドします。

注:

API ベースのメッセージ拡張アプリの SSO を有効にするために 、「リダイレクト URI」 と入力する必要はありません。

[登録] を選択します。アプリが作成されたことを示すメッセージがブラウザーに表示されます。

アプリ ID やその他のアプリの詳細を含むページが表示されます。
アプリケーション (クライアント) ID からアプリ ID をメモして保存し、アプリマニフェストを後で更新します。

アプリはMicrosoft Entra IDに登録されています。これで、API ベースのメッセージ拡張アプリのアプリ ID が取得されました。

アクセストークンのスコープを構成する

新しいアプリの登録を作成したら、Teams クライアントにアクセストークンを送信するためのスコープ (アクセス許可) オプションを構成し、SSO を有効にするための信頼されたクライアントアプリケーションを承認します。

スコープを構成し、信頼されたクライアントアプリケーションを承認するには、次の操作を行う必要があります。

[アプリ ID URI の追加]: アプリのスコープ (アクセス許可) オプションを構成します。 Web API を公開し、アプリ ID URI を構成します。
API スコープの構成: API のスコープと、スコープに同意できるユーザーを定義します。管理者のみが、より高い特権を持つアクセス許可に対する同意を提供できます。
承認されたクライアントアプリケーションを構成する: 事前認証するアプリケーションの承認されたクライアント ID を作成します。これにより、アプリユーザーは、追加の同意を必要とせずに、構成したアプリスコープ (アクセス許可) にアクセスできます。アプリユーザーが同意を拒否する機会がないため、信頼できるクライアントアプリケーションのみを事前認証します。

アプリ ID URI

左側のウィンドウで [管理]>[API の公開] を選択します。

[API の公開] ページが表示されます。
[ 追加] を選択して、 api://{AppID}の形式でアプリ ID URI を生成します。

アプリ ID URI を設定するためのセクションが表示されます。
ここで説明する形式で アプリケーション ID URI を 入力します。
- アプリケーション ID URI には、api://{AppID}形式のアプリ ID (GUID) が事前に入力されています。
- アプリ ID URI 形式は、 api://fully-qualified-domain-name.com/{AppID}である必要があります。
- fully-qualified-domain-name.com を api:// と {AppID} (つまり GUID) の間に挿入します。たとえば、api://example.com/{AppID} です。
重要
- スタンドアロンボットを構築する場合は、アプリ ID URI を api://botid-{YourBotId} として入力します。ここで、{YourBotId} はMicrosoft Entraアプリ ID です。
- ボット、メッセージ拡張機能、タブを使用してアプリをビルドする場合は、アプリ ID URI を api://fully-qualified-domain-name.com/botid-{YourClientId}として入力します。{YourClientId} はボットアプリ ID です。
- ボットなしでメッセージ拡張機能またはタブ機能を使用してアプリをビルドする場合は、アプリ ID URI を api://fully-qualified-domain-name.com/{YourClientId}として入力します。{YourClientId} は Microsoft Entra アプリ ID です。
- 複数の機能を持つアプリのアプリケーション ID URI: API ベースのメッセージ拡張機能を構築する場合は、api://fully-qualified-domain-name.com/{YourClientId}としてアプリ ID URI を入力します。{YourClientId} は Microsoft Entra アプリ ID です。
- ドメイン名の形式: ドメイン名には小文字のみを使用します。
[保存] を選択します。

アプリ ID URI が更新されたことを示すメッセージがブラウザーに表示されます。

アプリ ID URI がページに表示されます。
アプリマニフェストを後で更新するには、アプリ ID URI をメモして保存します。

API スコープを構成する

注:

API ベースのメッセージ拡張機能では、 access_as_user スコープのみがサポートされます。
API は、スコープが Azure portal に登録されているaccess_as_userに設定されたMicrosoft Entraアクセストークンを受け取ります。ただし、トークンは、Microsoft Graph などの他のダウンストリーム API を呼び出す権限がありません。

[この API で定義されたスコープ] セクションで [+ スコープの追加] を選択します。

[スコープの追加] ページが表示されます。
スコープを構成するための詳細を入力します。
1. スコープ名を入力します。このフィールドは必須です。
2. このスコープに同意できるユーザーを選択します。既定のオプションは [管理者のみ] です。
3. 管理同意表示名を入力します。このフィールドは必須です。
4. 管理者の同意の説明を入力します。このフィールドは必須です。
5. [ユーザーの同意表示名] を入力します。
6. ユーザー同意の説明を入力します。
7. 状態の [有効] オプションを選択します。
8. [スコープの追加] を選択します。
スコープが追加されたことを示すメッセージがブラウザーに表示されます。

定義した新しいスコープがページに表示されます。

承認されたクライアントアプリケーションを構成する

[API の公開 ] ページを [ 承認されたクライアントアプリケーション ] セクションに移動し、[ + クライアントアプリケーションの追加] を選択します。

[クライアントアプリケーションの追加] ページが表示されます。

アプリの Web アプリケーションに対して承認するアプリケーションに適した Microsoft 365 クライアント ID を入力します。

Azure portalのアプリにクライアントアプリケーションを追加するための [クライアント ID] オプションと [承認されたスコープ] オプションを示すスクリーンショット。クライアントアプリケーションを追加する

注:

Teams 用のモバイル、デスクトップ、および Web アプリ用の Microsoft 365 クライアント ID は、追加する必要がある実際の ID です。

次のいずれかのクライアント ID を選択します。

クライアント ID を使用する	承認する場合...
1fec8e78-bce4-4aaf-ab1b-5451cc387264	Teams モバイルアプリまたはデスクトップアプリ
5e3ce6c0-2b1f-4285-8d4b-75ee78787346	Teams Web アプリ

[ 承認されたスコープ ] でアプリ用に作成したアプリ ID URI を選択して、公開した Web API にスコープを追加します。
[アプリケーションの追加] を選択します。

承認されたクライアントアプリが追加されたことを示すメッセージがブラウザーに表示されます。

承認されたアプリのクライアント ID がページに表示されます。

注:

複数のクライアントアプリケーションを承認できます。承認された別のクライアントアプリケーションを構成するには、この手順の手順を繰り返します。

アプリのスコープ、アクセス許可、およびクライアントアプリケーションが正常に構成されました。アプリ ID URI をメモして保存してください。次に、アクセストークンのバージョンを構成します。

トークンの認証

メッセージ拡張機能は、認証中に API を呼び出すと、ユーザーのアクセストークンを使用して要求を受け取ります。メッセージ拡張機能は、送信 HTTP 要求の承認ヘッダーにトークンを追加します。ヘッダー形式は Authorization: Bearer <token_value>。たとえば、メッセージ拡張機能が認証を必要とするサービスに対して API 呼び出しを行う場合などです。この拡張機能は、次のように HTTP 要求を構築します。

GET /api/resource HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

API ベースのメッセージ拡張機能がトークンを含む要求ヘッダーを取得したら、次の手順を実行します。

認証: 対象ユーザー、スコープ、発行者、署名要求のトークンを確認して、トークンがアプリ用の場合はチェックします。その他の要求については、「 ID トークンの要求」を参照してください。

次の例は、ヘッダーと応答を含む JSON Web トークン (JWT) を示しています。

トークン V2
トークン V1

{
"typ": "JWT",
"rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.",
"alg": "RS256",
"kid": "q-23falevZhhD3hm9CQbkP5MQyU"
}.{
  "aud": "00000002-0000-0000-c000-000000000000",
  "iss": "https://login.microsoftonline.com/72f988bf-86f1-41af-91ab-2d7cd011db47/v2.0",
  "iat": 1712509315,
  "nbf": 1712509315,
  "exp": 1712513961,
  "aio": "Y2NgYEjJqF0stqv73u41a6ZmxPEvBgA=",
  "azp": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
  "azpacr": "0",
  "name": "John Doe",
  "oid": "00000000-0000-0000-0000-000000000000",
  "preferred_username": "john.doe@contoso.com",
  "rh": "I",
  "scp": "access_as_user",
  "sub": "e4uM7JgAEm08GBuasSltQjvPuMX1fR5TqxopJpqZJB8",
  "tid": "12345678-aaaa-bbbb-cccc-9876543210ab",
  "uti": "h7DMQwSPAEeiEe62JJUGAA",
  "ver": "2.0"
  }

{
"typ": "JWT",
"rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.",
"alg": "RS256",
"kid": "q-23falevZhhD3hm9CQbkP5MQyU"
}.{
  "aud": "api://00000002-0000-0000-c000-000000000000",
  "iss": "https://sts.windows.net/{tenantid}/",
  "iat": 1537231048,
  "nbf": 1537231048,
  "exp": 1537234948,
  "acr": "1",
  "aio": "AXQAi/8IAAAA",
  "amr": ["pwd"],
  "appid": "c44b4083-3bb0-49c1-b47d-974e53cbdf3c",
  "appidacr": "0",
  "ipaddr": "192.168.1.1",
  "name": "John Doe",
  "oid": "00000000-0000-0000-0000-000000000000",
  "scp": "access_as_user",
  "sub": "AAAAAAAAAAAAAAAAAAAAAIkzqFVrSaSaFHy782bbtaQ",
  "tid": "12345678-aaaa-bbbb-cccc-9876543210ab",
  "uti": "fqiBqXLPj0eQa82S-IYFAA",
  }

トークンを使用する: 名前、電子メール、オブジェクト ID などのユーザー情報をトークンから抽出し、トークンを使用してメッセージ拡張アプリの独自の API を呼び出します。アクセストークンに含まれる要求の詳細を含む要求リファレンスの詳細については、「アクセストークンの要求」を参照してください。

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

アプリマニフェストファイルで次のプロパティを更新します。

webApplicationInfo: webApplicationInfo プロパティを使用して、アプリの SSO を有効にして、アプリユーザーが API ベースのメッセージ拡張機能アプリにシームレスにアクセスできるようにします。 Microsoft Entra IDに登録したアプリ ID URI は、公開した API のスコープで構成されます。詳細については、「webApplicationInfo」を参照してください。
microsoftEntraConfiguration: アプリの SSO 認証を有効にします。 SSO をサポートし、複数の認証の必要性を減らすためにtrueするように supportsSingleSignOn プロパティを構成します。プロパティが false に設定されているか、空のままになっている場合、ユーザーはアプリを Teams にアップロードできず、アプリの検証に失敗します。

アプリマニフェストを構成するには:

API ベースのメッセージ拡張アプリを開きます。
アプリマニフェストフォルダーを開きます。
注:
- アプリマニフェストフォルダーは、アプリフォルダーのルートにある必要があります。詳細については、「 Microsoft Teams アプリパッケージを作成する」を参照してください。
- manifest.jsonを作成する方法の詳細については、アプリマニフェストスキーマに関するページを参照してください。
manifest.json ファイルを開きます。
アプリマニフェストファイルの webApplicationInfo セクションに次のコードスニペットを追加します。
```
"webApplicationInfo":
{
"id": "{Microsoft Entra AppId}",
"resource": "api://subdomain.example.com/{Microsoft Entra AppId}"
}
```
ここで、
- {Microsoft Entra AppId}は、Microsoft Entra IDでアプリを登録したときに作成したアプリ ID です。これは GUID です。
- api://subdomain.example.com/{Microsoft Entra AppId}は、Microsoft Entra IDでスコープを作成するときに登録したアプリ ID URI です。

アプリマニフェストファイルの composeExtensions セクションに次のコードスニペットを追加します。

"authorization": {
  "authType": "microsoftEntra",
  “microsoftEntraConfiguration”: {
    “supportsSingleSignOn”: true
  }
},

アプリマニフェストファイルを保存します。

おめでとうございます! API ベースのメッセージ拡張機能に対して SSO を有効にしました。

次の方法で共有

API ベースのメッセージ拡張機能の SSO を有効にする

前提条件

Microsoft Entra IDで新しいアプリを登録する

アクセストークンのスコープを構成する

アプリ ID URI

API スコープを構成する

承認されたクライアントアプリケーションを構成する

トークンの認証

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

関連項目

その他のリソース

次の方法で共有

API ベースのメッセージ拡張機能の SSO を有効にする

前提条件

Microsoft Entra IDで新しいアプリを登録する

アクセス トークンのスコープを構成する

アプリ ID URI

API スコープを構成する

承認されたクライアント アプリケーションを構成する

トークンの認証

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

関連項目

その他のリソース

アクセストークンのスコープを構成する

承認されたクライアントアプリケーションを構成する

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