PowerShell を使用して 1 つのロールを持つアプリケーションのエンタイトルメント管理でアクセス パッケージを作成する
Microsoft Entra エンタイトルメント管理では、アクセス パッケージには、ユーザーが 1 つ以上のリソース ロールの割り当てを取得する方法に関するポリシーが含まれています。 リソースには、グループ、アプリケーション、SharePoint Online サイトを含められます。
この記事では、Microsoft Graph PowerShell を使用して、1 つのロールを持つ 1 つのアプリケーションのアクセス パッケージを作成する方法について説明します。 このシナリオは、特定のビジネスまたはミドルウェア アプリケーションの継続的なアクセスを自動化するためにエンタイトルメント管理を使用している環境に主に適用されます。 複数のリソースまたは複数のロールを持つリソースを持つ組織は、アクセス パッケージを使用してアクセス ポリシーをモデル化することもできます。
- 組織にビジネス ロールの既存の組織ロール モデルが既にある場合は、そのモデルを Azure Active Directory Identity Governance に移行し、組織のロール モデルを使用してアクセスを管理できます。
- 組織に複数のロールを持つアプリケーションがある場合は、Microsoft Entra ID と統合されたアプリケーションへのアクセスを管理するための組織ポリシーを展開できます
- 他のシナリオでのアクセス パッケージの作成の詳細については、「チュートリアル - エンタイトルメント管理でリソースへのアクセスを管理する」および「エンタイトルメント管理でアクセス パッケージを作成する」方法を参照してください。
前提条件
この機能を使用するには、Microsoft Entra ID Governance または Microsoft Entra スイートのライセンスが必要です。 要件に適したライセンスを見つけるには、「Microsoft Entra ID ガバナンス ライセンスの基礎」をご覧ください。
アクセス パッケージの作成を開始する前に、アプリケーションを Microsoft Entra ID と統合する必要があります。 アプリケーションが Microsoft Entra ID テナントにまだ存在しない場合は、その記事の手順に従って、オブジェクトのアプリケーションとサービス プリンシパルを作成します。 また、ID ガバナンスのために Microsoft Entra ID を構成する前に、Microsoft Entra ID テナントが前提条件を満たしていることを確認します。
アクセス パッケージとそれに関連付けられているポリシーと割り当てを作成するには、次の情報を準備しておく必要があります。
ユース ケース | 構成設定 | PowerShell 変数 |
---|---|---|
すべて | Microsoft Entra ID テナント内のアプリケーションの名前 | $servicePrincipalName |
すべて | アプリケーションのロールの名前 | $servicePrincipalRoleName |
すべて | アクセス パッケージを含むカタログの名前 | $catalogName |
すべて | アクセス パッケージを指定する名前 | $accessPackageName |
すべて | アクセス パッケージを指定する説明 | $accessPackageDescription |
互換性のないアクセス パッケージを使用した職務要件の分離 | 互換性のないアクセス パッケージの ID | $incompatibleAccessPackageId (必要な場合) |
割り当てがまだなく、自動的に割り当てられないユーザー | ユーザーの一覧 | $inputpath (必要な場合) |
特定の属性を持つユーザーは自動的に割り当てを持つ | スコープ内のユーザーのクエリ式 | $autoAssignmentPolicyFilter (必要な場合) |
割り当てを持っていないユーザーに割り当てを要求することを許可する | 要求できるユーザーのスコープ、承認者、およびアクセス レビュー期間 | 要件によって異なる |
ライフサイクル ワークフローの参加ワークフローまたは脱退ワークフローに基づいて、割り当ての作成または削除を自動化する | アクセス権を付与および削除するワークフローの名前 | 要件によって異なる |
Microsoft Entra ID に対して認証する
このセクションでは、Microsoft Graph PowerShell コマンドレットを使用して Azure Active Directory Identity Governance を操作する方法を示します。
このシナリオのために組織でこれらのコマンドレットを初めて使用する場合は、テナントで Microsoft Graph PowerShell を使用できるように、グローバル管理者ロールである必要があります。 以降の操作では、次のような低い特権のロールを使用できます。
PowerShell を開きます。
Microsoft Graph PowerShell モジュールがまだインストールされていない場合は、次のコマンドを使用して
Microsoft.Graph.Identity.Governance
モジュールなどをインストールします。Install-Module Microsoft.Graph
これらのモジュールが既にインストールされている場合は、最新バージョンを使用していることを確認します。
Update-Module microsoft.graph.users,microsoft.graph.identity.governance,microsoft.graph.applications
Microsoft Entra ID に接続します。
$msg = Connect-MgGraph -ContextScope Process -Scopes "User.ReadWrite.All,Application.ReadWrite.All,AppRoleAssignment.ReadWrite.All,EntitlementManagement.ReadWrite.All"
このコマンドを初めて使用する場合は、Microsoft Graph コマンド ライン ツールにこれらのアクセス許可を付与することを許可する必要があります。
Microsoft Entra エンタイトルメント管理でカタログを作成する
既定では、管理者が最初にエンタイトルメント管理を操作すると、既定のカタログが自動的に作成されます。 ただし、管理対象アプリケーションのアクセス パッケージは、指定されたカタログに含まれている必要があります。
カタログの名前を指定します。
$catalogName = "Business applications"
アプリケーション ガバナンス シナリオのカタログが既にある場合は、このセクションの手順 4 に進みます。
アプリケーション ガバナンス シナリオ用のカタログがまだない場合は、カタログを作成します。
$catalog = New-MgEntitlementManagementCatalog -DisplayName $catalogName
カタログの ID を検索します。
$catalogFilter = "displayName eq '" + $catalogName + "'" $catalog = Get-MgEntitlementManagementCatalog -Filter $catalogFilter -All -expandProperty resources,accessPackages if ($catalog -eq $null) { throw "catalog $catalogName not found" } $catalogId = $catalog.Id
アプリケーションをリソースとしてカタログに追加する
カタログが作成されたら、そのカタログにリソースとしてアプリケーションを追加します。
アプリケーションの名前とアプリケーション ロールの名前を指定します。 アプリケーションの名前を
servicePrincipalName
の値として使用します。$servicePrincipalName = "SAP Cloud Identity Services" $servicePrincipalRoleName = "User"
アプリケーション サービス プリンシパルの ID を検索します。
$servicePrincipalFilter = "displayName eq '" + $applicationName + "'" $servicePrincipal = Get-MgServicePrincipal -Filter $servicePrincipalFilter -all if ($servicePrincipal -eq $null) { throw "service principal $servicePrincipalName not found" } $servicePrincipalId = $servicePrincipal.Id
アプリケーションがリソースとしてカタログに既に存在するかどうかを確認します。 既に存在する場合は、このセクションの手順 6 に進みます。
$resourceId = $null foreach ($r in $catalog.Resources) { if ($r.OriginId -eq $servicePrincipalId) { $resourceId = $r.id; break } } if ($resourceId -ne $null) { write-output "resource already in catalog" } else {write-output "resource not yet in catalog"}
アプリケーションのサービス プリンシパルをリソースとしてカタログに追加します。
$resourceAddParams = @{ requestType = "adminAdd" resource = @{ originId = $servicePrincipalId originSystem = "AadApplication" } catalog = @{ id = $catalogId } } $resourceAdd = New-MgEntitlementManagementResourceRequest -BodyParameter $resourceAddParams if ($resourceAdd -eq $null) { throw "resource could not be added" } sleep 5
そのカタログ内のリソースの ID とスコープを取得します。
$resource = $null $resourceId = $null $resourceScope = $null $catalogResources = Get-MgEntitlementManagementCatalogResource -AccessPackageCatalogId $CatalogId -ExpandProperty "scopes" -all foreach ($r in $catalogResources) { if ($r.OriginId -eq $servicePrincipalId) { $resource = $r; $resourceId = $r.id; $resourceScope = $r.Scopes[0]; break } } if ($resourceId -eq $null) { throw "resource was not added" }
アプリケーションのロールを取得します。
$resourceRoleFilter = "(originSystem eq 'AadApplication' and resource/id eq '" + $resourceId + "')" $resourceRoles = @(get-mgentitlementmanagementcatalogresourcerole -AccessPackageCatalogId $catalogId -Filter $resourceRoleFilter -All -ExpandProperty "resource") if ($resourceRoles -eq $null -or $resourceRoles.count -eq 0) { throw "no roles available" }
アクセス パッケージに含まれるロールを選択します。
$resourceRole = $null foreach ($r in $resourceRoles) { if ($r.DisplayName -eq $servicePrincipalRoleName) { $resourceRole = $r; break; } } if ($resourceRole -eq $null) { throw "role $servicePrincipalRoleName not located" }
アプリケーションのアクセス パッケージを作成する
次に、PowerShell を使用して、アプリケーションのロールを含むアクセス パッケージをカタログに作成します。
アクセス パッケージの名前と説明を指定します。
$accessPackageName = "SAP Cloud Identity Services" $accessPackageDescription = "A user of SAP Cloud Identity Services" $accessPackageHidden = $true
アクセス パッケージがまだ存在していないことを確認します。
foreach ($a in $catalog.AccessPackages) { if ($a.DisplayName -eq $accessPackageName) { throw "access package $accessPackageName already exists" } }
アクセス パッケージを作成します。
$accessPackageParams = @{ displayName = $accessPackageName description = $accessPackageDescription isHidden = $accessPackageHidden catalog = @{ id = $catalog.id } } $accessPackage = New-MgEntitlementManagementAccessPackage -BodyParameter $accessPackageParams $accessPackageId = $accessPackage.Id
アクセス パッケージにアプリケーション ロールを追加する
アクセス パッケージを作成したら、カタログ内のリソースのロールをアクセス パッケージにリンクします。
$rrsParams = @{
role = @{
id = $resourceRole.Id
displayName = $resourceRole.DisplayName
description = $resourceRole.Description
originSystem = $resourceRole.OriginSystem
originId = $resourceRole.OriginId
resource = @{
id = $resource.Id
originId = $resource.OriginId
originSystem = $resource.OriginSystem
}
}
scope = @{
id = $resourceScope.Id
originId = $resourceScope.OriginId
originSystem = $resourceScope.OriginSystem
}
}
$roleAddRes = New-MgEntitlementManagementAccessPackageResourceRoleScope -AccessPackageId $accessPackageId -BodyParameter $rrsParams
直接割り当て用のアクセス パッケージ割り当てポリシーを作成する
このセクションでは、まずアクセス パッケージにアクセス パッケージ割り当てポリシー (直接割り当て用のアクセス パッケージ割り当てポリシー) を作成します。これは、アプリケーションに既にアクセスできるユーザーを追跡するために使用できます。 このセクションで作成したポリシーの例では、管理者またはアクセス パッケージの割り当てマネージャーのみがアクセス権を割り当てることができ、ユーザーは無期限にアクセスを保持し、承認やアクセス レビューはありません。
ポリシーを作成します。
$policy1Name = "Direct assignment policy" $policy1Description = "policy for administrative assignment" $policy1params = @{ displayName = $policy1Name description = $policy1Description allowedTargetScope = "notSpecified" specificAllowedTargets = @( ) expiration = @{ endDateTime = $null duration = $null type = "noExpiration" } requestorSettings = @{ enableTargetsToSelfAddAccess = $true enableTargetsToSelfUpdateAccess = $false enableTargetsToSelfRemoveAccess = $true allowCustomAssignmentSchedule = $true enableOnBehalfRequestorsToAddAccess = $false enableOnBehalfRequestorsToUpdateAccess = $false enableOnBehalfRequestorsToRemoveAccess = $false onBehalfRequestors = @( ) } requestApprovalSettings = @{ isApprovalRequiredForAdd = $false isApprovalRequiredForUpdate = $false stages = @( ) } accessPackage = @{ id = $accessPackageId } } $policy1Res = New-MgEntitlementManagementAssignmentPolicy -BodyParameter $policy1params $directAssignmentPolicyId = $policy1Res.Id
職務制約の分離を構成する
Microsoft Entra エンタイトルメント管理では、職務の分離チェックを適用して、別の指定されたアクセス パッケージまたは指定されたグループのメンバーシップへの既存の割り当てを既に持っているユーザーが、アクセス パッケージを要求することを防止できます。
このアプリケーションの職務要件を分離していない場合は、次のセクションに進みます。
職務の分離要件がある場合は、互換性のないアクセス パッケージまたは既存のグループをアクセス パッケージ用に構成します。
別のアクセス パッケージと互換性なしとしてマークされるアクセス パッケージごとに、PowerShell を使用してアクセス パッケージを互換性なしとして構成できます。
このアクセス パッケージと互換性のない他のアクセス パッケージを指定します。 Microsoft Entra エンタイトルメント管理の別のアクセス パッケージの ID に
incompatibleAccessPackageId
の値を変更します。$incompatibleAccessPackageId = "67cc7175-7a3d-4cb2-860f-4d9217ba96ca"
このアクセス パッケージに互換性のない参照を作成します。
$incompatible1params = @{ "@odata.id" = "https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/accessPackages/" + $incompatibleAccessPackageId } New-MgEntitlementManagementAccessPackageIncompatibleAccessPackageByRef -AccessPackageId $accessPackageId -BodyParameter $incompatible1params
他のアクセス パッケージに互換性のない参照を作成します。
$incompatible2params = @{ "@odata.id" = "https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/accessPackages/" + $accessPackageId } New-MgEntitlementManagementAccessPackageIncompatibleAccessPackageByRef -AccessPackageId $incompatibleAccessPackageId -BodyParameter $incompatible2params
他のアクセス パッケージに対して繰り返します。
シナリオで職務の分離チェックをオーバーライドする機能が必要な場合は、それらのオーバーライド シナリオ用に追加のアクセス パッケージを設定することもできます。
アプリケーションに既にアクセス許可を持っている既存のユーザーの割り当てを追加する
アプリケーションに既にアクセスできる既存のユーザーの割り当てを、アクセス パッケージとその直接割り当てポリシーに追加します。 アクセス パッケージに各ユーザーを直接割り当てることができます。
既存のアプリケーション ロールの割り当てを取得します。
$existingAppRoleAssignments = @(Get-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $servicePrincipalId -All)
重複する割り当てを作成しないようにするには、アクセス パッケージへの既存の割り当てを取得します。
$existingAssignments1filter = "accessPackage/id eq '" + $accessPackageId + "' and state eq 'Delivered'" $existingassignments1 = @(Get-MgEntitlementManagementAssignment -Filter $existingAssignments1filter -ExpandProperty target -All -ErrorAction Stop) $existingusers1 = @() foreach ($a in $existingassignments1) { $existingusers1 += $a.Target.ObjectId}
新しい割り当てを作成します。
foreach ($ar in $existingAppRoleAssignments) { if ($ar.principalType -ne "User") { write-warning "non-user assigned to application role" } $arpid = $ar.principalId if ($existingusers1.contains($arpId)) { continue } $params = @{ requestType = "adminAdd" assignment = @{ targetId = $arpId assignmentPolicyId = $directAssignmentPolicyId accessPackageId = $accessPackageId } } try { New-MgEntitlementManagementAssignmentRequest -BodyParameter $params } catch { write-error "cannot create request for user $upn" } }
アプリケーションへのアクセス許可を持つ必要がある追加ユーザーの割り当てを追加する
このスクリプトは、Microsoft Graph PowerShell コマンドレットを使用して、アプリケーションにアクセスできるように、追加ユーザーの割り当てを追加する方法を示しています。 アクセス許可が必要で、アクセス許可を自動的には受けないユーザーがいない場合は、次のセクションに進みます。
このスクリプトでは、直接割り当てポリシーを使用してアクセス パッケージにユーザーを割り当てるために、1 つの列 (UserPrincipalName
) を含む入力 CSV ファイルがあることを前提としています。
入力ファイルの名前を指定します。
$inputpath = "users.csv"
重複する割り当てを作成しないようにするには、アクセス パッケージへの既存の割り当てを取得します。
$existingAssignments2filter = "accessPackage/id eq '" + $accessPackageId + "' and state eq 'Delivered'" $existingassignments2 = @(Get-MgEntitlementManagementAssignment -Filter $existingAssignments2filter -ExpandProperty target -All -ErrorAction Stop) $existingusers2 = @() foreach ($a in $existingassignments2) { $existingusers2 += $a.Target.ObjectId}
新しい割り当てを作成します。
$users = import-csv -Path $inputpath foreach ($userrecord in $users) { $upn = $userrecord.UserPrincipalName if ($null -eq $upn) {throw "no UserPrincipalName" } $u = $null try { $u = Get-MgUser -UserId $upn } catch { write-error "no user $upn" } if ($u -eq $null) { continue } if ($existingusers2.contains($u.Id)) { continue } $params = @{ requestType = "adminAdd" assignment = @{ targetId = $u.Id assignmentPolicyId = $directAssignmentPolicyId accessPackageId = $accessPackageId } } try { New-MgEntitlementManagementAssignmentRequest -BodyParameter $params } catch { write-error "cannot create request for user $upn" } }
自動割り当てのアクセス パッケージにポリシーを追加する
アプリケーションへのアクセス許可を割り当てられるユーザーに対する組織のポリシーに、ユーザーの属性に基づいて自動的にアクセスを割り当てる、または削除する属性に基づくルールが含まれている場合は、自動割り当てポリシーを使用してこれを表せます。 アクセス パッケージには、最大 1 つの自動割り当てポリシーを含めることができます。 自動割り当ての要件がない場合は、次のセクションに進みます。
ユーザーが割り当てを受け取る自動割り当てフィルター式を指定します。 スコープ内の Microsoft Entra ID のユーザーのフィルターにする
autoAssignmentPolicyFilter
の値を変更します。 構文と許可される属性は、Microsoft Entra ID の動的メンバーシップ グループのルールで指定されます。$autoAssignmentPolicyFilter = '(user.city -eq "Redmond")'
PowerShell を使用して、アクセス パッケージに自動割り当てポリシーを作成します。
$policy2Name = "Automatic assignment policy" $policy2Description = "policy for automatic assignment" $policy2Params = @{ DisplayName = $policy2Name Description = $policy2Description AllowedTargetScope = "specificDirectoryUsers" SpecificAllowedTargets = @( @{ "@odata.type" = "#microsoft.graph.attributeRuleMembers" description = $policy2Description membershipRule = $autoAssignmentPolicyFilter } ) AutomaticRequestSettings = @{ RequestAccessForAllowedTargets = $true } AccessPackage = @{ Id = $accessPackageId } } New-MgEntitlementManagementAssignmentPolicy -BodyParameter $policy2Params
ユーザーがアクセスを要求できるようにする追加のポリシーを作成する
まだアクセス権を持っていないユーザーがアプリケーションへの割り当てを要求できる場合は、アクセス パッケージの割り当てポリシーを構成して、ユーザーがアクセス パッケージを要求できるようにすることもできます。 アクセス パッケージに追加のポリシーを追加し、各ポリシーで、要求できるユーザーと承認する必要があるユーザーを指定できます。 ユーザーにアクセス権を自動的にのみ割り当てる、または管理者が割り当てるようにする場合は、次のセクションに進みます。
その他の例については、PowerShell を使用した割り当てポリシーの作成、accessPackageAssignmentPolicy、assignmentPolicy の作成に関する記事を参照してください。
承認者になる Microsoft Entra ユーザーの名前、ポリシーの説明、ID を指定します。
$policy3Name = "example policy" $policy3Description = "example of a policy for users to request assignment" $policy3ApproverSingleUserId = "1aaaaaa1-2bb2-3cc3-4dd4-5eeeeeeeeee5"
ポリシーを作成します。
$policy3Params = @{ displayName = $policy3Name description = $policy3Description allowedTargetScope = "allMemberUsers" expiration = @{ type = "noExpiration" } requestorSettings = @{ enableTargetsToSelfAddAccess = "true" enableTargetsToSelfUpdateAccess = "true" enableTargetsToSelfRemoveAccess = "true" } requestApprovalSettings = @{ isApprovalRequiredForAdd = "true" isApprovalRequiredForUpdate = "true" stages = @( @{ durationBeforeAutomaticDenial = "P7D" isApproverJustificationRequired = "false" isEscalationEnabled = "false" fallbackPrimaryApprovers = @( ) escalationApprovers = @( ) fallbackEscalationApprovers = @( ) primaryApprovers = @( @{ "@odata.type" = "#microsoft.graph.singleUser" userId = $policy3ApproverSingleUserId } ) } ) } accessPackage = @{ id = $accessPackageId } } New-MgEntitlementManagementAssignmentPolicy -BodyParameter $policy3Params
ライフサイクル ワークフロー タスクを構成する
従業員参加、休暇イベントの移動に Microsoft Entra ライフサイクル ワークフローを使用する場合は、これらのワークフローにタスクを追加して、このアクセス パッケージへの割り当てを追加または削除することもできます。 ライフサイクル ワークフローを使用しない場合は、次のセクションに進みます。
この例では、参加と脱退のイベント ワークフローに変更を加える方法を示します。
joiner
カテゴリ ワークフローとそのタスクを、Get-MgIdentityGovernanceLifecycleWorkflow コマンドを使用して取得します。そのワークフロー内のタスクの一覧にタスクを追加します。
タスクの表示名 taskDefinitionId arguments ユーザー アクセス パッケージの割り当てを要求する c1ec1e76-f374-4375-aaa6-0bb6bd4c60be
name: assignmentPolicyId
値: ユーザーを割り当てるアクセス パッケージに対して承認が必要ない場合の$directAssignmentPolicyId
からの値などの割り当てポリシー ID。
name:accessPackageId
値: ユーザーに割り当てるアクセス パッケージのアクセス パッケージ ID$accessPackageId
。新しいタスクを含むワークフローの新しいバージョンを、New-MgIdentityGovernanceLifecycleWorkflowNewVersion コマンドを使用して作成します。
leaver
カテゴリ ワークフローとそのタスクを、Get-MgIdentityGovernanceLifecycleWorkflow コマンドを使用して取得します。そのワークフロー内のタスクの一覧にタスクを追加します。
タスクの表示名 taskDefinitionId arguments ユーザーのアクセス パッケージの割り当てを削除する 4a0b64f2-c7ec-46ba-b117-18f262946c50
name: accessPackageId
値: ユーザーからの割り当てを解除するアクセス パッケージの有効なアクセス パッケージ IDaccessPackageId
。新しいタスクを含むワークフローの新しいバージョンを、New-MgIdentityGovernanceLifecycleWorkflowNewVersion コマンドを使用して作成します。
割り当ての管理
アクセス パッケージ、ポリシー、および初期割り当てが作成されると、ユーザーにはアプリケーションのロールへのアクセス権が割り当てられます。
後で、割り当ての変更を監視し、プログラムで割り当てを追加または削除できます。
既存の割り当てを取得する
このスクリプトは、フィルターを使用して、状態 Delivered
のアクセス パッケージへの割り当てを取得する方法を示しています。 このスクリプトは、割り当てがあるユーザーの一覧を含む CSV ファイル assignments.csv
を生成し、割り当てごとに 1 行を生成します。
$assignmentFilter = "accessPackage/id eq '" + $accessPackageId + "' and state eq 'Delivered'"
$assignments = @(Get-MgEntitlementManagementAssignment -Filter $assignmentFilter -ExpandProperty target -All -ErrorAction Stop)
$sp = $assignments | select-object -Property Id,{$_.Target.id},{$_.Target.ObjectId},{$_.Target.DisplayName},{$_.Target.PrincipalName}
$sp | Export-Csv -Encoding UTF8 -NoTypeInformation -Path ".\assignments.csv"
割り当ての削除
New-MgEntitlementManagementAssignmentRequest
コマンドレットを使用して、ユーザーの割り当てを削除できます。
$userId = "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
$filter = "accessPackage/Id eq '" + $accessPackageId + "' and state eq 'Delivered' and target/objectId eq '" + $userId + "'"
$assignment = Get-MgEntitlementManagementAssignment -Filter $filter -ExpandProperty target -all -ErrorAction stop
if ($assignment -ne $null) {
$params = @{
requestType = "adminRemove"
assignment = @{ id = $assignment.id }
}
New-MgEntitlementManagementAssignmentRequest -BodyParameter $params
}