エージェントまたはアプリの RSC アクセス許可要件を宣言する

Teams 開発者ポータルを使用して、エージェントまたはアプリの RSC アクセス許可 要件を宣言したり、アプリ マニフェストで手動で構成したりできます。

アクセス許可を宣言してもアクセスは許可されません: 承認されたユーザーは、organization's 同意ポリシーに従って、ターゲット リソースにアプリをインストールするときに同意を付与します。 インストール ダイアログには、アプリによって要求されたアクセス許可が表示されます。

前提条件

この記事は、 Teams エージェント クイックスタート または同様のプロセスを通じてエージェントまたはアプリが既にセットアップされていることを前提としています。

アクセス許可を宣言する前に、以下を行います。

• アプリに必要な RSC アクセス許可 とリソース スコープを特定します。 その機能に必要なアクセス許可のみを要求します。
• アプリの webApplicationInfo.id プロパティで使用できる既存のアプリケーション (クライアント) ID を用意します。
• organization のポリシーが必要な同意を許可していることを確認します。 同意がブロックされている場合は、管理者と協力してください。 関連する管理ガイダンスについては、「 Teams アプリのアクセス許可への同意の付与と管理」を参照してください。

カスタム アプリのテストの場合は、organization がカスタム アプリのアップロードを許可していることを確認し、インストールする organization 用に構成されたアプリを使用します。 パッケージ化とインストールの前提条件については、「 Teams でアプリをアップロードする」を参照してください。

Teams では、エージェントまたはアプリごとに最大 16 個の RSC アクセス許可宣言がサポートされています。

委任された RSC アクセス許可を使用するには、アプリ マニフェスト v1.12 以降を使用する必要があります。 以前のバージョンを使用している場合は、エージェントまたはアプリで使用されるアプリ マニフェストのバージョンを更新することを強く検討してください。

開発者ポータルで RSC アクセス許可を宣言する

Teams 用開発者ポータルを使用すると、JSON を直接編集せずに、アプリのアクセス許可要件を編集できます。

1. 開発者ポータルで、[ アプリ ] を選択し、既存のアプリを開きます。 アプリ パッケージをデベロッパー ポータルの外部で管理する場合は、まずパッケージをインポートします。
2. [ 構成] で [ 基本情報 ] を選択し、 アプリケーション (クライアント) ID がアプリの既存のアプリケーション ID と一致していることを確認します。
3. [ 構成] で、[ アクセス許可] を選択します。
4. アプリがアクセスするリソースに応じて、[チームのアクセス許可]、[Chat/Meeting のアクセス許可]、または [ユーザーのアクセス許可] で必要な RSC アクセス許可を選択します。
5. 変更内容を保存します。
6. Configure>App パッケージ エディターで更新されたmanifest.jsonを確認します。 更新されたパッケージを使用する前に、アクセス許可の名前と種類が要件と一致していることを確認してください。

詳細については、「 デベロッパー ポータルでのアプリの管理」を参照してください。

アプリ マニフェストで RSC アクセス許可を宣言する

開発者ポータルの代わりに、エージェントまたはアプリのアプリ マニフェストを直接手動で編集できます。 アプリ マニフェスト バージョンの形式を使用します。

アプリ マニフェスト v1.12 以降

アプリ マニフェストで RSC アクセス許可を宣言するには:

1. 次の値を使用して webApplicationInfo キーをアプリ マニフェストに追加します。

   名前	型	説明
   id	文字列	エージェントまたはアプリの既存のアプリケーション (クライアント) ID。
   resource	文字列	オプションの認証リソース値。 RSC アクセスは許可されません。 アプリでシングル サインオン (SSO) を使用する場合は、構成した値を保持します。

