Criar um pacote de acesso no gerenciamento de direitos de um aplicativo com uma única função usando o PowerShell

  • Artigo

No gerenciamento de direitos do Microsoft Entra, um pacote de acesso abrange as políticas sobre como os usuários podem obter atribuições para uma ou mais funções de recursos. Os recursos podem incluir grupos, aplicativos e sites do SharePoint Online.

Este artigo descreve como criar um pacote de acesso para um único aplicativo com uma única função, usando o Microsoft Graph PowerShell. Esse cenário é aplicável principalmente a ambientes que usam o gerenciamento de direitos para automatizar o acesso contínuo a um aplicativo comercial ou de middleware específico. Uma organização que tem vários recursos ou recursos com diversas funções também pode modelar suas políticas de acesso com pacotes de acesso:

Pré-requisitos

O uso desse recurso exige licenças do Microsoft Entra ID Governance ou da Suíte do Microsoft Entra. Para encontrar a licença certa para seus requisitos, confira Conceitos básicos de licenciamento do Microsoft Entra ID Governance.

Antes de começar a criar o pacote de acesso, você deve integrar o aplicativo ao Microsoft Entra ID. Se o aplicativo ainda não estiver presente no seu locatário do Microsoft Entra ID, siga as instruções neste artigo para criar um aplicativo e uma entidade de serviço para o objeto. Também certifique-se de que seu locatário do Microsoft Entra ID atende aos pré-requisitos antes de configurar o Microsoft Entra ID para governança de identidade.

Para criar o pacote de acesso e suas políticas e atribuições associadas, você precisará ter as seguintes informações prontas:

Caso de uso Definição de configuração Variável do PowerShell
Tudo Nome do aplicativo no locatário do Microsoft Entra ID $servicePrincipalName
Tudo Nome da função de aplicativo $servicePrincipalRoleName
Tudo Nome do catálogo que contém o pacote de acesso $catalogName
Tudo Nome para fornecer o pacote de acesso $accessPackageName
Tudo Descrição para fornecer o pacote de acesso $accessPackageDescription
Requisito da separação de funções com um pacote de acesso incompatível a ID do pacote de acesso incompatível $incompatibleAccessPackageId (se necessário)
Usuários que ainda não têm atribuições e não seriam atribuídos automaticamente lista de usuários $inputpath (se necessário)
Usuários com atributos específicos recebem atribuições automaticamente a expressão de consulta para os usuários no escopo $autoAssignmentPolicyFilter (se necessário)
Permitir que os usuários que não têm uma atribuição solicitem uma atribuição o escopo dos usuários que podem solicitar, os aprovadores e o período de revisão de acesso depende dos requisitos
Automatizar a criação ou remoção de atribuições com base em fluxos de trabalho de junção ou de saída em fluxos de trabalho do ciclo de vida os nomes dos fluxos de trabalho que dão e removem o acesso depende dos requisitos

Autenticar no Microsoft Entra ID

Esta seção mostra como interagir com o Microsoft Entra ID Governance usando cmdlets do Microsoft Graph PowerShell.

Na primeira vez que sua organização usar esses cmdlets nesse cenário, você precisará ter a função de Administrador global para permitir que o PowerShell do Microsoft Graph seja usado no seu locatário. As interações subsequentes podem usar uma função com privilégios inferiores, como:

  1. Abra o PowerShell.

  2. Se você ainda não tiver os módulos do PowerShell do Microsoft Graph instalados, instale o módulo Microsoft.Graph.Identity.Governance e os demais usando este comando:

    Install-Module Microsoft.Graph

    Se você já tiver os módulos instalados, verifique se está usando uma versão recente:

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

  3. Conecte-se ao Microsoft Entra ID:

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

  4. Se esta for a primeira vez que você usa este comando, talvez seja necessário dar consentimento para que as ferramentas de linha de comando do Microsoft Graph acessem essas permissões.

Criar um catálogo no gerenciamento de direitos do Microsoft Entra

Por padrão, quando um administrador interage pela primeira vez com o gerenciamento de direitos, um catálogo padrão é criado automaticamente. No entanto, os pacotes de acesso para aplicativos controlados devem estar em um catálogo designado.

  1. Especifique o nome do catálogo.

    $catalogName = "Business applications"

  2. Se você já tiver um catálogo para o cenário de governança de aplicativos, continue na etapa 4 desta seção.

  3. Se você ainda não tiver um catálogo para o cenário de governança do aplicativo, crie um catálogo.

    $catalog = New-MgEntitlementManagementCatalog -DisplayName $catalogName

  4. Procure a ID do catálogo.

    $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

Adicionar o aplicativo como um recurso ao catálogo

