Criar um pacote de acesso no gerenciamento de direitos para um aplicativo com uma única função usando o PowerShell
No gerenciamento de direitos do Microsoft Entra, um pacote de acesso engloba as políticas de como os usuários podem obter atribuições para uma ou mais funções de recurso. 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 estão usando o gerenciamento de direitos para automatizar o acesso contínuo para um aplicativo de negócios ou middleware específico. Uma organização que tem vários recursos ou recursos com várias funções também pode modelar suas políticas de acesso com pacotes de acesso:
- Se a organização já tiver um modelo de função organizacional existente para suas funções de negócios, ela poderá migrar esse modelo para a Governança de ID do Microsoft Entra e controlar o acesso com um modelo de função organizacional.
- Se a organização tiver aplicativos com várias funções, ela poderá implantar políticas organizacionais para controlar o acesso a aplicativos integrados ao Microsoft Entra ID
- Para obter mais informações sobre como criar pacotes de acesso para outros cenários, consulte o tutorial: Gerenciar o acesso a recursos no gerenciamento de direitos e como criar um pacote de acesso no gerenciamento de direitos.
Pré-requisitos
O uso desse recurso requer licenças do Microsoft Entra ID Governance ou do Microsoft Entra Suite. Para encontrar a licença certa para seus requisitos, consulte Fundamentos de licenciamento do Microsoft Entra ID Governance.
Antes de começar a criar o pacote de acesso, você deve integrar o aplicativo com o Microsoft Entra ID. Se o seu aplicativo ainda não estiver presente no locatário do Microsoft Entra ID, siga as instruções nesse artigo para criar uma entidade de segurança de aplicativo e serviço para o objeto. Verifique também se o locatário do Microsoft Entra ID atendeu 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 utilização | Definição de configuração | Variável PowerShell |
---|---|---|
Todos | Nome do aplicativo em seu locatário do Microsoft Entra ID | $servicePrincipalName |
Todos | Nome da função do aplicativo | $servicePrincipalRoleName |
Todos | Nome do catálogo que contém o pacote de acesso | $catalogName |
Todos | Nome a dar ao pacote de acesso | $accessPackageName |
Todos | Descrição para dar o pacote de acesso | $accessPackageDescription |
Requisito de separação de funções com um pacote de acesso incompatível | o 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 utilizadores | $inputpath (se necessário) |
Usuários com atributos específicos têm 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 |
Automatize a criação ou remoção de atribuições com base em fluxos de trabalho de ingresso ou saída em fluxos de trabalho de ciclo de vida | Os nomes dos fluxos de trabalho que dão e removem acesso | depende dos requisitos |
Autenticar no Microsoft Entra ID
Esta seção mostra como interagir com a Governança de ID do Microsoft Entra usando cmdlets do Microsoft Graph PowerShell .
Na primeira vez que sua organização usar esses cmdlets para esse cenário, você precisará estar em uma função de Administrador Global para permitir que o Microsoft Graph PowerShell seja usado em seu locatário. As interações subsequentes podem usar um papel menos privilegiado, como:
Abra o PowerShell.
Se você não tiver os módulos do Microsoft Graph PowerShell já instalados, instale o
Microsoft.Graph.Identity.Governance
módulo e outros usando este comando:Install-Module Microsoft.Graph
Se já tiver os módulos instalados, certifique-se de que está a utilizar uma versão recente:
Update-Module microsoft.graph.users,microsoft.graph.identity.governance,microsoft.graph.applications
Conecte-se ao Microsoft Entra ID:
$msg = Connect-MgGraph -ContextScope Process -Scopes "User.ReadWrite.All,Application.ReadWrite.All,AppRoleAssignment.ReadWrite.All,EntitlementManagement.ReadWrite.All"
Se esta for a primeira vez que você usa esse comando, talvez seja necessário consentir para permitir que as ferramentas de linha de comando do Microsoft Graph tenham 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.
Especifique o nome do catálogo.
$catalogName = "Business applications"
Se você já tiver um catálogo para seu cenário de governança de aplicativo, continue na etapa 4 desta seção.
Se você ainda não tiver um catálogo para seu cenário de governança de aplicativos, crie um catálogo.
$catalog = New-MgEntitlementManagementCatalog -DisplayName $catalogName
Procure o 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.
Especifique o nome do aplicativo e o nome da função do aplicativo. Use o nome do seu aplicativo como o valor de
servicePrincipalName
.$servicePrincipalName = "SAP Cloud Identity Services" $servicePrincipalRoleName = "User"
Procure a ID da entidade de serviço do aplicativo.
$servicePrincipalFilter = "displayName eq '" + $applicationName + "'" $servicePrincipal = Get-MgServicePrincipal -Filter $servicePrincipalFilter -all if ($servicePrincipal -eq $null) { throw "service principal $servicePrincipalName not found" } $servicePrincipalId = $servicePrincipal.Id
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"}
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
Recupere a ID e o escopo do recurso nesse 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" }
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" }
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.
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
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" } }
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 pacotes de acesso para atribuição direta
Nesta seção, você criará a política de atribuição do primeiro 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 seção, somente os administradores ou gerentes de atribuição de pacotes de acesso podem atribuir acesso, os usuários retêm o acesso indefinidamente e não há aprovações ou revisões de acesso.
Crie 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 restrições de separação de funções
O gerenciamento de direitos do Microsoft Entra pode impor verificações de separação de tarefas para impedir 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 requisitos de separação de tarefas, configure os pacotes de acesso incompatíveis ou grupos existentes para seu pacote de acesso.
Para cada pacote de acesso que deve ser marcado como incompatível com outro, você pode usar um PowerShell configurar pacotes de acesso como incompatíveis.
Especifique o outro pacote de acesso que é incompatível com este. Altere o valor de para a ID de outro pacote de acesso no gerenciamento de direitos do
incompatibleAccessPackageId
Microsoft Entra.$incompatibleAccessPackageId = "67cc7175-7a3d-4cb2-860f-4d9217ba96ca"
Crie a referência incompatível neste pacote de acesso.
$incompatible1params = @{ "@odata.id" = "https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/accessPackages/" + $incompatibleAccessPackageId } New-MgEntitlementManagementAccessPackageIncompatibleAccessPackageByRef -AccessPackageId $accessPackageId -BodyParameter $incompatible1params
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
Repita para quaisquer outros pacotes de acesso.
Se o seu cenário exigir a capacidade de substituir uma verificação de separação de funções, 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.
Recupere as atribuições de função de aplicativo existentes.
$existingAppRoleAssignments = @(Get-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $servicePrincipalId -All)
Para evitar a criação de atribuições duplicadas, recupere quaisquer 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}
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 para quaisquer usuários adicionais que devem ter acesso ao aplicativo
Este script ilustra o uso dos cmdlets do Microsoft Graph PowerShell para adicionar atribuições para usuários adicionais para que eles tenham acesso ao aplicativo. Se você não tiver nenhum usuário que precise de acesso e não o receba automaticamente, 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.
Especifique o nome do arquivo de entrada.
$inputpath = "users.csv"
Para evitar a criação de atribuições duplicadas, recupere quaisquer 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}
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 para quem pode ser atribuído 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.
Especifique a expressão de filtro de atribuição automática para que os usuários recebam uma atribuição. Altere o valor de
autoAssignmentPolicyFilter
para ser um filtro para os usuários em sua ID do Microsoft Entra que estão no escopo. A sintaxe e os atributos permitidos são fornecidos em regras para grupos de associação dinâmica no Microsoft Entra ID.$autoAssignmentPolicyFilter = '(user.city -eq "Redmond")'
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 permitido para solicitar a atribuição ao aplicativo, você também pode 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 os usuários tenham acesso atribuído automaticamente ou por um administrador, continue na próxima seção.
Para obter mais exemplos, consulte Criar uma política de atribuição por meio do PowerShell, accessPackageAssignmentPolicy e Criar uma assignmentPolicy.
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"
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 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 este pacote de acesso. Se você não usa 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 ingresso e saída.
Recupere o fluxo de trabalho de categoria e suas tarefas usando o
joiner
comando Get-MgIdentityGovernanceLifecycleWorkflow.Adicione uma tarefa à lista de tarefas nesse fluxo de trabalho.
Nome para exibição da tarefa taskDefinitionId Argumentos Solicitar atribuição de pacote de acesso de usuário c1ec1e76-f374-4375-aaa6-0bb6bd4c60be
Designação: assignmentPolicyId
value: O ID da política de atribuição, como o valor de se nenhuma aprovação for necessária, para o pacote de$directAssignmentPolicyId
acesso que você deseja atribuir ao usuário.
Designação:accessPackageId
value: O ID do pacote de acesso,$accessPackageId
, para o pacote de acesso que você deseja atribuir ao usuário.Crie uma nova versão do fluxo de trabalho, incluindo a nova tarefa, usando o comando New-MgIdentityGovernanceLifecycleWorkflowNewVersion .
Recupere o fluxo de trabalho de categoria e suas tarefas usando o
leaver
comando Get-MgIdentityGovernanceLifecycleWorkflow.Adicione uma tarefa à lista de tarefas nesse fluxo de trabalho.
Nome para exibição da tarefa taskDefinitionId Argumentos Remover atribuição de pacote de acesso para o usuário 4a0b64f2-c7ec-46ba-b117-18f262946c50
Designação: accessPackageId
value: Um ID de pacote de acesso válido,accessPackageId
para o pacote de acesso que você deseja cancelar a atribuição do usuário.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 tiverem sido criados, os usuários receberão acesso à função do aplicativo.
Mais tarde, você pode monitorar alterações nas atribuições ou adicionar ou remover atribuições programaticamente.
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 assignments.csv
CSV com uma lista de usuários que têm 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 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
}