アプリケーションにアプリ ロールを追加してトークンで受け取る
ロールベースのアクセス制御 (RBAC) は、アプリケーションにおいて承認を実施する一般的なメカニズムです。 RBAC を使用すると、管理者は特定のユーザーまたはグループに対してではなく、ロールに対してアクセス許可を付与できます。 その後、管理者はロールをさまざまなユーザーやグループに割り当てて、コンテンツや機能にだれがアクセスできるかを制御できます。
RBAC をアプリケーション ロールおよびロール要求と一緒に使用すると、開発者はあまり手間をかけずにアプリでの承認を確実に行うことができます。
もう 1 つの方法として、GitHub 上の active-directory-aspnetcore-webapp-openidconnect-v2 コード サンプルで示されているように、Microsoft Entra グループとグループ要求を使うこともできます。 Microsoft Entra グループとアプリケーション ロールは相互に排他的ではありません。一緒に使うことで、さらにきめ細かいアクセス制御を提供できます。
アプリケーションのロールを宣言する
アプリ ロールは、アプリの登録プロセス時に、[Microsoft Entra 管理センター] を使用して定義します。 アプリのロールは、サービス、アプリ、または API を表すアプリケーション登録で定義されます。 ユーザーがアプリケーションにサインインすると、Microsoft Entra ID によって、ユーザーまたはサービス プリンシパルに付与された各ロールの roles 要求が生成されます。 これは、クレームベースの認可を実装するために使用できます。 アプリ ロールはユーザーまたはユーザー グループに割り当てることができます。 アプリ ロールは、別のアプリケーションのサービス プリンシパルに割り当てたり、マネージド ID のサービス プリンシパルに割り当てたりすることもできます。
現時点、サービス プリンシパルをグループに追加してから、そのグループにアプリ ロールを割り当てる場合、Microsoft Entra ID では、そこで発行されるトークンに roles 要求は追加されません。
アプリ ロールは、[Microsoft Entra 管理センター] のアプリ ロール UI を使用して宣言されます。
追加するロールの数は、Microsoft Entra ID によって適用されるアプリケーション マニフェストの制限に照らしてカウントされます。 このような制限については、Microsoft Entra ID のアプリ マニフェスト リファレンスに関するページの「マニフェストの制限」セクションを参照してください。
アプリ ロール UI
ヒント
この記事の手順は、開始するポータルによって若干異なる場合があります。
[Microsoft Entra 管理センター] のユーザー インターフェイスを使用してアプリ ロールを作成するには次の手順に従ってください:
クラウド アプリケーション管理者以上として Microsoft Entra 管理センターにサインインします。
複数のテナントにアクセスできる場合は、上部のメニューの [設定] アイコン
を使用し、[ディレクトリとサブスクリプション] メニューからアプリケーション登録が含まれるテナントに切り替えます。[ID]>[アプリの登録]>[アプリの登録] の順に移動して、アプリ ロールを定義するアプリケーションを選択します。
[管理] で、[アプリ ロール] を選択して、[アプリ ロールの作成] を選択します。
[Create app role](アプリのロールの作成) ペインで、ロールの設定を入力します。 図の下の表では、各設定とそのパラメーターについて説明します。
フィールド Description 例 表示名 管理者の同意やアプリの割り当て時に表示されるアプリのロールの表示名です。 この値にはスペースを含めることができます。 Survey WriterAllowed member types (許可されるメンバーの種類) このアプリのロールをユーザー、アプリケーション、またはその両方に割り当てることができるかどうかを指定します。 applicationsから使用できる場合、アプリ ロールは、アプリの登録の [管理] セクション > [API のアクセス許可] > [アクセス許可の追加] > [自分の API] > [API を選択する] > [アプリケーションの許可] の下にアプリケーションのアクセス許可として表示されます。Users/GroupsValue アプリケーション側でトークンに想定するロール要求の値を指定します。 この値は、アプリケーションのコードで参照される文字列と正確に一致する必要があります。 値にスペースを含めることはできません。 Survey.Create説明 管理者のアプリの割り当てと同意エクスペリエンスの間に表示されるアプリのロールの詳細な説明。 Writers can create surveys.Do you want to enable this app role? (このアプリのロールを有効にしますか?) アプリ ロールを有効にするかどうかを指定します。 アプリのロールを削除するには、このチェックボックスをオフにして、変更を適用してから削除操作を試行してください。 この設定は、アプリ ロールの使用状況と可用性を制御します。アプリ ロールは完全に削除するのではなく、一時的または永続的に無効にできます。 オン [適用] を選択して変更を保存します。
アプリ ロールが有効に設定されている場合、割り当てられているすべてのユーザー、アプリケーション、またはグループのトークンにはそのロールが含まれます。 これらのトークンは、アプリで API を呼び出す場合はアクセス トークンであり、アプリがユーザーのサインインを行う場合は ID トークンになります。 アプリ ロールを無効に設定すると、アプリ ロールは非アクティブになり、割り当てできなくなります。 以前の割り当て先のトークンにはアプリ ロールが含まれていますが、アクティブに割り当てできなくなったため無効になっています。
アプリケーションの所有者を割り当てる
まだ行っていない場合は、アプリケーション所有者として自分自身を割り当てる必要があります。
- アプリの登録の [管理] で、[所有者] を選択し、[所有者の追加] を選択します。
- 新しいウィンドウで、アプリケーションに割り当てる所有者を見つけて選びます。 選択した所有者が右側のパネルに表示されます。 完了したら、[選択] で確定します。 これで、アプリ所有者が所有者の一覧に表示されます。
Note
必ず、API アプリケーションと、アクセス許可を追加するアプリケーションの両方に所有者を設定してください。そうしなければ、API のアクセス許可を要求するときに API が一覧表示されません。
アプリケーションへのアプリ ロールの割り当て
アプリケーションにアプリ ロールを追加したら、[Microsoft Entra 管理センター] を使用するか、Microsoft Graph を使用してプログラムでアプリ ロールをクライアント アプリに割り当てることができます。 これを、ユーザーへのロールの割り当てと混同しないでください。
アプリケーションにアプリ ロールを割り当てるときは、"アプリケーションのアクセス許可" を作成します。 通常、アプリケーションのアクセス許可は、認証および承認された API 呼び出しをユーザーによる操作なしで行う必要がある、デーモン アプリまたはバックエンド サービスによって使用されます。
[Microsoft Entra 管理センター] を使用して、アプリケーションにアプリロールを割り当てるには、次の手順に従ってください。
- クラウド アプリケーション管理者以上として Microsoft Entra 管理センターにサインインします。
- [ID]>[アプリケーション]>[アプリの登録] の順に移動して、[すべてのアプリケーション] を選択します。
- [すべてのアプリケーション] を選択して、すべてのアプリケーションの一覧を表示します。 アプリケーションが一覧に表示されない場合は、 [すべてのアプリケーション] 一覧の上部にあるフィルターを使用して一覧を制限するか、一覧を下にスクロールしてアプリケーションを見つけます。
- アプリ ロールを割り当てるアプリケーションを選択します。
- [API のアクセス許可] 、 [アクセス許可の追加] の順に選択します。
- [マイ API] タブを選択し、アプリ ロールを定義したアプリを選択します。
- [アクセス許可] で、割り当てるロールを選びます。
- ロールの追加を完了するために、 [アクセス許可の追加] ボタンを選択します。
新しく追加されたロールは、アプリの登録の [API のアクセス許可] ペインに表示されます。
管理者の同意の付与
これらは委任されたアクセス許可ではなく、"アプリケーションのアクセス許可" であるため、アプリケーションに割り当てられたアプリ ロールの使用に管理者が同意を付与する必要があります。
- アプリの登録の [API のアクセス許可] ペインで、[<テナント名> に管理者の同意を与えます]を選択します。
- 要求されたアクセス許可への同意の付与を求めるメッセージが表示されたら、 [はい] を選択します。
[状態] 列には、同意が <テナント名> に付与されたことが反映されているはずです。
アプリ ロールの使用シナリオ
アプリケーションのシナリオでユーザーをサインインするアプリ ロールのビジネス ロジックを実装する場合は、最初にアプリの登録にアプリ ロールを定義します。 次に、管理者が [エンタープライズ アプリケーション] ペインでユーザーとグループに割り当てます。 これらの割り当てられたアプリ ロールは、アプリケーションに対して発行されるすべてのトークンに含まれます。
アプリ呼び出し API のシナリオでアプリ ロールのビジネス ロジックを実装している場合は、2 つのアプリ登録があります。 1 番目のアプリ登録はアプリ用であり、2 番目のアプリ登録は API 用です。 この場合は、アプリ ロールを定義して、API のアプリ登録でユーザーまたはグループに割り当てます。 ユーザーがアプリを使用して認証し、アクセス トークンを要求して API が呼び出されると、ロール要求がトークンに含められます。 次の手順は、API が呼び出されたときにこれらのロールを確認するコードを Web API に追加することです。
Web API に承認を追加する方法については、「保護された Web API: スコープとアプリのロールを検証する」を参照してください。
アプリ ロールとグループ
承認にはアプリ ロールまたはグループを使用できますが、両者の間の重要な違いは、実際のシナリオでどちらを使用するかの決定に影響する可能性があります。
| アプリ ロール | グループ |
|---|---|
| アプリケーションに固有のものであり、アプリの登録で定義されます。 これらはアプリケーションと共に移動します。 | これらは、アプリケーション固有ではなく、Microsoft Entra テナント固有です。 |
| アプリ ロールは、アプリの登録が削除されると削除されます。 | アプリが削除されても、グループはそのまま残ります。 |
roles 要求で提供されます。 |
groups 要求で提供されます。 |
開発者はアプリ ロールを使用して、ユーザーがアプリにサインインできるか、Web API のアクセス トークンをアプリで取得できるかを制御できます。 このセキュリティ制御をグループにまで拡張するために、開発者と管理者は、セキュリティ グループをアプリ ロールに割り当てることもできます。
開発者がアプリ自体に承認のパラメーターを記述して制御する必要がある場合は、アプリ ロールをお勧めします。 たとえば、承認にグループを使用するアプリは、グループ ID と名前の両方が異なる可能性があるため、次のテナントで中断されます。 アプリ ロールを使用するアプリは安全なままです。 実際、アプリ ロールにグループを割り当てることは、SaaS アプリが複数のテナントにプロビジョニングされることを許可するのと同じ理由で、SaaS アプリでも一般的です。
ユーザーとグループを Microsoft Entra のロールに割り当てる
アプリケーションにアプリ ロールを追加したら、Microsoft Entra のロールにユーザーとグループを割り当てることができます。 ユーザーとグループのロールへの割り当ては、ポータルの UI を介して行うか、Microsoft Graph を使用してプログラミングによって行うことができます。 さまざまなロールに割り当てられたユーザーがアプリケーションにサインインすると、そのトークンは roles 要求で割り当てられたロールを持つようになります。
[Microsoft Entra 管理センター] を使用して、ユーザーとグループをロールに割り当てるには、次の手順に従ってください。
- クラウド アプリケーション管理者以上として Microsoft Entra 管理センターにサインインします。
- 複数のテナントにアクセスできる場合は、上部のメニューの [設定] アイコン を使用し、[ディレクトリとサブスクリプション] メニューからアプリケーション登録が含まれるテナントに切り替えます。
- ID>アプリケーション>エンタープライズ アプリケーション を参照します。
- [すべてのアプリケーション] を選択して、すべてのアプリケーションの一覧を表示します。 アプリケーションが一覧に表示されない場合は、 [すべてのアプリケーション] 一覧の上部にあるフィルターを使用して一覧を制限するか、一覧を下にスクロールしてアプリケーションを見つけます。
- ユーザーまたはグループをロールに割り当てるアプリケーションを選択します。
- [管理] で [ユーザーとグループ] を選択します。
- [ユーザーの追加] を選択し、 [割り当ての追加] ペインを開きます。
- [割り当ての追加] ウィンドウから [ユーザーとグループ] セレクターを選択します。 ユーザーとセキュリティ グループの一覧が表示されます。 特定のユーザーまたはグループを検索することや、一覧に表示される複数のユーザーやグループを選択することができます。
- ユーザーとグループを選択したら、 [選択] ボタンを選択して続行します。
- [割り当ての追加] ペインで [ロールの選択] を選択します。 アプリケーションに対して定義されているすべてのロールが表示されます。
- ロールを選択し、 [選択] ボタンを選択します。
- [割り当て] ボタンを選択して、アプリへのユーザーとグループの割り当てを完了します。
追加したユーザーとグループが [ユーザーとグループ] の一覧に表示されることを確認します。
次のステップ
アプリ ロールの詳細については、次のリソースを参照してください。
- コード サンプル (GitHub)
- リファレンス ドキュメント
- ビデオ:Microsoft ID プラットフォームを使用してアプリケーションで承認を実装する (1:01:15)