ロール要求を構成する

2025-04-30

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

前提条件

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

注意

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

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

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

Microsoft Entra 管理センターに、少なくともクラウドアプリケーション管理者としてサインインします。
Entra ID>Enterprise アプリ>すべてのアプリケーションを参照します。
検索ボックスに既存のアプリケーションの名前を入力し、検索結果からアプリケーションを選択します。
アプリケーションを選択したら、概要ペインからオブジェクト 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 エクスプローラーで、メソッドを GET から PATCH に変更します。
Graph エクスプローラーの [要求本文 ] ウィンドウに以前に記録した appRoles プロパティをコピーし、新しいロール定義を追加し、[ クエリの実行 ] を選択してパッチ操作を実行します。成功メッセージにより、ロールの作成が確認されます。次の例は、 管理者 ロールの追加を示しています。
```
{
  "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 エクスプローラーを開きます。
Graph Explorer サイトに特権ロール管理者としてサインインします。
次の要求にある <objectID> を、概要ペインに記載されたアプリケーションのオブジェクト ID に置き換え、クエリを実行します。

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

ロールの削除

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

Microsoft Graph エクスプローラーを開きます。
Graph Explorer サイトに特権ロール管理者としてサインインします。
次の要求にある <objectID> を、Azure portal の概要ペインに記載されたアプリケーションのオブジェクト ID に置き換え、クエリを実行します。

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

次のステップ

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