Depois que o catálogo for criado, adicione o aplicativo como um recurso nesse catálogo.

  1. Especifique o nome do aplicativo e o nome da função de aplicativo. Use o nome do aplicativo como o valor de servicePrincipalName.

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

  2. Procure a ID da entidade de serviço de aplicativo.

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

  3. Verifique se o aplicativo já está presente no catálogo como um recurso. Se já estiver presente, continue na etapa 6 desta seção.

    $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. Adicione a entidade de serviço do aplicativo como um recurso ao catálogo.

    $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. Recupere a ID e o escopo do recurso neste catálogo.

    $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. Recupere as funções do aplicativo.

    $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. Selecione a função que será incluída no pacote de acesso.

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

Criar o pacote de acesso para o aplicativo

Em seguida, você usará o PowerShell para criar um pacote de acesso em um catálogo que inclua a função do aplicativo.

  1. Especifique o nome e a descrição do pacote de acesso.

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

  2. Verifique se o pacote de acesso ainda não existe.

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

  3. Crie o pacote de acesso.

    $accessPackageParams = @{
    displayName = $accessPackageName
    description = $accessPackageDescription
    isHidden = $accessPackageHidden
    catalog = @{
        id = $catalog.id
    }
}
$accessPackage = New-MgEntitlementManagementAccessPackage -BodyParameter $accessPackageParams
$accessPackageId = $accessPackage.Id

Adicionar a função de aplicativo ao pacote de acesso

Depois de criar um pacote de acesso, vincule a função do recurso no catálogo ao pacote de acesso.

$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

Criar políticas de atribuição de pacote de acesso para atribuição direta

Nesta seção, você criará a primeira política de atribuição do pacote de acesso no pacote de acesso, uma política de atribuição de pacote de acesso para atribuição direta, que pode ser usada para rastrear os usuários que já têm acesso ao aplicativo. Na política de exemplo criada nesta secção, apenas os administradores ou gerentes de atribuição de pacotes de acesso podem atribuir acesso, os usuários mantêm o acesso indefinidamente e não há aprovações ou revisões de acesso.

  1. Criar uma política.

    $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

Configurar as restrições de separação de funções

O gerenciamento de direitos do Microsoft Entra pode impor verificações de separação de funções para evitar que um usuário que já tenha uma atribuição existente a outro pacote de acesso designado, ou associação a um grupo designado, solicite um pacote de acesso.

Se você não tiver requisitos de separação de funções para este aplicativo, continue na próxima seção.

Se você tiver os requisitos de separação de tarefas, configure os pacotes de acesso incompatíveis ou os grupos existentes para o seu pacote de acesso.

Para cada pacote de acesso que será marcado como incompatível com outro, você poderá usar um PowerShell para configurar pacotes de acesso como incompatíveis.

  1. Especifique o outro pacote de acesso incompatível com este. Altere o valor de incompatibleAccessPackageId para a ID de outro pacote de acesso no gerenciamento de direitos do Microsoft Entra.

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

  2. Crie a referência incompatível nesse pacote de acesso.

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

  3. Crie a referência incompatível no outro pacote de acesso.

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

  4. Repita para qualquer outro pacote de acesso.

  5. Se o cenário exigir a capacidade de substituir uma verificação de separação de tarefas, você também poderá configurar pacotes de acesso adicionais para esses cenários de substituição.

Adicionar atribuições de usuários existentes que já têm acesso ao aplicativo

Adicione atribuições de usuários existentes, que já têm acesso ao aplicativo, ao pacote de acesso e à sua política de atribuição direta. Você pode atribuir diretamente cada usuário a um pacote de acesso.

  1. Recupere as atribuições de função de aplicativo existentes.

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

  2. Para evitar a criação de atribuições duplicadas, recupere as atribuições existentes para o pacote de acesso.

    $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. Crie novas atribuições.

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

Adicionar atribuições a usuários adicionais que devem ter acesso ao aplicativo

Este script ilustra o uso dos cmdlets do Microsoft Graph PowerShell para adicionar atribuições a usuários adicionais para que eles tenham acesso ao aplicativo. Se você não tiver usuários que precisam de acesso e não o receberiam automaticamente, então continue na próxima seção.

Este script pressupõe que você tenha um arquivo CSV de entrada contendo uma coluna, UserPrincipalName, para atribuir esses usuários ao pacote de acesso por meio de sua política de atribuição direta.

  1. Especifique o nome do arquivo de entrada.

    $inputpath = "users.csv"

  2. Para evitar a criação de atribuições duplicadas, recupere as atribuições existentes para o pacote de acesso.

    $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. Crie novas atribuições.

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

