MENU

Microsoft Graph で PIM 有資格ロールの最大期間を取得する方法｜AU スコープでも共通になる理由

Azure

Microsoft Entra ID（旧 Azure AD）の PIM 設定を自動チェックしたくて、「このロールは最長どれくらい eligible にできるのか？」を Graph API や PowerShell から取りたくなる場面は多いはずです。ところが管理単位（Administrative Unit; AU）スコープのロールになると、ドキュメントだけでは挙動が分かりづらく、実装でつまずきがちです。

目次

roleManagementPolicyAssignments は管理単位（AU）をサポートしないのか？という疑問

まず、よくある疑問を整理します。

  • ディレクトリ全体（scopeId = '/', scopeType = 'Directory'）にスコープされた PIM ロールについては、roleManagementPolicyAssignments から maximumDuration を取得できる。
  • しかし、AU にスコープされたロール（Administrative Unit scope）の場合、scopeType = 'AdministrativeUnit' が公式ドキュメントにほとんど出てこない。
  • 「もしかして AU スコープのロールには別ポリシーがあって、Graph から取れないのでは？」という不安が出てくる。

結論から言うと、この疑問は「ロール設定（role settings）の適用単位」を押さえればすっきり解消します。

PIM のロール設定は「ポリシー」と「ルール」で構成される

Microsoft Entra の PIM では、ロール設定は以下の 2 つのリソースで表現されています。

  • unifiedRoleManagementPolicy（ポリシー本体）
  • unifiedRoleManagementPolicyAssignment（どのロール／スコープにどのポリシーを適用するか、というひも付け）

ポリシー本体の中には、さらに複数の「ルール」が含まれています。これは unifiedRoleManagementPolicyRule の派生型として定義され、以下の 5 系統に分類されています。

  • 有効期限ルール：unifiedRoleManagementPolicyExpirationRule
  • 有効化条件ルール：unifiedRoleManagementPolicyEnablementRule
  • 承認ルール：unifiedRoleManagementPolicyApprovalRule
  • 通知ルール：unifiedRoleManagementPolicyNotificationRule
  • 認証コンテキストルール：unifiedRoleManagementPolicyAuthenticationContextRule

Microsoft の公開情報では、PIM ロール設定には 17 個の既定ルールがあり、それぞれに固定の id（例：Expiration_EndUser_Assignment）と役割が割り当てられています。

「最大期間（maximumDuration）」は Expiration 系ルールに出てくる

今回の主役は、有効期限ルール（unifiedRoleManagementPolicyExpirationRule）です。これらのルールには、次のようなプロパティがあります。

  • id：ルール ID（例：Expiration_Admin_Assignment）
  • isExpirationRequired：期限設定を必須にするかどうか
  • maximumDuration：許される最大期間（ISO 8601 期間表記）
  • target：どの「呼び出し元（Admin / EndUser）」と「レベル（Assignment / Eligibility）」に適用されるか

特に次の 3 つのルールは、実運用で頻繁に目にします。

ルール IDcallerlevel意味合い（概要）
Expiration_Admin_EligibilityAdminEligibility管理者が作成する「有資格（eligible）割り当て」の有効期限ルール
Expiration_Admin_AssignmentAdminAssignment管理者による「アクティブ割り当て」の有効期限ルール（既定で 180 日の例あり）
Expiration_EndUser_AssignmentEndUserAssignmentエンドユーザーが PIM から自分で有効化したセッションの最大時間（既定で 8 時間の例あり）

つまり、「最大何日まで eligible にできるか」「最大何時間までアクティブにできるか」は、これら Expiration 系ルールの maximumDuration を読むことで判断できます。

ロール設定はディレクトリ全体と AU で共通：結論

では、管理単位（AU）にスコープされたロールの場合はどうでしょうか。

Microsoft Q&A では、まさに同じ疑問に対して、MVP による次のような回答が出ています（要約）。

  • ロール設定（Role settings）は、ディレクトリ全体と AU スコープで共通である。
  • そのため、最大期間は「ロールごと」に決まり、スコープ（Directory vs AdministrativeUnit）によって変わらない。
  • 違いが出るのは、Admin / EndUser といった呼び出し元や、Eligibility / Assignment といったレベルだけ。

公式ドキュメント上も、PIM for Microsoft Entra roles のポリシー（roleManagementPolicies）を取得する際の scopeId と scopeType は、ディレクトリ全体を示す '/' と 'Directory'（または 'DirectoryRole'）に限定して説明されています。

つまり、PIM ロール設定は「ロール単位」でディレクトリ全体に対して定義され、その設定が AU にスコープした割り当てにもそのまま適用されます。

実務的な結論

