ロール要求を構成する

[アーティクル]
10/29/2023

アプリケーションが承認された後に受け取るアクセストークンのロール要求をカスタマイズできます。トークンでカスタムロールを想定するアプリケーションの場合は、この機能を使用します。ロールは、必要な数だけ作成できます。

前提条件

テナントが構成されている Microsoft Entra サブスクリプション。詳細については、「クイックスタート: テナントを設定する」を参照してください。
テナントに追加されているエンタープライズアプリケーション。詳細については、「クイックスタート: エンタープライズアプリケーションを追加する」を参照してください。
アプリケーションでシングルサインオン (SSO) が構成されている。詳細については、「エンタープライズアプリケーションのシングルサインオンを有効にする」を参照してください。
ロールに割り当てられているユーザーアカウント。詳細については、「クイックスタート*: ユーザーアカウント*を作成して割り当てる*」を参照してください。

注意

この記事では、API を使用して、サービスプリンシパルでアプリケーションロールを作成、更新、削除する方法について説明します。アプリロールの新しいユーザーインターフェイスを使用するには、「アプリケーションにアプリロールを追加してトークンで受け取る」を参照してください。

エンタープライズアプリケーションを見つける

ヒント

この記事の手順は、開始するポータルによって若干異なる場合があります。

次の手順を実行して、エンタープライズアプリケーションを見つけます。

クラウドアプリケーション管理者以上として Microsoft Entra 管理センターにサインインします。
[ID]>[アプリケーション]>[エンタープライズアプリケーション]>[すべてのアプリケーション] に移動します。
検索ボックスに既存のアプリケーションの名前を入力し、検索結果からアプリケーションを選択します。
アプリケーションを選択したら、概要ペインからオブジェクト ID をコピーします。

ロールを追加する

Microsoft Graph Explorer を使用してエンタープライズアプリケーションにロールを追加します。

別のウィンドウで Microsoft Graph Explorer を開き、テナントの管理者資格情報を使用してサインインします。

注意

このシナリオでは、クラウドアプリ管理者ロールとアプリ管理者ロールは機能しません。ディレクトリの読み取りと書き込みには、グローバル管理者のアクセス許可が必要です。
[アクセス許可の変更] を選択し、Application.ReadWrite.All の [同意] と一覧の Directory.ReadWrite.All アクセス許可を選択します。
次の要求の <objectID> を、以前に記録したオブジェクト ID に置き換えてからクエリを実行します。

https://graph.microsoft.com/v1.0/servicePrincipals/<objectID>
エンタープライズアプリケーションは、サービスプリンシパルとも呼ばれます。返されたサービスプリンシパルオブジェクトから appRoles プロパティを記録します。次の例は、一般的な appRoles プロパティを示しています。
```
{
  "appRoles": [
    {
      "allowedMemberTypes": [
        "User"
      ],
      "description": "msiam_access",
      "displayName": "msiam_access",
      "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "isEnabled": true,
      "origin": "Application",
      "value": null
    }
  ]
}
```
Graph Explorer で、メソッドを GET から PATCH に変更します。
記録しておいた appRoles プロパティを Graph Explorer の [要求本文] ペインにコピーし、新しいロール定義を追加してから [クエリの実行] を選択してパッチ操作を実行します。成功メッセージにより、ロールの作成が確認されます。次の例は、Admin ロールを追加する例を示しています。
```
{
  "appRoles": [
    {
      "allowedMemberTypes": [
        "User"
      ],
      "description": "msiam_access",
      "displayName": "msiam_access",
      "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "isEnabled": true,
      "origin": "Application",
      "value": null
    },
    {
      "allowedMemberTypes": [
        "User"
      ],
      "description": "Administrators Only",
      "displayName": "Admin",
      "id": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
      "isEnabled": true,
      "origin": "ServicePrincipal",
      "value": "Administrator"
    }
  ]
}
```
要求本文には、新しいロールに加えて msiam_access ロールオブジェクトを含める必要があります。要求本文に既存のロールを含めないと、それらは appRoles オブジェクトから削除されます。また、組織が必要とする数のロールを追加できます。 SAML 応答の要求値として、これらのロールの値が送信されます。新しいロールの ID の GUID 値を生成するには、オンライン GUID/UUID ジェネレーターなどの Web ツールを使用します。応答の appRoles プロパティには、クエリの要求本文の内容が含まれます。

属性の編集

属性を更新して、トークンに含まれるロール要求を定義します。

Microsoft Entra 管理センターでアプリケーションを見つけたら、左側のメニューで [シングルサインオン] を選択します。
[属性と要求] セクションで、[編集] を選択します。
[新しい要求の追加] を選択します。
[名前] ボックスに、属性名を入力します。この例では、要求名としてロールの名前を使用します。
[名前空間] ボックスは空白のままにします。
[ソース属性] の一覧から、[user.assignedroles] を選択します。
[保存] を選択します。新しい「ロール名」属性が [属性と要求] セクションに表示されます。これで、アプリケーションにサインインするときに、この要求がアクセストークンに含まれるようになります。

ロールを割り当てる

より多くのロールでサービスプリンシパルを修正したら、対応するロールにユーザーを割り当てることができます。

Microsoft Entra 管理センターで、ロールが追加されたアプリケーションを見つけます。
左側のメニューで [ユーザーとグループ] を選択し、新しいロールを割り当てるユーザーを選択します。
ペインの上部にある [割り当ての編集] を選択して、ロールを変更します。
[選択されていません] を選択してから一覧からロールを選択し、[選択] を選択します。
[割り当て] を選択して、ロールをユーザーに割り当てます。

ロールを更新する

既存のロールを更新するには、以下の手順を実行します。

Microsoft Graph Explorer を開きます。
テナントのグローバル管理者または共同管理者の資格情報を使用して、Graph Explorer サイトにサインインします。
次の要求にある <objectID> を、概要ペインに記載されたアプリケーションのオブジェクト ID に置き換え、クエリを実行します。

https://graph.microsoft.com/v1.0/servicePrincipals/<objectID>
返されたサービスプリンシパルオブジェクトから appRoles プロパティを記録します。
Graph Explorer で、メソッドを GET から PATCH に変更します。
記録しておいた appRoles プロパティを Graph Explorer の [要求本文] ペインにコピーし、ロール定義を更新してから [クエリの実行] を選択してパッチ操作を実行します。

ロールの削除

既存のロールを削除するには、以下の手順を実行します。

Microsoft Graph Explorer を開きます。
テナントのグローバル管理者または共同管理者の資格情報を使用して、Graph Explorer サイトにサインインします。
次の要求にある <objectID> を、Azure portal の概要ペインに記載されたアプリケーションのオブジェクト ID に置き換え、クエリを実行します。

https://graph.microsoft.com/v1.0/servicePrincipals/<objectID>
返されたサービスプリンシパルオブジェクトから appRoles プロパティを記録します。
Graph Explorer で、メソッドを GET から PATCH に変更します。
記録しておいた appRoles プロパティを Graph Explorer の [要求本文] ペインにコピーし、削除するロールの IsEnabled の値を false に設定したら、[クエリの実行] を選択してパッチ操作を実行します。ロールを削除するには、まず無効にする必要があります。
ロールを無効にした後、そのロールのブロックを appRoles セクションから削除します。メソッドを PATCH にしたまま、[クエリの実行] を再度選択します。

次のステップ

要求のカスタマイズの詳細については、ハウツー記事「エンタープライズアプリケーションの SAML トークンで発行された要求のカスタマイズ」を参照してください。