Бөлісу құралы:

Создание пакета доступа в управлении правами для приложения с одной ролью с помощью PowerShell

  • Мақала

В службе управления правами Microsoft Entra пакет доступа охватывает политики того, как пользователи могут получать назначения для одной или нескольких ролей ресурсов. Ресурсы могут включать группы, приложения и сайты SharePoint Online.

В этой статье описывается, как создать пакет доступа для одного приложения с одной ролью с помощью Microsoft Graph PowerShell. Этот сценарий в первую очередь применим к средам, использующим управление правами для автоматизации текущего доступа для конкретного бизнес-приложения или по промежуточного слоя. Организация с несколькими ресурсами или ресурсами с несколькими ролями также может моделировать политики доступа с помощью пакетов доступа:

Необходимые компоненты

Для использования этой функции требуются лицензии Управление идентификацией Microsoft Entra или Microsoft Entra Suite. Чтобы найти подходящую лицензию для ваших требований, см. Управление идентификацией Microsoft Entra основы лицензирования.

Прежде чем приступить к созданию пакета доступа, необходимо интегрировать приложение с идентификатором Microsoft Entra. Если приложение еще не присутствует в клиенте идентификатора Microsoft Entra ID, следуйте инструкциям в этой статье, чтобы создать приложение и субъект-службу для объекта. Кроме того, убедитесь, что клиент Идентификатора Microsoft Entra выполнил предварительные требования перед настройкой идентификатора Microsoft Entra для управления удостоверениями.

Чтобы создать пакет доступа и связанные с ним политики и назначения, вам потребуется подготовить следующие сведения:

Вариант использования Параметр конфигурации Переменная PowerShell
Все Имя приложения в клиенте идентификатора Microsoft Entra $servicePrincipalName
Все Имя роли приложения $servicePrincipalRoleName
Все Имя каталога, содержащего пакет доступа $catalogName
Все Имя для предоставления пакета доступа $accessPackageName
Все Описание предоставления пакета доступа $accessPackageDescription
Разделение обязанностей с несовместимым пакетом доступа Идентификатор несовместимого пакета доступа $incompatibleAccessPackageId (при необходимости)
Пользователи, которые еще не имеют назначений и не будут автоматически назначены список пользователей $inputpath (при необходимости)
Пользователи с определенными атрибутами автоматически имеют назначения выражение запроса для пользователей в области $autoAssignmentPolicyFilter (при необходимости)
Разрешить пользователям, у которых нет назначения, запрашивать назначение область действия пользователей, которые могут запрашивать, утверждающих и период проверки доступа зависит от требований
Автоматизация создания или удаления назначений на основе объединения или выхода рабочих процессов в рабочих процессах жизненного цикла имена рабочих процессов, которые предоставляют и удаляют доступ зависит от требований

Проверка подлинности в идентификаторе Microsoft Entra

В этом разделе показано, как взаимодействовать с Управление идентификацией Microsoft Entra с помощью командлетов Microsoft Graph PowerShell.

Когда ваша организация впервые применит эти командлеты для данного сценария, вам потребуется роль глобального администратора, чтобы предоставить согласие на использование 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:

    $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 для добавления дополнительных пользователей в приложение. Если у вас нет пользователей, которым требуется доступ, и он не получится автоматически, перейдите к следующему разделу.

Этот скрипт предполагает, что у вас есть входной 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, которые находятся в области. Синтаксис и допустимые атрибуты предоставляются в правилах динамического членства для групп в идентификаторе Microsoft Entra.

    $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 и создание назначенияPolicy.

  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. Получите рабочий joiner процесс категории и его задачи с помощью команды Get-MgIdentityGovernanceLifecycleWorkflow .

  2. Добавьте задачу в список задач в этом рабочем процессе.

    Отображаемое имя задачи taskDefinitionId аргументы
    Запрос назначения пакета доступа пользователей c1ec1e76-f374-4375-aaa6-0bb6bd4c60be имя: assignmentPolicyId
    значение: идентификатор политики назначения, например значение, от $directAssignmentPolicyId которого не требуется утверждение, для пакета доступа, который требуется назначить пользователю.

    имя: accessPackageId
    значение: идентификатор пакета доступа для пакета доступа, $accessPackageIdкоторый требуется назначить пользователю.

  3. Создайте новую версию рабочего процесса, включая новую задачу, с помощью команды New-MgIdentityGovernanceLifecycleWorkflowNewVersion .

  4. Получите рабочий leaver процесс категории и его задачи с помощью команды Get-MgIdentityGovernanceLifecycleWorkflow .

  5. Добавьте задачу в список задач в этом рабочем процессе.

    Отображаемое имя задачи taskDefinitionId аргументы
    Удаление назначения пакета доступа для пользователя 4a0b64f2-c7ec-46ba-b117-18f262946c50 имя: accessPackageId
    значение: допустимый идентификатор пакета доступа для пакета доступа, 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 .

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

Следующие шаги