有資格ロール割り当ての最大期間（maximumDuration）を確認したいだけなら、AU を気にせず次の方針で OK です。

  1. 対象ロールの roleDefinitionId を特定する。
  2. scopeId = '/' かつ scopeType = 'Directory'（または 'DirectoryRole'）で roleManagementPolicyAssignments を取得する。
  3. 展開された policy.rules から、目的の Expiration ルール（Expiration_***）の maximumDuration を読む。

AU スコープかどうかは、最大期間の計算には影響しない、というのがポイントです。

Directory スコープのポリシーから最大期間を取得する手順

手順 1：対象ロールの roleDefinitionId を調べる

まずは対象となる PIM ロール（例：グローバル管理者）に対応する roleDefinitionId を特定します。代表的な取得方法は次のとおりです。

REST API の例

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions
  ?$filter=displayName eq 'Global Administrator'

応答の value[0].id が roleDefinitionId です。

Graph PowerShell の例

Import-Module Microsoft.Graph.Identity.Directory
Connect-MgGraph -Scopes 'RoleManagement.Read.Directory'

$role = Get-MgRoleManagementDirectoryRoleDefinition `
    -Filter "displayName eq 'Global Administrator'"

$roleDefinitionId = $role.Id

手順 2：ディレクトリ全体スコープのポリシー割り当てを取得

次に、対象ロールに紐づくポリシー割り当てをディレクトリ全体スコープで取得します。ドキュメントのサンプルでは、以下のようなクエリが紹介されています。

GET https://graph.microsoft.com/v1.0/policies/roleManagementPolicyAssignments
  ?$filter=scopeId eq '/' and scopeType eq 'Directory' and roleDefinitionId eq '<roleDefinitionId>'
  &$expand=policy($expand=rules)

/beta でもほぼ同じクエリが利用できますが、本番用途では v1.0 の利用が推奨されます。

Graph PowerShell 版（v1.0）

Import-Module Microsoft.Graph.Identity.SignIns
Connect-MgGraph -Scopes 'RoleManagementPolicy.Read.Directory','RoleManagement.Read.Directory'

# ディレクトリ全体スコープ & 特定ロールのポリシー割り当て
$assignment = Get-MgPolicyRoleManagementPolicyAssignment `
    -Filter "scopeId eq '/' and scopeType eq 'Directory' and roleDefinitionId eq '$roleDefinitionId'" `
    -ExpandProperty "policy(`$expand=rules)"

$policy = $assignment.Policy
$rules  = $policy.Rules

ここまでで、対象ロールに適用されている PIM ポリシー（unifiedRoleManagementPolicy）と、その配下の全ルールを取得できました。

手順 3：Expiration 系ルールだけを抽出して maximumDuration を読む

最後に、有効期限関連のルールだけに絞り込みます。API の応答例を見ると、有効期限ルールは @odata.type に unifiedRoleManagementPolicyExpirationRule が入り、ルール ID と maximumDuration が含まれています。

# 「有効期限」系ルールのみ抽出
$expirationRules = $rules | Where-Object {
    $_.'@odata.type' -like '*unifiedRoleManagementPolicyExpirationRule'
}

# 代表的なルールだけ見やすく表示
$expirationRules |
    Select-Object id,
                  @{ Name = 'Caller'; Expression = { $_.target.caller } },
                  @{ Name = 'Level';  Expression = { $_.target.level } },
                  maximumDuration,
                  isExpirationRequired

出力イメージ（例）:

id                          Caller   Level        maximumDuration isExpirationRequired
--                          ------   -----        --------------- --------------------
Expiration_Admin_Eligibility Admin    Eligibility  P365D           False
Expiration_Admin_Assignment  Admin    Assignment   P180D           False
Expiration_EndUser_Assignment EndUser Assignment   PT8H            True

ここから、目的に応じて次のように読み替えられます。

  • 有資格割り当て（eligible）の最大期間：Expiration_Admin_Eligibility.maximumDuration
  • 管理者によるアクティブ割り当ての最大期間：Expiration_Admin_Assignment.maximumDuration
  • エンドユーザーが有効化したセッションの最大時間：Expiration_EndUser_Assignment.maximumDuration

元の質問文のように「有資格割り当てに設定できる最大期間」を知りたいのであれば、通常は Expiration_Admin_Eligibility の maximumDuration を見ることになります。

AU を明示的に問い合わせたい場合（任意）

前述のとおり、ロール設定はロール単位で共通なので、実務上はディレクトリ全体スコープだけを見れば十分です。それでも「AU スコープでも同じ値が返ってくることを検証したい」というケースもあるでしょう。

Microsoft Q&A では、以下のようなクエリ例も紹介されています（/beta）。

GET https://graph.microsoft.com/beta/policies/roleManagementPolicyAssignments
  ?$filter=scopeId eq '<AdministrativeUnitObjectId>'
            and scopeType eq 'AdministrativeUnit'
            and roleDefinitionId eq '<roleDefinitionId>'
  &$expand=policy($expand=rules)

