共用方式為

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

  • 發行項

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

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

必要條件

使用此功能需要 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
全部 包含存取套件之目錄的名稱 $catalogName
全部 提供存取套件的名稱 $accessPackageName
全部 提供存取套件的描述 $accessPackageDescription
使用不相容存取套件區分職責需求 不相容存取套件的識別碼 $incompatibleAccessPackageId (需要時)
尚未指派且不會自動指派的使用者 使用者清單 $inputpath (需要時)
具有特定屬性的使用者會自動擁有指派 範圍中使用者的查詢運算式 $autoAssignmentPolicyFilter (需要時)
允許沒有指派的使用者要求指派 可以要求的使用者範圍、核准者和存取權檢閱期間 視需求而定
根據加入或離開生命週期工作流程中的工作流程，自動建立或移除指派 提供和移除存取權的工作流程名稱 視需求而定

至 Microsoft Entra ID 進行驗證

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

組織在此情況下第一次使用這些 Cmdlet 時，您必須是全域管理員角色，才能在租用戶中使用 Microsoft Graph PowerShell。 後續的互動可以使用特殊權限較低的角色，例如：

  1. 開啟 PowerShell。

  2. 如果您尚未安裝 Microsoft Graph PowerShell 模組，請使用此命令來安裝 Microsoft.Graph.Identity.Governance 模組和其他模組：

    Install-Module Microsoft.Graph

    如果已安裝這些模組，請確定是使用最新版本：

    Update-Module microsoft.graph.users,microsoft.graph.identity.governance,microsoft.graph.applications

  3. 連線至 Microsoft Entra ID：

    $msg = Connect-MgGraph -ContextScope Process -Scopes "User.ReadWrite.All,Application.ReadWrite.All,AppRoleAssignment.ReadWrite.All,EntitlementManagement.ReadWrite.All"

  4. 如果這是您第一次使用此命令，您可能需要同意允許 Microsoft Graph 命令行工具具有這些權限。

在 Microsoft Entra 權利管理中建立目錄

根據預設，當系統管理員第一次與權利管理互動時，系統會自動建立預設目錄。 但是，受控管應用程式的存取套件應位於指定的目錄中。

  1. 指定目錄的名稱。

    $catalogName = "Business applications"

  2. 如果您已經有應用程式控管案例的目錄，請繼續進行本節的步驟 4。

  3. 如果您還沒有目錄可用於應用程式控管案例，請建立目錄。

    $catalog = New-MgEntitlementManagementCatalog -DisplayName $catalogName

  4. 搜尋目錄的識別碼。

    $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

將應用程式新增為資源至目錄

建立目錄之後，請將應用程式新增為該目錄中的資源。

  1. 指定應用程式的名稱和應用程式角色的名稱。 使用應用程式的名稱作為 servicePrincipalName 的值。

    $servicePrincipalName = "SAP Cloud Identity Services"
$servicePrincipalRoleName = "User"

  2. 搜尋應用程式服務主體的識別碼。

    $servicePrincipalFilter = "displayName eq '" + $applicationName + "'"
$servicePrincipal = Get-MgServicePrincipal -Filter $servicePrincipalFilter -all
if ($servicePrincipal -eq $null) { throw "service principal $servicePrincipalName not found" }
$servicePrincipalId = $servicePrincipal.Id

  3. 檢查應用程式是否已經以資源的形式存在於目錄中。 如果已經存在，請繼續進行本節的步驟 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"}

  4. 將應用程式服務主體新增為資源至目錄。

    $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

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

  6. 擷取應用程式的角色。

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

  7. 選取將包含在存取套件中的角色。

    $resourceRole = $null
foreach ($r in $resourceRoles) { if ($r.DisplayName -eq $servicePrincipalRoleName) { $resourceRole = $r; break; } }
if ($resourceRole -eq $null) { throw "role $servicePrincipalRoleName not located" }

建立應用程式的存取套件

接下來，您將使用 PowerShell 在目錄中建立包含應用程式角色的存取套件。

  1. 指定存取套件的名稱和描述。

    $accessPackageName = "SAP Cloud Identity Services"
$accessPackageDescription = "A user of SAP Cloud Identity Services"
$accessPackageHidden = $true

  2. 檢查存取套件不存在。

    foreach ($a in $catalog.AccessPackages) { if ($a.DisplayName -eq $accessPackageName) { throw "access package $accessPackageName already exists" } }

  3. 建立存取套件。

    $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

