使用 PowerShell 為具有單一角色的應用程式,在權利管理中建立存取套件
在 Microsoft Entra 權利管理中,存取套件包含使用者如何取得一或多個資源角色指派的原則。 這些資源可以包含群組、應用程式和 SharePoint Online 網站。
本文說明如何使用 Microsoft Graph PowerShell,為具有單一角色的單一應用程式建立存取套件。 此案例主要適用於使用權利管理,將特定商務或中介軟體應用程式持續存取自動化的環境。 您可以基於本篇及其他文章中的指引來應用這些方法,以應對更複雜的情境,例如跨多個應用程式的存取,或跨應用程式及其他資源的存取。 具有多個資源或具有多個角色資源的組織,也可以使用存取套件來建立其存取原則的模型:
- 如果組織已經有其商務角色的現有組織角色模型,他們可以將該模型移轉至Microsoft Entra ID 控管,使用組織角色模型控管存取。
- 如果組織具有多個角色的應用程式,則可以部署組織原則,以控管與 Microsoft Entra ID 整合之應用程式的存取權
- 如需建立其他案例存取套件的詳細資訊,請參閱教學課程:管理權利管理中的資源存取,以及如何在權利管理中建立存取套件。
必要條件
使用此功能需要 Microsoft Entra ID 控管或 Microsoft Entra 套件授權。 若要找到適合您需求的授權,請參閱 Microsoft Entra ID 控管授權基礎知識。
開始建立存取套件之前,您必須先整合應用程式與 Microsoft Entra ID。 如果您的應用程式尚未存在於 Microsoft Entra ID 租用戶中,請遵循該文章中的指示,為物件建立應用程式和服務主體。 此外,請確定您的 Microsoft Entra ID 租用戶已符合 必要條件,再為身分識別治理設定 Microsoft Entra ID。
若要建立存取套件及其相關聯的原則和指派,您必須備妥下列資訊:
使用案例 | 組態設定 | PowerShell 變數 |
---|---|---|
全部 | Microsoft Entra ID 租用戶中的應用程式名稱 | $servicePrincipalName |
全部 | 應用程式角色的名稱 | $servicePrincipalRoleName |
依賴安全組的應用程式 | 應用程式所使用的Microsoft Entra 安全組標識符,如果有的話 | $groupId |
全部 | 包含存取套件之目錄的名稱 | $catalogName |
全部 | 提供存取套件的名稱 | $accessPackageName |
全部 | 提供存取套件的描述 | $accessPackageDescription |
使用不相容存取套件區分職責需求 | 不相容存取套件的識別碼 |
$incompatibleAccessPackageId (需要時) |
尚未指派且不會自動指派的使用者 | 使用者清單 |
$inputpath (需要時) |
具有特定屬性的使用者會自動擁有指派 | 範圍中使用者的查詢運算式 |
$autoAssignmentPolicyFilter (需要時) |
允許沒有指派的使用者要求指派 | 可以要求的使用者範圍、核准者和存取權檢閱期間 | 視需求而定 |
根據加入或離開生命週期工作流程中的工作流程,自動建立或移除指派 | 提供和移除存取權的工作流程名稱 | 視需求而定 |
至 Microsoft Entra ID 進行驗證
本節說明如何使用 Microsoft Graph PowerShell Cmdlet 來與 Microsoft Entra ID 控管互動。
組織在此情況下第一次使用這些 Cmdlet 時,您必須是全域管理員角色,才能在租用戶中使用 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
搜尋目錄的識別碼。
$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" }
將群組新增為資源至目錄
如果應用程式依賴安全組,請將該群組新增至目錄,以便將其納入為資源。 如果應用程式不依賴安全組,請繼續進行下一節。
指定群組的識別碼。 使用群組的標識碼作為
servicePrincipalName
的值。$groupId = "7c2b967b-68c2-418a-a1c6-a3c7efb895a7"
檢查群組是否已經以資源的形式存在於目錄中。 如果已經存在,請繼續進行本節的步驟 4。
$groupResourceId = $null foreach ($r in $catalog.Resources) { if ($r.OriginId -eq $groupId) { $groupResourceId = $r.id; break } } if ($groupResourceId -ne $null) { write-output "resource for group already in catalog" } else {write-output "resource for group not yet in catalog"}
將群組新增為資源至目錄。
$groupResourceAddParams = @{ requestType = "adminAdd" resource = @{ originId = $groupId originSystem = "AadGroup" } catalog = @{ id = $catalogId } } $groupResourceAdd = New-MgEntitlementManagementResourceRequest -BodyParameter $groupResourceAddParams if ($groupResourceAdd -eq $null) { throw "group resource could not be added" } sleep 5
擷取該目錄中群組資源的標識碼和範圍。
$groupResource = $null $groupResourceId = $null $groupResourceScope = $null $catalogResources = Get-MgEntitlementManagementCatalogResource -AccessPackageCatalogId $CatalogId -ExpandProperty "scopes" -all foreach ($r in $catalogResources) { if ($r.OriginId -eq $groupId) { $groupResource = $r; $groupResourceId = $r.id; $groupResourceScope = $r.Scopes[0]; break } } if ($groupResourceId -eq $null) { throw "resource was not added" }
擷取該目錄中群組資源的
member
角色。$grFilter = "(originSystem eq 'AadGroup' and resource/id eq '" + $groupResourceId + "')" $grrs = Get-MgEntitlementManagementCatalogResourceRole -AccessPackageCatalogId $CatalogId -Filter $grFilter -ExpandProperty "resource" $grMember = $grrs | where DisplayName -eq "Member"
建立應用程式的存取套件
接下來,您將使用 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
將群組新增至存取套件
如果應用程式依賴群組,則您會將群組的群組成員資格連結至存取套件。 如果應用程式不依賴群組,請繼續進行下一節。
$grrsParams = @{
role = @{
displayName = "Member"
description = ""
originSystem = $grMember.OriginSystem
originId = $grMember.OriginId
resource = @{
id = $groupResource.Id
originId = $groupResource.OriginId
originSystem = $groupResource.OriginSystem
}
}
scope = @{
id = $groupResourceScope.Id
originId = $groupResourceScope.OriginId
originSystem = $groupResourceScope.OriginSystem
}
}
$groupRrsAddRes = New-MgEntitlementManagementAccessPackageResourceRoleScope -AccessPackageId $accessPackageId -BodyParameter $grrsParams
建立直接指派的存取套件指派原則
在本節中,您將在存取套件中建立第一個存取套件指派原則,這是直接指派存取套件指派原則,可用來追蹤已擁有應用程式存取權的使用者。 在本節中建立的範例原則中,只有系統管理員或存取套件指派管理員可以指派存取權、使用者無限期地保留存取權,而且沒有核准或存取權檢閱。
建立原則。
$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 ID 中使用者的篩選。 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 生命週期工作流程員工加入、移動離開事件,則您也可以將工作新增至這些工作流程,以新增或移除此存取套件的指派。 如果您未使用生命週期工作流程,請繼續進行下一節。
此範例說明如何變更聯結並離開事件工作流程。
將工作新增至該工作流程中的工作清單。
工作顯示名稱 taskDefinitionId 引數 要求使用者存取套件的指派 c1ec1e76-f374-4375-aaa6-0bb6bd4c60be
name: assignmentPolicyId
value:指派原則識別碼,例如,如果不需要核准,則來自$directAssignmentPolicyId
的值,用於您要指派使用者的存取套件。
name:accessPackageId
value:您要指派給使用者的存取套件識別碼$accessPackageId
。使用 New-MgIdentityGovernanceLifecycleWorkflowNewVersion 命令,建立新的工作流程版本,包括新的工作。
將工作新增至該工作流程中的工作清單。
工作顯示名稱 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"
移除指派
您可以使用 New-MgEntitlementManagementAssignmentRequest
Cmdlet 移除使用者的指派。
$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
}