ただし、公式ドキュメントでは scopeType として Directory / DirectoryRole / Group しか明示されておらず、AdministrativeUnit は登場しません。

そのため、この AU スコープ指定は「動作はするが将来変更される可能性がある」程度の扱いと考え、あくまで検証やトラブルシュート用途に留めるのが安全です。最大期間を判定するロジック自体は、ディレクトリ全体スコープのポリシーだけを頼りに構成するのがおすすめです。

ISO 8601 期間表記（maximumDuration）の読み方

maximumDuration は ISO 8601 形式の期間で返されます。PIM に限らず、Azure / Microsoft 365 まわりではよく出てくる形式なので、ここで一度整理しておきます。

文字列意味典型的な用途
P180D180 日管理者によるアクティブ割り当ての最大期間など
P365D365 日有資格割り当てを 1 年間許可するケース
PT8H8 時間エンドユーザーのアクティベーションセッション時間
PT1H1 時間より厳しめのセッション最大時間など

PowerShell で TimeSpan に変換する

PowerShell では、.NET の System.Xml.XmlConvert クラスを使うと簡単に TimeSpan に変換できます。

# ISO 8601 期間 → TimeSpan
[TimeSpan]$ts180d = [System.Xml.XmlConvert]::ToTimeSpan('P180D')
[TimeSpan]$ts8h   = [System.Xml.XmlConvert]::ToTimeSpan('PT8H')

$ts180d.TotalDays   # 180
$ts8h.TotalHours    # 8

逆に TimeSpan から ISO 8601 形式の文字列を得たい場合は、ToString() ではなく XmlConvert.ToString() を使う必要がある点にも注意してください。

# TimeSpan → ISO 8601 期間文字列
$ts = [TimeSpan]::FromDays(90)
[System.Xml.XmlConvert]::ToString($ts)   # 例: P90D

最大期間の意味を整理する：eligible と active と activation

PIM の UI 上は「有資格」「アクティブ」「アクティベーション」など似た用語が並ぶため、どの maximumDuration が何を意味しているのか混乱しがちです。Microsoft のマッピングガイドとルール一覧を基に、分かりやすく整理してみます。

観点状態主なルール ID何の最大期間か
ロール付与そのもの有資格（eligible）Expiration_Admin_Eligibility「このユーザーをいつまで eligible としておくか」の上限
ロール付与そのものアクティブ（active）Expiration_Admin_Assignment管理者がロールを直接割り当てたときの最大期間
セッションアクティベーション（有効化）Expiration_EndUser_Assignmentユーザーが PIM から「今だけ有効化」したときのセッション時間（例：8 時間）

実装でよくある落とし穴は、次のようなものです。

  • 「ロールを何日間 eligible にできるか知りたい」のに Expiration_EndUser_Assignment を見てしまう
    ⇒ それはセッションの最大時間なので、通常は Expiration_Admin_Eligibility のほうを参照すべきです。
  • 「管理者が直接ロールを付与した時だけ特別に長くしたい」ケース
    ⇒ Expiration_Admin_Assignment の maximumDuration と isExpirationRequired を調整します。

いずれにしても、AU スコープかどうかでこれらのルールが変わることはありません。ロールに紐づくポリシーの内容こそが、すべてのスコープ（テナント全体・特定 AU）に効いてきます。

必要な Graph 権限と最小権限の設計

roleManagementPolicyAssignments や roleManagementPolicies、rules を読むには、いくつかの高権限な Graph 権限が必要です。Microsoft Graph のリファレンスでは、PIM for Microsoft Entra roles 向けに次のような権限が挙げられています。

用途代表的な権限（Delegated / Application）備考
PIM ポリシーのルール取得
（/policies/roleManagementPolicies/{id}/rules）		RoleManagementPolicy.Read.Directory
RoleManagement.Read.Directory		読み取り専用。最小権限としてまず検討。
ポリシー割り当て取得
（/policies/roleManagementPolicyAssignments）		RoleManagementPolicy.Read.Directory
RoleManagement.Read.Directory		アサインメントの詳細（ポリシーとの関連）を取得。
より広い RBAC 設定の読み取りRoleManagement.Read.Allすべての RBAC プロバイダーに対するロール関連情報を取得。

古い資料やコミュニティ記事では Policy.Read.All を利用している例もありますが、現在の公式リファレンスでは PIM 用としては RoleManagementPolicy.Read.Directory 系を利用するのが標準的です。

アプリケーション権限（app-only）を使う場合は、これらに対して管理者同意を付与することになるため、特に「どのアプリにどの権限を与えているか」の棚卸しを定期的に行うと安全です。