建立直接指派的存取套件指派原則

在本節中，您將在存取套件中建立第一個存取套件指派原則，這是直接指派存取套件指派原則，可用來追蹤已擁有應用程式存取權的使用者。 在本節中建立的範例原則中，只有系統管理員或存取套件指派管理員可以指派存取權、使用者無限期地保留存取權，而且沒有核准或存取權檢閱。

  1. 建立原則。

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

  1. 指定另一個與這個存取套件不相容的存取套件。 將 incompatibleAccessPackageId 的值變更為 Microsoft Entra 權利管理中另一個存取套件的識別碼。

    $incompatibleAccessPackageId = "67cc7175-7a3d-4cb2-860f-4d9217ba96ca"

  2. 在此存取套件上建立不相容的參考。

    $incompatible1params = @{
 "@odata.id" = "https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/accessPackages/" + $incompatibleAccessPackageId
}
New-MgEntitlementManagementAccessPackageIncompatibleAccessPackageByRef -AccessPackageId $accessPackageId -BodyParameter $incompatible1params

  3. 在其他存取套件上建立不相容的參考。

    $incompatible2params = @{
 "@odata.id" = "https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/accessPackages/" + $accessPackageId
}
New-MgEntitlementManagementAccessPackageIncompatibleAccessPackageByRef -AccessPackageId $incompatibleAccessPackageId -BodyParameter $incompatible2params

  4. 針對任何其他存取套件重複。

  5. 如果您的案例需要覆寫職責區分檢查的功能，您也可以為這些覆寫案例設定其他存取套件。

將已有應用程式存取權之現有使用者的指派新增

將已有應用程式存取權之現有使用者的指派新增至應用程式、存取套件和直接指派原則。 您可以直接將使用者指派給存取套件。

  1. 擷取現有的應用程式角色指派。

    $existingAppRoleAssignments = @(Get-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $servicePrincipalId -All)

  2. 若要避免建立重複的指派，請擷取存取套件的任何現有指派。

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

  3. 建立新的指派。

    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，藉此直接指派原則將這些使用者指派給存取套件。

  1. 指定輸入檔案的名稱。

    $inputpath = "users.csv"

  2. 若要避免建立重複的指派，請擷取存取套件的任何現有指派。

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

  3. 建立新的指派。

    $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. 指定使用者接收指派的自動指派篩選條件運算式。 將 autoAssignmentPolicyFilter 的值變更為範圍中 Microsoft Entra ID 中使用者的篩選。 Microsoft Entra ID 的組動態成員資格群組規則會提供語法及允許的屬性。

    $autoAssignmentPolicyFilter = '(user.city -eq "Redmond")'

  2. 使用 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。

  1. 指定原則的名稱、描述，以及將成為核准者之Microsoft Entra 使用者的識別碼。

    $policy3Name = "example policy"
$policy3Description = "example of a policy for users to request assignment"
$policy3ApproverSingleUserId = "1aaaaaa1-2bb2-3cc3-4dd4-5eeeeeeeeee5"

  2. 建立原則。

    $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 生命週期工作流程員工加入、移動離開事件，則您也可以將工作新增至這些工作流程，以新增或移除此存取套件的指派。 如果您未使用生命週期工作流程，請繼續進行下一節。

此範例說明如何變更聯結並離開事件工作流程。

  1. 使用 get-MgIdentityGovernanceLifecycleWorkflow 命令，擷取 joiner 類別工作流程及其工作。

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

    工作顯示名稱 taskDefinitionId 引數
    要求使用者存取套件的指派 c1ec1e76-f374-4375-aaa6-0bb6bd4c60be name：assignmentPolicyId
    value：指派原則識別碼，例如，如果不需要核准，則來自 $directAssignmentPolicyId 的值，用於您要指派使用者的存取套件。

    name：accessPackageId
    value：您要指派給使用者的存取套件識別碼 $accessPackageId。

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

  4. 使用 get-MgIdentityGovernanceLifecycleWorkflow 命令，擷取 leaver 類別工作流程及其工作。

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

    工作顯示名稱 taskDefinitionId 引數
    為使用者移除存取套件的指派 4a0b64f2-c7ec-46ba-b117-18f262946c50 name：accessPackageId
    value：您要取消指派給使用者的有效存取套件識別碼 accessPackageId。

  6. 使用 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
}

下一步