Adicionar uma política aos pacotes de acesso para atribuição automática

Se a política da sua organização sobre quem pode receber acesso a um aplicativo incluir uma regra baseada nos atributos do usuário para atribuir e remover o acesso automaticamente com base nesses atributos, você poderá representar isso usando uma política de atribuição automática. Um pacote de acesso pode ter no máximo uma política de atribuição automática. Se você não tiver um requisito para uma atribuição automática, continue na próxima seção.

  1. Especifique a expressão de filtro de atribuição automática para os usuários receberem uma atribuição. Altere o valor de autoAssignmentPolicyFilter para ser um filtro para os usuários em seu Microsoft Entra ID que estão no escopo. A sintaxe e os atributos permitidos são fornecidos em regras de grupos de associação dinâmica no Microsoft Entra ID.

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

  2. Use o PowerShell para criar uma política de atribuição automática no pacote de acesso.

    $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

Criar políticas adicionais para permitir que os usuários solicitem acesso

Se os usuários que ainda não têm acesso tiverem permissão para solicitar a atribuição ao aplicativo, você também poderá configurar uma política de atribuição de pacote de acesso para permitir que os usuários solicitem um pacote de acesso. Você pode adicionar políticas adicionais a um pacote de acesso e, em cada política, especificar quais usuários podem solicitar e quem deve aprovar. Se você deseja que apenas usuários tenham acesso atribuído automaticamente ou por um administrador, continue na próxima seção.

Para obter mais exemplos, confira Criar uma política de atribuição através do PowerShell, accessPackageAssignmentPolicy e Criar uma assignmentPolicy.

  1. Especifique o nome, a descrição da política e a ID de um usuário do Microsoft Entra que será o aprovador.

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

  2. Crie a política.

    $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

Configurar tarefas de fluxos de trabalho do ciclo de vida

Se você usar os fluxos de trabalho do ciclo de vida do Microsoft Entra para ingresso de funcionários, mover eventos de licença, também poderá adicionar tarefas a esses fluxos de trabalho para adicionar ou remover atribuições a esse pacote de acesso. Se você não usar fluxos de trabalho do ciclo de vida, continue na próxima seção.

Este exemplo ilustra como fazer uma alteração nos fluxos de trabalho de eventos de junção e de saída.

  1. Recupere o fluxo de trabalho da categoria joiner e suas tarefas, usando o comando Get-MgIdentityGovernanceLifecycleWorkflow.

  2. Adicione uma tarefa à lista de tarefas nesse fluxo de trabalho.

    Nome de exibição da tarefa taskDefinitionId argumentos
    Solicitar a atribuição do pacote de acesso do usuário c1ec1e76-f374-4375-aaa6-0bb6bd4c60be nome: assignmentPolicyId
    value: a ID da política de atribuição, como o valor de $directAssignmentPolicyId se nenhuma aprovação for necessária, para o pacote de acesso que você deseja atribuir ao usuário.

    nome: accessPackageId
    valor: a ID do pacote de acesso, $accessPackageId, para o pacote de acesso que você deseja atribuir ao usuário.

  3. Crie uma nova versão do fluxo de trabalho, incluindo a nova tarefa, usando o comando New-MgIdentityGovernanceLifecycleWorkflowNewVersion.

  4. Recupere o fluxo de trabalho da categoria leaver e suas tarefas, usando o comando Get-MgIdentityGovernanceLifecycleWorkflow.

  5. Adicione uma tarefa à lista de tarefas nesse fluxo de trabalho.

    Nome de exibição da tarefa taskDefinitionId argumentos
    Remover a atribuição do pacote de acesso do usuário 4a0b64f2-c7ec-46ba-b117-18f262946c50 nome: accessPackageId
    valor: uma ID do pacote de acesso válida, accessPackageId, para o pacote de acesso que você deseja cancelar a atribuição do usuário.

  6. Crie uma nova versão do fluxo de trabalho, incluindo a nova tarefa, usando o comando New-MgIdentityGovernanceLifecycleWorkflowNewVersion.

Gerenciar atribuições

Depois que os pacotes de acesso, as políticas e as atribuições iniciais forem criados, os usuários receberão acesso à função do aplicativo.

Posteriormente, você poderá monitorar as alterações nas atribuições ou adicionar ou remover atribuições de forma programática.

Recuperar atribuições existentes

Este script ilustra o uso de um filtro para recuperar as atribuições para o pacote de acesso que estão no estado Delivered. O script gera um arquivo CSV assignments.csv com uma lista de usuários que tem atribuições, com uma linha por atribuição.

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

Remover uma atribuição

Você pode remover a atribuição de um usuário com o cmdlet 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
}

Próximas etapas