実務でよくあるつまずきポイント

最後に、PIM ポリシーと roleManagementPolicyAssignments を扱う際によくハマるポイントをいくつか挙げておきます。

v1.0 と /beta の混在

  • サンプルコードやブログ記事の多くが /beta を使っているため、そのまま真似すると「本番で /beta を叩いていた」状態になりがちです。
  • 現在は PIM for Microsoft Entra roles / Groups の API の多くが v1.0 で提供されています。
  • 新機能の検証や一部のプレビュー機能を除き、本番スクリプトは v1.0 で統一するのがおすすめです。

「最大期間の意味」を取り違える

  • Expiration_EndUser_Assignment は「セッション最大時間」であり、「eligible 期間」ではない点に注意。
  • 「有資格にしておける最大期間」は Expiration_Admin_Eligibility を見る必要があります。
  • UI 上もラベルが似ているため、実際にルール一覧を取得して caller と level を確認するのが一番確実です。

AU ごとのポリシーがあると勘違いする

  • 「AU 単位で別の PIM ロール設定を持てるのでは？」と想像したくなりますが、現時点の PIM ポリシーモデルは「ロール単位」での定義が基本です。
  • AU はあくまで「どこまで管理を委任するか」というスコープ的な概念であり、ロール自体のポリシーを分岐させる仕組みではありません。

サンプル PowerShell：対象ロールの eligible 最大期間を取得する

ここまでの話をまとめて、「対象ロールの有資格割り当ての最大期間（Expiration_Admin_Eligibility.maximumDuration）を取得する」サンプルを示します。

# 必要なモジュールを読み込み
Import-Module Microsoft.Graph.Identity.Directory
Import-Module Microsoft.Graph.Identity.SignIns

# PIM ポリシーとロール定義を読むための権限で接続
Connect-MgGraph -Scopes @(
    'RoleManagementPolicy.Read.Directory',
    'RoleManagement.Read.Directory'
)

# 対象ロール名（例：グローバル管理者）
$roleDisplayName = 'Global Administrator'

# 1. roleDefinitionId を取得
$role = Get-MgRoleManagementDirectoryRoleDefinition `
            -Filter "displayName eq '$roleDisplayName'"
if (-not $role) {
    throw "Role '$roleDisplayName' が見つかりませんでした。"
}
$roleDefinitionId = $role.Id

# 2. ディレクトリ全体スコープのポリシー割り当てを取得
$assignment = Get-MgPolicyRoleManagementPolicyAssignment `
    -Filter "scopeId eq '/' and scopeType eq 'Directory' and roleDefinitionId eq '$roleDefinitionId'" `
    -ExpandProperty "policy(`$expand=rules)"

if (-not $assignment) {
    throw "roleManagementPolicyAssignment が見つかりませんでした。"
}

$rules = $assignment.Policy.Rules

# 3. 有資格の最大期間（Expiration_Admin_Eligibility）を取得
$eligRule = $rules | Where-Object {
    $_.'@odata.type' -like '*unifiedRoleManagementPolicyExpirationRule' -and
    $_.Id -eq 'Expiration_Admin_Eligibility'
}

if (-not $eligRule) {
    throw "Expiration_Admin_Eligibility ルールが見つかりませんでした。"
}

$maxDurationString = $eligRule.maximumDuration
$maxDuration = [System.Xml.XmlConvert]::ToTimeSpan($maxDurationString)

Write-Host "Role: $roleDisplayName"
Write-Host "Eligible 最大期間 (文字列): $maxDurationString"
Write-Host "Eligible 最大期間 (日):      $($maxDuration.TotalDays) 日"

このスクリプトは AU を一切意識していませんが、AU スコープのロールにも同じ設定が適用されるため、要件を満たすことができます。

まとめ

  • PIM のロール設定は unifiedRoleManagementPolicy とその配下の 17 個のルールで構成されており、最大期間は Expiration 系ルールの maximumDuration で決まります。
  • AU スコープかどうかにかかわらず、ロール設定はロール単位で共通です。ディレクトリ全体スコープのポリシーを見れば十分であり、AU ごとに別の最大期間が設定されることはありません。
  • 有資格期間・アクティブ期間・アクティベーションセッションの 3 つを区別し、それぞれに対応するルール ID（Expiration_Admin_Eligibility / Expiration_Admin_Assignment / Expiration_EndUser_Assignment）を正しく参照することが重要です。
  • スクリプトから最大期間を取得する場合は、scopeId = '/', scopeType = 'Directory' で roleManagementPolicyAssignments を取得し、展開された policy.rules から目的の Expiration ルールの maximumDuration を読む、というパターンを押さえておけば AU を意識せず安全に実装できます。
Azure
PowerShell Azure AD Microsoft Graph Entra ID PIM

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次