使用 PowerShell 為具有單一角色的應用程式，在權利管理中建立存取套件

發行項
04/10/2024

在 Microsoft Entra 權利管理中，存取套件包含使用者如何取得一或多個資源角色指派的原則。這些資源可以包含群組、應用程式和 SharePoint Online 網站。

本文說明如何使用 Microsoft Graph PowerShell，為具有單一角色的單一應用程式建立存取套件。此案例主要適用於使用權利管理將特定商務或中間件應用程式持續存取自動化的環境。具有多個資源或具有多個角色資源的組織，也可以使用存取套件來建立其存取原則的模型：

如果組織已經有其商務角色的現有組織角色模型，他們可以將該模型移轉至 Microsoft Entra ID 控管，並使用組織角色模型控管存取權。
如果組織具有多個角色的應用程式，他們可以部署組織原則，以控管與 Microsoft Entra ID 整合之應用程式的存取權
如需建立其他案例存取套件的詳細資訊，請參閱教學課程：管理權利管理中的資源存取，以及如何在權利管理中建立存取套件。

必要條件

使用此功能需要 Microsoft Entra ID 控管授權。若要尋找您需求的正確授權，請參閱 Microsoft Entra ID 控管授權基本概念。

開始建立存取套件之前，您必須先整合應用程式與 Microsoft Entra ID。如果您的應用程式尚未存在於 Microsoft Entra ID 租使用者中，請遵循該文章中的指示來建立物件的應用程式和服務主體。此外，請確定您的 Microsoft Entra ID 租使用者已符合必要條件，再設定 Microsoft Entra ID 以進行身分識別控管。

若要建立存取套件及其相關聯的原則和指派，您必須備妥下列資訊：

使用案例	組態設定	PowerShell 變數
全部	Microsoft Entra ID 租使用者中的應用程式名稱	`$servicePrincipalName`
全部	應用程式角色的名稱	`$servicePrincipalRoleName`
全部	包含存取套件的目錄名稱	`$catalogName`
全部	要授與存取套件的名稱	`$accessPackageName`
全部	提供存取套件的描述	`$accessPackageDescription`
使用不相容存取套件區分職責需求	不相容存取套件的標識碼	`$incompatibleAccessPackageId` （如有需要）
尚未指派且不會自動指派的使用者	用戶清單	`$inputpath` （如有需要）
具有特定屬性的用戶會自動擁有指派	範圍中用戶的查詢表達式	`$autoAssignmentPolicyFilter` （如有需要）
允許沒有指派的使用者要求指派	可以要求的用戶範圍、核准者和存取權檢閱期間	視需求而定
根據加入或離開生命週期工作流程中的工作流程，自動建立或移除指派	提供和移除存取權的工作流程名稱	視需求而定

向 Microsoft Entra 識別碼進行驗證

本節說明如何使用 Microsoft Graph PowerShell Cmdlet 與 Microsoft Entra ID 控管互動。

貴組織第一次針對此案例使用這些 Cmdlet 時，您必須具有全域管理員 istrator 角色，才能在租使用者中使用 Microsoft Graph PowerShell。後續的互動可以使用較低許可權的角色，例如：

Identity Governance 管理員 istrator。

開啟 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 識別碼：

$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

查閱目錄的識別碼。

$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"
```

查閱應用程式服務主體的標識碼。

$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

擷取該目錄中資源的標識碼和範圍。

$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 將存取套件設定為不相容。

指定另一個與這個存取套件不相容的存取套件。將的值 incompatibleAccessPackageId 變更為 Microsoft Entra 權利管理中另一個存取套件的識別碼。
```
$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 Cmdlet 將其他使用者新增至應用程式。如果您沒有任何需要存取權的使用者，且不會自動收到，請繼續進行下一節。

此腳本假設您有一個包含一個數據行的輸入 CSV 檔案， UserPrincipalName可透過其直接指派原則將這些使用者指派給存取套件。

指定輸入檔的名稱。
```
$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"
   }
}

將原則新增至存取套件以進行自動指派

如果貴組織可獲指派應用程式存取權的原則包含根據使用者屬性的規則，根據使用者的屬性自動指派和移除存取權，您可以使用自動指派原則來表示。存取套件最多可以有一個自動指派原則。如果您沒有自動指派的需求，請繼續進行下一節。

指定使用者接收指派的自動指派篩選表達式。將的值 autoAssignmentPolicyFilter 變更為範圍中 Microsoft Entra 識別碼中用戶的篩選。 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 使用者的標識碼。

$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	參數
要求使用者存取套件指派	`c1ec1e76-f374-4375-aaa6-0bb6bd4c60be`	name： `assignmentPolicyId` value：指派原則標識符，例如 `$directAssignmentPolicyId` ，如果您想要指派使用者的存取套件，則不需要核准的值。 name： `accessPackageId` value：您要指派給使用者之存取套件的存取套件識別碼 `$accessPackageId`。

使用 New-MgIdentityGovernanceLifecycleWorkflowNewVersion 命令建立新的工作流程版本，包括新工作。
leaver使用 Get-MgIdentityGovernanceLifecycleWorkflow 命令擷取類別工作流程及其工作。

將工作新增至該工作流程中的工作清單。

工作顯示名稱	taskDefinitionId	參數
拿掉使用者的存取套件指派	`4a0b64f2-c7ec-46ba-b117-18f262946c50`	name： `accessPackageId` value：您想要從使用者取消指派之存取套件的有效存取套件識別碼 `accessPackageId` 。

使用 New-MgIdentityGovernanceLifecycleWorkflowNewVersion 命令建立新的工作流程版本，包括新工作。

管理指派

建立存取套件、原則和初始指派之後，使用者就會獲指派應用程式角色的存取權。

稍後，您可以監視指派的變更，或以程序設計方式新增或移除指派。

擷取現有的指派

此腳本說明如何使用篩選來擷取狀態之存取套件 Delivered的指派。腳本會產生 CSV 檔案 assignments.csv ，其中包含具有指派的使用者清單，每個指派各有一個數據列。

$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"

移除指派

您可以使用 Cmdlet 移除使用者的指派 New-MgEntitlementManagementAssignmentRequest 。

$userId = "040a792f-4c5f-4395-902f-f0d9d192ab2c"
$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
}

Share via