2. アプリに必要なアクセス許可を追加します。

   名前	型	説明
   authorization	オブジェクト	アプリを実行する必要があるアクセス許可の一覧。 詳細については、「 アプリ マニフェストでの承認」を参照してください。

   各アクセス許可の名前とその Application または Delegated の種類を authorization.permissions.resourceSpecific で一覧表示します。 アプリがチーム スコープとチャット スコープの両方でのインストールをサポートする場合は、チームとチャットの両方のアクセス許可を同じ配列で宣言できます。 アプリに必要なアクセス許可のみを含めます。 RSC の概要 には、サポートされているアクセス許可が記載されています。

例:

{
    "webApplicationInfo": {
        "id": "00000000-0000-0000-0000-000000000000",
        "resource": "https://RscBasedStoreApp"
    },
    "authorization": {
        "permissions": {
            "resourceSpecific": [
                {
                    "name": "TeamSettings.Read.Group",
                    "type": "Application"
                },
                {
                    "name": "ChannelMeetingStage.Write.Group",
                    "type": "Delegated"
                }
            ]
        }
    }
}

アプリ マニフェスト v1.11 以前

次の値を使用して webApplicationInfo キーをアプリ マニフェストに追加します。

アプリがチーム スコープとチャット スコープの両方でのインストールをサポートすることを目的としている場合は、チームとチャットの両方のアクセス許可を同じアプリ マニフェストの applicationPermissions で指定できます。

例:

{
    "webApplicationInfo": {
        "id": "00000000-0000-0000-0000-000000000000",
        "resource": "https://RscBasedStoreApp",
        "applicationPermissions": [
            "TeamSettings.Read.Group",
            "TeamsActivity.Send.User"
        ]
    }
}

アプリに付与されている RSC アクセス許可を確認する

許可を確認する前に、テストするチーム、チャット、または個人用スコープにアプリをインストールします。 カスタム アプリのインストールについては、「 Teams でアプリをアップロードする」を参照してください。 要求されたアクセス許可に対して承認されたユーザーの同意を得る。

最初のインストール後、アクセス許可要件を変更し、該当する アプリの更新と同意フローを完了した後、またはアクセス拒否応答のトラブルシューティングを行うときに、許可を確認します。 このチェックでは、マニフェストで宣言されているアクセス許可と、特定のリソースに実際に付与されたアクセス許可を区別します。

たとえば、アプリが TeamSettings.Read.Group を要求し、チーム A にインストールされている場合は、チーム A の許可を調べます。アプリのアプリケーション ID を検索し、その許可にその許可が含まれていることを確認します。 チーム A の許可は、チーム B に同じアクセスを付与しません。

次の手順では、Microsoft Graph を介して アプリケーションの RSC アクセス許可 を検査します。 委任された RSC アクセス許可は、サインインしたユーザーのコンテキストで Teams クライアント API を通じて使用されます。以下の application-grant チェックでは、その委任された動作は確認されません。

1. 検証要求を承認します。
2. 特定のリソースに付与されている RSC アクセス許可を確認します。

確認要求を承認する

Microsoft Graph エクスプローラーを使用して、許可を対話形式で検査できます。 アプリがインストールされている organization の職場または学校アカウントでサインインします。 検査するリソースの API リファレンスの [アクセス許可] セクションを確認し、Graph エクスプローラーに必要な委任されたアクセス許可を承認します。

これらのアクセス許可により、 検査ツール が許可を読み取ることが承認されます。 これらは、アプリに対して検証されるアクセス許可ではありません。 検査要求での認証エラーは、それ自体がアプリの RSC 許可がないことを意味しません。

代わりに独自のツールから要求を送信する場合は、適切な 代理認証フロー または アプリケーション認証フローを使用して、その検査 API で必要なアクセス許可を使用して、Microsoft Graph アクセス トークンを取得します。 Graph エクスプローラーを使用するためだけにアプリにトークン取得を実装する必要はありません。

特定のリソースに付与されている RSC アクセス許可を確認する

以下のリソースの手順を使用してください。 permissionGrants エンドポイントは、インストールされているアプリのリストではなく許可を返します。 インストールを個別に調査するには、[ チーム内のアプリの一覧表示]、[ チャット内のアプリの一覧表示]、または [ユーザー用アプリの一覧表示]を使用します。

成功した 200 OK 応答の場合:

• clientAppIdがアプリ マニフェスト内の webApplicationInfo.id と一致するエントリを検索します。 トップレベル アプリ マニフェスト idと混同しないでください。
• 各エントリの permission を、そのリソース スコープに対して宣言されているアプリケーションのアクセス許可名と比較します。
• 検証するアプリケーション許可に対して permissionType が Application ていることを確認します。

予想される許可がない場合は、リソース ID、インストールされているアプリ パッケージとそのアプリケーション ID、および更新されたアクセス許可への同意が完了したかどうかチェックします。 組織のポリシーによって同意できない場合は、管理者と連携します。 許可を検査すると、記録されたアクセスが確認されます。アプリの API 呼び出しが機能したことを証明するものではありません。 フォローアップ する Teams でリソース固有の同意のアクセス許可をテストする。

チームで追加された RSC アクセス許可をアプリで確認する

1. Teams で、アプリをインストールしたチームを見つけます。

2. そのチームの [その他のオプション (...)] を選択します。

3. ドロップダウン リストから [ チームへのリンクを取得] を選択します。

4. リンクから groupId 値をコピーし、次の要求で {team-id} として使用します。

5. Graph エクスプローラーで、要求を送信します:

   GET https://graph.microsoft.com/v1.0/teams/{team-id}/permissionGrants
   

   clientAppIdをアプリのwebApplicationInfo.idと一致させ、返されたアクセス許可をチームに要求されたアプリケーションのアクセス許可と比較します。

要求のアクセス許可と応答の詳細については、「 アクセス許可の一覧表示」を参照してください。

チャットで追加された RSC アクセス許可をアプリで確認する

1. アプリをインストールしたチャットの ID を取得します。 チャットのリストを使用すると、チャットとそのidを検索できます。呼び出す前に、その API のアクセス許可を確認してください。

2. {chat-id}をチャット ID に置き換え、Graph エクスプローラー で次の要求を送信します。

   GET https://graph.microsoft.com/v1.0/chats/{chat-id}/permissionGrants
   

   clientAppIdアプリのwebApplicationInfo.idと一致させ、返されたアクセス許可をチャットに要求されたアプリケーションのアクセス許可と比較します。

リクエストのアクセス許可と応答の詳細については、「 チャットのアクセス許可の付与を一覧表示する」を参照してください。

アプリで、ユーザーの追加された RSC アクセス許可を確認する

1. [ ユーザーの取得 ] を使用して、インストールされているアプリが個人用スコープを含むユーザーの ID を見つけます。 呼び出す前に、その API のアクセス許可を確認してください。

2. {user-id}ユーザー ID に置き換え、Graph エクスプローラー で次の要求を送信します。

   GET https://graph.microsoft.com/v1.0/users/{user-id}/permissionGrants
   

   clientAppIdをアプリのwebApplicationInfo.idと一致させ、返されたアクセス許可を、ユーザーに要求されたアプリケーションのアクセス許可と比較します。

リクエストのアクセス許可と応答の詳細については、「 ユーザーの許可の付与の一覧表示」を参照してください。

コード サンプル

以下の 2 つの Node.js サンプルは、Teams JavaScript クライアント ライブラリ (@microsoft/teams-js) と Microsoft Graph クライアントを使用する Teams タブのサンプルです。 これらは Teams SDK サンプルではありません。

関連項目

• Teams でリソース固有の同意アクセス許可をテストする
• Teams アプリに対するリソース固有の同意
• 開発者ポータルでアプリを管理する
• Teams アプリのアクセス許可に対する同意の付与と管理
• アクセス許可を一覧表示するユーザーの付与
• ユーザーに通知を送信する