Governar os usuários existentes de um aplicativo – Microsoft PowerShell

  • Artigo

Há três cenários comuns em que é necessário preencher o Microsoft Entra ID com usuários existentes de um aplicativo antes de usar o aplicativo com um recurso de governança do Microsoft Entra ID, como as revisões de acesso.

Requisitos de licença

O uso desse recurso exige licenças do Microsoft Entra ID Governance ou do 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.

Aplicativo migrado para o Microsoft Entra ID depois de usar seu próprio provedor de identidade

No primeiro cenário, o aplicativo já existe no ambiente. Anteriormente, o aplicativo usava o próprio provedor de identidade ou armazenamento de dados para acompanhar quais usuários tinham acesso.

Quando você altera o aplicativo para se basear no Microsoft Entra ID, somente os usuários que estão no Microsoft Entra ID e têm acesso a esse aplicativo podem acessá-lo. Como parte dessa alteração de configuração, você pode optar por trazer os usuários existentes no armazenamento de dados desse aplicativo para o Microsoft Entra ID. Esses usuários continuam tendo acesso por meio de Microsoft Entra ID.

Associar os usuários ao aplicativo representado no Microsoft Entra ID permitirá que o Microsoft Entra ID acompanhe os usuários com acesso ao aplicativo, mesmo que a relação do usuário com o aplicativo tenha se originado em outro lugar. Por exemplo, a relação pode ter se originado em um banco de dados ou diretório do aplicativo.

Depois que o Microsoft Entra ID tomar conhecimento da atribuição de um usuário, ele poderá enviar atualizações para o armazenamento de dados do aplicativo. Atualizações incluem quando os atributos desse usuário são alterados ou quando o usuário sai do escopo do aplicativo.

Aplicativo que não usa o Microsoft Entra ID como seu único provedor de identidade

No segundo cenário, um aplicativo não depende apenas do Microsoft Entra ID como provedor de identidade.

Em alguns casos, um aplicativo pode depender de grupos do AD. Esse cenário é descrito no Padrão B em Preparação para a revisão de acesso de um usuário a um aplicativo. Não é necessário configurar o provisionamento para esse aplicativo, conforme descrito nesse artigo, em vez disso, siga as instruções para o Padrão B nesse artigo sobre como examinar a associação de grupos do AD.

Em outros casos, um aplicativo pode dar suporte a vários provedores de identidade ou ter o próprio armazenamento interno de credenciais. Esse cenário é descrito como Padrão C na Preparação para a revisão de acesso de um usuário a um aplicativo.

Talvez não seja viável remover outros provedores de identidade ou autenticação de credencial local do aplicativo. Nesse caso, se quiser usar o Microsoft Entra ID para revisar quem tem acesso ao aplicativo ou para remover o acesso de alguém desse aplicativo, precisará criar atribuições no Microsoft Entra ID que representam usuários do aplicativo que não dependem do Microsoft Entra ID para autenticação.

Ter essas atribuições é necessário se você planeja revisar todos os usuários com acesso ao aplicativo como parte de uma revisão de acesso.

Por exemplo, suponha que um usuário esteja no armazenamento de dados do aplicativo. O Microsoft Entra ID está configurado para exigir atribuições de função ao aplicativo. No entanto, o usuário não tem uma atribuição de função de aplicativo no Microsoft Entra ID.

Se o usuário for atualizado no Microsoft Entra ID, nenhuma alteração será enviada ao aplicativo. E se as atribuições de função do aplicativo forem revisadas, o usuário não será incluído na revisão. Para que todos os usuários sejam incluídos na revisão, é necessário ter atribuições de função de aplicativo para todos os usuários do aplicativo.

O aplicativo não usa o Microsoft Entra ID como seu provedor de identidade nem dá suporte ao provisionamento

Para alguns aplicativos herdados, talvez não seja viável remover outros provedores de identidade ou autenticação de credencial local do aplicativo, ou habilitar o suporte para protocolos de provisionamento para esses aplicativos.

Esse cenário de um aplicativo que não dá suporte a protocolos de provisionamento é abordado em um artigo separado, Controlar os usuários existentes de um aplicativo que não dá suporte ao provisionamento.

Terminologia

Este artigo ilustra o processo de gerenciamento de atribuições de função de aplicativo usando os cmdlets do PowerShell do Microsoft Graph. Eles usam a terminologia do Microsoft Graph a seguir.

Diagrama que ilustra a terminologia do Microsoft Graph.

No Microsoft Entra ID, uma entidade de serviço (ServicePrincipal) representa um aplicativo em um diretório de uma determinada organização. ServicePrincipal tem uma propriedade AppRoles que lista as funções compatíveis com um aplicativo, como Marketing specialist. AppRoleAssignment vincula um usuário a uma entidade de serviço e especifica qual função o usuário tem nesse aplicativo. Um aplicativo pode ter mais de uma entidade de serviço, se o logon único no aplicativo e o provisionamento para o aplicativo forem tratados separadamente.

Você também pode usar os pacotes de acesso do gerenciamento de direitos do Microsoft Entra para dar aos usuários acesso por tempo limitado ao aplicativo. No gerenciamento de direitos, um AccessPackage contém uma ou mais funções de recurso, potencialmente de várias entidades de serviço. AccessPackage também tem atribuições (Assignment) para usuários ao pacote de acesso.

Ao criar uma atribuição para um usuário a um pacote de acesso, o gerenciamento de direitos do Microsoft Entra cria automaticamente as instâncias AppRoleAssignment necessárias para o usuário para cada entidade de serviço do aplicativo no pacote de acesso. Para obter mais informações, consulte o tutorial Gerenciar acesso a recursos no gerenciamento de direitos do Microsoft Entra sobre como criar pacotes de acesso por meio do PowerShell.

Antes de começar

Coletar usuários existentes em um aplicativo

A primeira etapa para garantir que todos os usuários estejam registrados no Microsoft Entra ID é coletar a lista de usuários existentes que têm acesso ao aplicativo.

Alguns aplicativos podem ter um comando interno para exportar uma lista de usuários atuais do armazenamento de dados. Em outros casos, o aplicativo pode depender de um diretório ou banco de dados externo.

Em alguns ambientes, o aplicativo pode estar localizado em um segmento da rede ou do sistema que não seja apropriado para gerenciar o acesso a Microsoft Entra ID. Portanto, talvez seja necessário extrair a lista de usuários desse diretório ou banco de dados e, em seguida, transferi-la como um arquivo para outro sistema que possa ser usado para interações do Microsoft Entra.

Esta seção explica quatro abordagens para obter uma lista de usuários em um arquivo CSV (arquivo de valores separados por vírgulas):

  • De um diretório LDAP
  • De um banco de dados do SQL Server
  • De outro banco de dados baseado em SQL
  • Pelo SAP Cloud Identity Services

Coletar usuários existentes de um aplicativo que usa um diretório LDAP

Esta seção é válida para aplicativos que usam um diretório LDAP como armazenamento de dados subjacente para usuários que não se autenticam no Microsoft Entra ID. Muitos diretórios LDAP, como o Active Directory, incluem um comando que dá saída em uma lista de usuários.

  1. Identifique os usuários nesse diretório que estão no escopo de serem usuários do aplicativo. Essa escolha dependerá da configuração do aplicativo. Para alguns aplicativos, qualquer usuário que exista em um diretório LDAP é um usuário válido. Outros aplicativos podem exigir que o usuário tenha um atributo específico ou seja membro de um grupo nesse diretório.

  2. Execute o comando que recupera esse subconjunto de usuários do diretório. Confirme se a saída inclui os atributos dos usuários que serão usados para correspondência com o Microsoft Entra ID. Exemplos desses atributos são ID do funcionário, nome da conta e endereço de email.

    Por exemplo, esse comando produziria um arquivo CSV no diretório do sistema de arquivo atual com o atributo userPrincipalName de cada pessoa no diretório LDAP:

    $out_filename = ".\users.csv"
csvde -f $out_filename -l userPrincipalName,cn -r "(objectclass=person)"

  3. Se necessário, transfira o arquivo CSV que contém a lista de usuários para um sistema que tem os cmdlets do PowerShell do Microsoft Graph instalados.

  4. Continue lendo no Confirmar se o Microsoft Entra ID tem usuários que correspondem aos usuários do aplicativo mais adiante neste artigo.

Coletar usuários existentes de uma tabela do banco de dados do aplicativo usando um assistente do SQL Server

Esta seção é válida a aplicativos que usam o SQL Server como armazenamento de dados subjacente.

Primeiro, obtenha uma lista dos usuários nas tabelas. A maioria dos bancos de dados fornece uma maneira de exportar o conteúdo das tabelas para um formato de arquivo padrão, como um arquivo CSV. Se o aplicativo usar um banco de dados do SQL Server, você poderá usar o Assistente de Importação e Exportação do SQL Server para exportar partes de um banco de dados. Caso não tenha um utilitário no seu banco de dados, você poderá usar o driver ODBC com o PowerShell, conforme descrito na próxima seção.

  1. Faça logon no sistema onde o SQL Server está instalado.
  2. Abra a Importação e Exportação do SQL Server 2019 (64 bits) ou equivalente para seu banco de dados.
  3. Selecione o banco de dados existente como a origem.
  4. Em Destino, selecione Destino de Arquivo Simples. Forneça um nome de arquivo e altere o valor de Página de código para 65001 (UTF-8).
  5. Conclua o assistente e selecione a opção para executar imediatamente.
  6. Aguarde a conclusão da execução.
  7. Se necessário, transfira o arquivo CSV que contém a lista de usuários para um sistema que tem os cmdlets do PowerShell do Microsoft Graph instalados.
  8. Continue lendo no Confirmar se o Microsoft Entra ID tem usuários que correspondem aos usuários do aplicativo mais adiante neste artigo.

Coletar usuários existentes da tabela do banco de dados do aplicativo usando o PowerShell

Esta seção e válida para aplicativos que usam outro banco de dados SQL como armazenamento de dados subjacente, em que o Host do Conector ECMA é usado para provisionar usuários nesse aplicativo. Caso ainda não tenha configurado o agente de provisionamento, use este guia para criar o arquivo de conexão DSN que você usará nesta seção.

  1. Faça logon no sistema em que o agente de provisionamento está ou será instalado.

  2. Abra o PowerShell.

  3. Construa uma cadeia de conexão para se conectar ao sistema de banco de dados.

    Os componentes da cadeia de conexão dependerão dos requisitos do seu banco de dados. Se você estiver usando o SQL Server, confira a lista de DSN e atributos e palavras-chave de cadeia de conexão.

    Se você estiver usando um banco de dados diferente, precisará incluir as palavras-chave obrigatórias para se conectar a esse banco de dados. Por exemplo, se o banco de dados usar o nome de caminho totalmente qualificado do arquivo DSN, uma ID de usuário e uma senha, construa a cadeia de conexão usando os seguintes comandos:

    $filedsn = "c:\users\administrator\documents\db.dsn"
$db_cs = "filedsn=" + $filedsn + ";uid=p;pwd=secret"

  4. Abra uma conexão com o seu banco de dados e forneça essa cadeia de conexão usando os seguintes comandos:

    $db_conn = New-Object data.odbc.OdbcConnection
$db_conn.ConnectionString = $db_cs
$db_conn.Open()

  5. Construa uma consulta SQL para recuperar os usuários da tabela de banco de dados. Inclua as colunas que serão usadas para fazer a correspondência dos usuários no banco de dados do aplicativo com esses usuários no Microsoft Entra ID. As colunas podem incluir ID do funcionário, nome da conta ou endereço de email.

    Por exemplo, se os usuários estiverem incluídos em uma tabela de banco de dados de nome USERS que tiver as colunas name e email, digite o seguinte comando:

    $db_query = "SELECT name,email from USERS"

  6. Envie a consulta para o banco de dados por meio da conexão:

    $result = (new-object data.odbc.OdbcCommand($db_query,$db_conn)).ExecuteReader()
$table = new-object System.Data.DataTable
$table.Load($result)

    O resultado é a lista de linhas que representa os usuários que foram recuperados da consulta.

  7. Escreva o resultado em um arquivo CSV:

    $out_filename = ".\users.csv"
$table.Rows | Export-Csv -Path $out_filename -NoTypeInformation -Encoding UTF8

  8. Se esse sistema não tiver os cmdlets do PowerShell do Microsoft Graph instalados ou não tiver conectividade com o Microsoft Entra ID, transfira o arquivo CSV que contém a lista de usuários para um sistema que tenha os cmdlets do PowerShell do Microsoft Graph instalados.

Coletar usuários existentes do SAP Cloud Identity Services

Esta seção se aplica a aplicativos SAP que usam o SAP Cloud Identity Services como o serviço subjacente para provisionamento de usuário.

  1. Entre no console de administrador do SAP Cloud Identity Services, https://<tenantID>.accounts.ondemand.com/admin ou https://<tenantID>.trial-accounts.ondemand.com/admin se for uma avaliação.
  2. Navegue até Usuários e Autorizações > Exportar Usuários.
  3. Selecione todos os atributos necessários para fazer a correspondência dos usuários do Microsoft Entra com os do SAP. Isso inclui SCIM ID, userName e emails e outros atributos que você pode estar usando em seus Sistemas SAP.
  4. Selecione Exportar e aguarde o navegador baixar o arquivo CSV.
  5. Se esse sistema não tiver os cmdlets do PowerShell do Microsoft Graph instalados ou não tiver conectividade com o Microsoft Entra ID, transfira o arquivo CSV que contém a lista de usuários para um sistema que tenha os cmdlets do PowerShell do Microsoft Graph instalados.

Confirmar se o Microsoft Entra ID tem usuários que correspondem aos usuários do aplicativo

Agora que você tem uma lista de todos os usuários obtidos do aplicativo, você poderá fazer a correspondência desses usuários do armazenamento de dados do aplicativo com os usuários no Microsoft Entra ID.

Antes de prosseguir, examine as informações sobre a correspondência de usuários nos sistemas de origem e de destino. Você configurará o provisionamento do Microsoft Entra com mapeamentos equivalentes posteriormente. Essa etapa permitirá que o provisionamento do Microsoft Entra consulte o armazenamento de dados do aplicativo com as mesmas regras de correspondência.

Recuperar as IDs dos usuários no Microsoft Entra ID

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

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:

  • Administrador de Usuário, caso preveja a criação de usuários.
  • Administrador de aplicativos ou Administrador de governança de identidade, caso esteja apenas gerenciando atribuições de função de aplicativos.

  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.Users 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.

  5. Leia a lista de usuários obtida do armazenamento de dados do aplicativo na sessão do PowerShell. Se a lista de usuários estiver em um arquivo CSV, você poderá usar o cmdlet Import-Csv do PowerShell e fornecer o nome do arquivo da seção anterior como argumento.

    Por exemplo, se você tiver um arquivo chamado Users-exported-from-sap.csv que foi obtido do SAP Cloud Identity Services e ele estiver localizado no diretório atual, insira este comando.

    $filename = ".\Users-exported-from-sap.csv"
$dbusers = Import-Csv -Path $filename -Encoding UTF8

    Nesse outro exemplo: se você estiver usando um banco de dados ou diretório e o arquivo se chamar users.csv e também estiver localizado no diretório atual, insira este comando:

    $filename = ".\users.csv"
$dbusers = Import-Csv -Path $filename -Encoding UTF8

  6. Escolha a coluna do arquivo users.csv que corresponderá a um atributo de um usuário no Microsoft Entra ID.

    E se você estiver usando o SAP Cloud Identity Services, o mapeamento padrão será o atributo userName do SAP SCIM com o atributo userPrincipalName do Microsoft Entra ID:

    $db_match_column_name = "userName"
$azuread_match_attr_name = "userPrincipalName"

    Outro exemplo seria se você estiver usando um banco de dados ou diretório, pode haver usuários em um banco de dados em que o valor na coluna denominada EMail é o mesmo valor do atributo userPrincipalName do Microsoft Entra:

    $db_match_column_name = "EMail"
$azuread_match_attr_name = "userPrincipalName"

  7. Recupere as IDs desses usuários no Microsoft Entra ID.

    O script do PowerShell a seguir usa os valores $dbusers, $db_match_column_name e $azuread_match_attr_name especificados anteriormente. Ele consultará o Microsoft Entra ID para localizar um usuário que tenha um atributo com um valor correspondente para cada registro no arquivo de origem. Se o arquivo obtido do SAP Cloud Identity Services, do banco de dados ou do diretório tiver muitos usuários, prepare-se para aguardar alguns minutos até que o script seja concluído. Se você não tiver um atributo no Microsoft Entra ID que tenha o valor e precisar usar contains ou outra expressão de filtro, será necessário personalizar esse script e o da etapa 11 abaixo para usar uma expressão de filtro diferente.

    $dbu_not_queried_list = @()
$dbu_not_matched_list = @()
$dbu_match_ambiguous_list = @()
$dbu_query_failed_list = @()
$azuread_match_id_list = @()
$azuread_not_enabled_list = @()
$dbu_values = @()
$dbu_duplicate_list = @()

foreach ($dbu in $dbusers) { 
   if ($null -ne $dbu.$db_match_column_name -and $dbu.$db_match_column_name.Length -gt 0) { 
      $val = $dbu.$db_match_column_name
      $escval = $val -replace "'","''"
      if ($dbu_values -contains $escval) { $dbu_duplicate_list += $dbu; continue } else { $dbu_values += $escval }
      $filter = $azuread_match_attr_name + " eq '" + $escval + "'"
      try {
         $ul = @(Get-MgUser -Filter $filter -All -Property Id,accountEnabled -ErrorAction Stop)
         if ($ul.length -eq 0) { $dbu_not_matched_list += $dbu; } elseif ($ul.length -gt 1) {$dbu_match_ambiguous_list += $dbu } else {
            $id = $ul[0].id; 
            $azuread_match_id_list += $id;
            if ($ul[0].accountEnabled -eq $false) {$azuread_not_enabled_list += $id }
         } 
      } catch { $dbu_query_failed_list += $dbu } 
    } else { $dbu_not_queried_list += $dbu }
}

  8. Exiba os resultados das consultas anteriores. Veja se algum do usuário que está no SAP Cloud Identity Services, no banco de dados ou no diretório não pôde ser encontrado no Microsoft Entra ID, devido a erros ou correspondências faltando.

    O seguinte script do PowerShell exibirá as contagens de registros que não foram localizados:

    $dbu_not_queried_count = $dbu_not_queried_list.Count
if ($dbu_not_queried_count -ne 0) {
  Write-Error "Unable to query for $dbu_not_queried_count records as rows lacked values for $db_match_column_name."
}
$dbu_duplicate_count = $dbu_duplicate_list.Count
if ($dbu_duplicate_count -ne 0) {
  Write-Error "Unable to locate Microsoft Entra ID users for $dbu_duplicate_count rows as multiple rows have the same value"
}
$dbu_not_matched_count = $dbu_not_matched_list.Count
if ($dbu_not_matched_count -ne 0) {
  Write-Error "Unable to locate $dbu_not_matched_count records in Microsoft Entra ID by querying for $db_match_column_name values in $azuread_match_attr_name."
}
$dbu_match_ambiguous_count = $dbu_match_ambiguous_list.Count
if ($dbu_match_ambiguous_count -ne 0) {
  Write-Error "Unable to locate $dbu_match_ambiguous_count records in Microsoft Entra ID as attribute match ambiguous."
}
$dbu_query_failed_count = $dbu_query_failed_list.Count
if ($dbu_query_failed_count -ne 0) {
  Write-Error "Unable to locate $dbu_query_failed_count records in Microsoft Entra ID as queries returned errors."
}
$azuread_not_enabled_count = $azuread_not_enabled_list.Count
if ($azuread_not_enabled_count -ne 0) {
 Write-Error "$azuread_not_enabled_count users in Microsoft Entra ID are blocked from sign-in."
}
if ($dbu_not_queried_count -ne 0 -or $dbu_duplicate_count -ne 0 -or $dbu_not_matched_count -ne 0 -or $dbu_match_ambiguous_count -ne 0 -or $dbu_query_failed_count -ne 0 -or $azuread_not_enabled_count) {
 Write-Output "You will need to resolve those issues before access of all existing users can be reviewed."
}
$azuread_match_count = $azuread_match_id_list.Count
Write-Output "Users corresponding to $azuread_match_count records were located in Microsoft Entra ID."

  9. Quando o script for concluído, ele indicará um erro se houver registros da fonte de dados não localizados no Microsoft Entra ID. Se nem todos os registros de usuários do armazenamento de dados do aplicativo puderem ser localizados no Microsoft Entra ID, será necessário investigar os registros que não corresponderam e por quê.

    Por exemplo, o endereço de email e o userPrincipalName de alguém podem ter sido alterados no Microsoft Entra ID sem que a propriedade mail correspondente tenha sido atualizada na fonte de dados do aplicativo. Ou talvez o usuário já tenha deixado a organização, mas ainda continue na fonte de dados do aplicativo. Ou pode haver uma conta de fornecedor ou de superadministrador na fonte de dados do aplicativo que não corresponda a nenhuma pessoa específica no Microsoft Entra ID.

  10. Se houver usuários que não foram localizados no Microsoft Entra ID ou que não estavam ativos e prontos para entrar, mas você quer que eles tenham o acesso revisado ou seus atributos atualizados no SAP Cloud Identity Services, no banco de dados ou no diretório, você precisará atualizar o aplicativo ou a regra de correspondência, ou então atualizar ou criar usuários do Microsoft Entra para eles. Para mais informações sobre quais alterações fazer, confira gerenciar mapeamentos e contas de usuário em aplicativos que encontraram correspondência com os usuários no Microsoft Entra ID.

    Se você optar por criar usuários no Microsoft Entra ID, poderá criar usuários em massa usando:

    Verifique se os novos usuários foram preenchidos com os atributos necessários para que o Microsoft Entra ID combine-os posteriormente com os usuários existentes no aplicativo e com os atributos exigidos pelo Microsoft Entra ID, incluindo userPrincipalName, mailNickname e displayName. O userPrincipalName deve ser único entre todos os usuários no diretório.

    Por exemplo, é possível ter usuários em um banco de dados em que o valor na coluna EMail é o valor que você quer usar como o nome UPN do Microsoft Entra, o valor na coluna Alias contém o apelido de email do Microsoft Entra ID e o valor na coluna Full name contém o nome de exibição do usuário:

    $db_display_name_column_name = "Full name"
$db_user_principal_name_column_name = "Email"
$db_mail_nickname_column_name = "Alias"

    Depois, você pode usar este script para criar usuários do Microsoft Entra para aqueles que estão no SAP Cloud Identity Services, no banco de dados ou no diretório que não correspondem aos usuários no Microsoft Entra ID. Observe que talvez seja necessário modificar esse script para adicionar outros atributos do Microsoft Entra necessários em sua organização ou, se $azuread_match_attr_name não for mailNickname nem userPrincipalName, para fornecer esse atributo do Microsoft Entra.

    $dbu_missing_columns_list = @()
$dbu_creation_failed_list = @()
foreach ($dbu in $dbu_not_matched_list) {
   if (($null -ne $dbu.$db_display_name_column_name -and $dbu.$db_display_name_column_name.Length -gt 0) -and
       ($null -ne $dbu.$db_user_principal_name_column_name -and $dbu.$db_user_principal_name_column_name.Length -gt 0) -and
       ($null -ne $dbu.$db_mail_nickname_column_name -and $dbu.$db_mail_nickname_column_name.Length -gt 0)) {
      $params = @{
         accountEnabled = $false
         displayName = $dbu.$db_display_name_column_name
         mailNickname = $dbu.$db_mail_nickname_column_name
         userPrincipalName = $dbu.$db_user_principal_name_column_name
         passwordProfile = @{
           Password = -join (((48..90) + (96..122)) * 16 | Get-Random -Count 16 | % {[char]$_})
         }
      }
      try {
        New-MgUser -BodyParameter $params
      } catch { $dbu_creation_failed_list += $dbu; throw }
   } else {
      $dbu_missing_columns_list += $dbu
   }
}

  11. Quando adicionar os usuários ausentes ao Microsoft Entra ID, execute o script da etapa 7 novamente. Em seguida, execute o script da etapa 8. Verifique se não há nenhum erro relatado.

    $dbu_not_queried_list = @()
$dbu_not_matched_list = @()
$dbu_match_ambiguous_list = @()
$dbu_query_failed_list = @()
$azuread_match_id_list = @()
$azuread_not_enabled_list = @()
$dbu_values = @()
$dbu_duplicate_list = @()

foreach ($dbu in $dbusers) { 
   if ($null -ne $dbu.$db_match_column_name -and $dbu.$db_match_column_name.Length -gt 0) { 
      $val = $dbu.$db_match_column_name
      $escval = $val -replace "'","''"
      if ($dbu_values -contains $escval) { $dbu_duplicate_list += $dbu; continue } else { $dbu_values += $escval }
      $filter = $azuread_match_attr_name + " eq '" + $escval + "'"
      try {
         $ul = @(Get-MgUser -Filter $filter -All -Property Id,accountEnabled -ErrorAction Stop)
         if ($ul.length -eq 0) { $dbu_not_matched_list += $dbu; } elseif ($ul.length -gt 1) {$dbu_match_ambiguous_list += $dbu } else {
            $id = $ul[0].id; 
            $azuread_match_id_list += $id;
            if ($ul[0].accountEnabled -eq $false) {$azuread_not_enabled_list += $id }
         } 
      } catch { $dbu_query_failed_list += $dbu } 
    } else { $dbu_not_queried_list += $dbu }
}

$dbu_not_queried_count = $dbu_not_queried_list.Count
if ($dbu_not_queried_count -ne 0) {
  Write-Error "Unable to query for $dbu_not_queried_count records as rows lacked values for $db_match_column_name."
}
$dbu_duplicate_count = $dbu_duplicate_list.Count
if ($dbu_duplicate_count -ne 0) {
  Write-Error "Unable to locate Microsoft Entra ID users for $dbu_duplicate_count rows as multiple rows have the same value"
}
$dbu_not_matched_count = $dbu_not_matched_list.Count
if ($dbu_not_matched_count -ne 0) {
  Write-Error "Unable to locate $dbu_not_matched_count records in Microsoft Entra ID by querying for $db_match_column_name values in $azuread_match_attr_name."
}
$dbu_match_ambiguous_count = $dbu_match_ambiguous_list.Count
if ($dbu_match_ambiguous_count -ne 0) {
  Write-Error "Unable to locate $dbu_match_ambiguous_count records in Microsoft Entra ID as attribute match ambiguous."
}
$dbu_query_failed_count = $dbu_query_failed_list.Count
if ($dbu_query_failed_count -ne 0) {
  Write-Error "Unable to locate $dbu_query_failed_count records in Microsoft Entra ID as queries returned errors."
}
$azuread_not_enabled_count = $azuread_not_enabled_list.Count
if ($azuread_not_enabled_count -ne 0) {
 Write-Warning "$azuread_not_enabled_count users in Microsoft Entra ID are blocked from sign-in."
}
if ($dbu_not_queried_count -ne 0 -or $dbu_duplicate_count -ne 0 -or $dbu_not_matched_count -ne 0 -or $dbu_match_ambiguous_count -ne 0 -or $dbu_query_failed_count -ne 0 -or $azuread_not_enabled_count -ne 0) {
 Write-Output "You will need to resolve those issues before access of all existing users can be reviewed."
}
$azuread_match_count = $azuread_match_id_list.Count
Write-Output "Users corresponding to $azuread_match_count records were located in Microsoft Entra ID."

Registrar o aplicativo

Se o aplicativo já estiver registrado no Microsoft Entra ID, continue para a próxima etapa.

Verificar se há usuários que ainda não estão atribuídos ao aplicativo

As etapas anteriores confirmaram que todos os usuários no armazenamento de dados do aplicativo existem como usuários no Microsoft Entra ID. No entanto, pode ser que nem todos tenham as funções do aplicativo atribuídas no Microsoft Entra ID. Portanto, as próximas etapas se destinam a ver os usuários que não têm atribuições de funções de aplicativo.

  1. Procure a ID da entidade de serviço para a entidade de serviço do aplicativo. Caso tenha criado recentemente uma entidade de serviço para um aplicativo que usa um diretório do LDAP ou um banco de dados SQL, use o nome dessa entidade de serviço.

    Por exemplo, se o nome do aplicativo empresarial for CORPDB1, digite os seguintes comandos:

    $azuread_app_name = "CORPDB1"
$azuread_sp_filter = "displayName eq '" + ($azuread_app_name -replace "'","''") + "'"
$azuread_sp = Get-MgServicePrincipal -Filter $azuread_sp_filter -All

  2. Recupere os usuários que atualmente têm atribuições para o aplicativo no Microsoft Entra ID.

    Isso se baseia na variável $azuread_sp definida no comando anterior.

    $azuread_existing_assignments = @(Get-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $azuread_sp.Id -All)

  3. Compare a lista de IDs de usuário da seção anterior com os usuários atribuídos atualmente ao aplicativo:

    $azuread_not_in_role_list = @()
foreach ($id in $azuread_match_id_list) {
   $found = $false
   foreach ($existing in $azuread_existing_assignments) {
      if ($existing.principalId -eq $id) {
         $found = $true; break;
      }
   }
   if ($found -eq $false) { $azuread_not_in_role_list += $id }
}
$azuread_not_in_role_count = $azuread_not_in_role_list.Count
Write-Output "$azuread_not_in_role_count users in the application's data store are not assigned to the application roles."

    Se nenhum usuário estiver atribuído a funções do aplicativo, indicando que todos os usuários estão atribuídos a funções do aplicativo, você não precisará fazer mais alterações antes de realizar uma revisão de acesso.

    No entanto, se houver um ou mais usuários sem a atribuição de funções do aplicativo, será preciso continuar o procedimento e adicioná-los a uma das funções do aplicativo.

  4. Selecione a função do aplicativo a ser atribuída aos usuários restantes.

    Um aplicativo pode ter mais de uma função e uma entidade de serviço pode ter funções adicionais. Use este comando para listar as funções disponíveis de uma entidade de serviço:

    $azuread_sp.AppRoles | where-object {$_.AllowedMemberTypes -contains "User"} | ft DisplayName,Id

    Selecione a função apropriada na lista e obtenha sua ID de função. Por exemplo, se o nome da função for Admin, forneça esse valor nos seguintes comandos do PowerShell:

    $azuread_app_role_name = "Admin"
$azuread_app_role_id = ($azuread_sp.AppRoles | where-object {$_.AllowedMemberTypes -contains "User" -and $_.DisplayName -eq $azuread_app_role_name}).Id
if ($null -eq $azuread_app_role_id) { write-error "role $azuread_app_role_name not located in application manifest"}

Configurar o provisionamento de aplicativo

Se o aplicativo usar um diretório LDAP, um banco de dados SQL, SAP Cloud Identity Services ou der suporte a SCIM, antes de criar atribuições, configure o provisionamento de usuários do Microsoft Entra para o aplicativo. Configurar o provisionamento antes de criar atribuições permitirá que o Microsoft Entra ID faça a correspondência dos usuários no Microsoft Entra ID com as atribuições de função de aplicativo para os usuários que já estão no armazenamento de dados do aplicativo. Se o aplicativo tiver um diretório ou banco de dados local a ser provisionado e também der suporte ao SSO federado, talvez você precise de duas entidades de serviço para representar o aplicativo em seu diretório: uma para provisionamento e outra para SSO. Se o aplicativo não der suporte ao provisionamento, continue lendo na próxima seção.

  1. Verifique se o aplicativo está configurado para exigir que os usuários tenham atribuições de função de aplicativo, para que somente usuários selecionados sejam provisionados no aplicativo.

  2. Se o provisionamento não tiver sido configurado para o aplicativo, configure-o agora (mas não inicie o provisionamento):

  3. Confira a guia Propriedades do aplicativo. Verifique se a opção Atribuição de usuário necessária? está definida como Sim. Se ela estiver definida como Não, todos os usuários no diretório, incluindo as identidades externas, poderão acessar o aplicativo e você não poderá revisar o acesso a ele.

  4. Verifique os mapeamentos de atributo para provisionar para esse aplicativo. Verifique se Fazer correspondência dos objetos usando esse atributo está definido para o atributo do Microsoft Entra e a coluna que você usou nas seções acima para a correspondência.

    Se essas regras não estiverem usando os mesmos atributos usados anteriormente, quando as atribuições de função de aplicativo forem criadas, talvez o Microsoft Entra ID não consiga localizar usuários existentes no armazenamento de dados do aplicativo. Com isso, o Microsoft Entra ID pode criar inadvertidamente usuários duplicados.

  5. Verifique se há um mapeamento de atributo de isSoftDeleted para um atributo do aplicativo.

    Quando um usuário tiver a atribuição removida do aplicativo, for excluído de maneira reversível no Microsoft Entra ID ou tiver a entrada bloqueada, o provisionamento do Microsoft Entra atualizará o atributo mapeado para isSoftDeleted. Se nenhum atributo for mapeado, os usuários que tiverem posteriormente a atribuição removida da função de aplicativo continuarão a existir no armazenamento de dados do aplicativo.

  6. Se o provisionamento já tiver sido habilitado para o aplicativo, verifique se o provisionamento de aplicativos não está em quarentena. Resolva os problemas que estão causando a quarentena antes de prosseguir.

Criar atribuições de função de aplicativo no Microsoft Entra ID

Para que o Microsoft Entra ID corresponda os usuários no aplicativo com os usuários do Microsoft Entra ID, você precisa criar atribuições de função de aplicativo no Microsoft Entra ID. Cada atribuição de função de aplicativo associa um usuário a uma função de aplicativo de uma entidade de serviço.

Quando uma atribuição de função de aplicativo é criada no Microsoft Entra ID para um usuário a um aplicativo, e o aplicativo dá suporte ao provisionamento, então:

  • O Microsoft Entra ID consultará o aplicativo via SCIM, ou seu diretório ou banco de dados, para determinar se o usuário já existe.
  • Quando houver atualizações dos atributos do usuário no Microsoft Entra ID elas serão enviadas ao aplicativo.
  • O usuário permanecerá no aplicativo indefinidamente, a não ser que haja atualização fora do Microsoft Entra ID ou a atribuição seja removida do Microsoft Entra ID.
  • Na próxima revisão de acesso das atribuições de função desse aplicativo, o usuário será incluído.
  • Se o usuário for negado em uma revisão de acesso, a atribuição de função de aplicativo dele será removida. O Microsoft Entra ID notificará o aplicativo de que o usuário está impedido de entrar.

Se o aplicativo não der suporte ao provisionamento, então

  • O usuário permanecerá no aplicativo indefinidamente, a não ser que haja atualização fora do Microsoft Entra ID ou a atribuição seja removida do Microsoft Entra ID.
  • Na próxima revisão das atribuições de função desse aplicativo, o usuário será incluído na revisão.
  • Se o usuário for negado em uma revisão de acesso, a atribuição de função de aplicativo dele será removida. O usuário não poderá mais entrar do Microsoft Entra ID no aplicativo.

  1. Crie atribuições de função de aplicativo para usuários que não têm atribuições de função no momento:

    foreach ($u in $azuread_not_in_role_list) {
   $res = New-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $azuread_sp.Id -AppRoleId $azuread_app_role_id -PrincipalId $u -ResourceId $azuread_sp.Id 
}

  2. Aguarde um minuto para que as alterações sejam propagadas no Microsoft Entra ID.

Verifique se o provisionamento do Microsoft Entra fez a correspondência dos usuários existentes

  1. Consulte novamente o Microsoft Entra ID para obter a lista atualizada de atribuições de função:

    $azuread_existing_assignments = @(Get-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $azuread_sp.Id -All)

  2. Compare a lista de IDs de usuário da seção anterior com os usuários atribuídos atualmente ao aplicativo:

    $azuread_still_not_in_role_list = @()
foreach ($id in $azuread_match_id_list) {
   $found = $false
   foreach ($existing in $azuread_existing_assignments) {
      if ($existing.principalId -eq $id) {
         $found = $true; break;
      }
   }
   if ($found -eq $false) { $azuread_still_not_in_role_list += $id }
}
$azuread_still_not_in_role_count = $azuread_still_not_in_role_list.Count
if ($azuread_still_not_in_role_count -gt 0) {
   Write-Output "$azuread_still_not_in_role_count users in the application's data store are not assigned to the application roles."
}

    Se algum usuário não tiver funções do aplicativo atribuídas, verifique o log de auditoria do Microsoft Entra para obter um erro de uma etapa anterior.

  3. Se a entidade de serviço de aplicativo for configurada para provisionamento e o Status de Provisionamento da entidade de serviço estiver Desativado, altere-o para Ativado. Você também pode iniciar o provisionamento usando APIs do Graph.

  4. Com base nas diretrizes de quanto tempo levará para provisionar os usuários, aguarde até que o provisionamento do Microsoft Entra faça a correspondência dos usuários existentes do aplicativo com os usuários que acabaram de ser atribuídos.

  5. Monitore o status de provisionamento por meio do portal ou das APIs do Graph para garantir que todos os usuários tenham sido correspondidos com êxito.

    Se você não vir usuários sendo provisionados, verifique o guia de solução de problemas para o caso em que nenhum usuário é provisionado. Se você vir um erro no status de provisionamento e estiver provisionando para um aplicativo local, verifique o guia de solução de problemas para provisionamento de aplicativo local.

  6. Verifique o log de provisionamento no Centro de administração do Microsoft Entra ou nas APIs do Graph. Filtre o log para o status Falha. Se houver falhas com um ErrorCode de DuplicateTargetEntries, será uma indicação de ambiguidade nas regras de correspondência de provisionamento, e você precisará atualizar os usuários do Microsoft Entra ou os mapeamentos usados para correspondência a fim de garantir que cada usuário do Microsoft Entra corresponda a um usuário do aplicativo. Depois, filtre o log para a ação Criar e o status Ignorado. Se os usuários foram ignorados com o código SkipReason de NotEffectivelyEntitled, pode indicar que não foram encontradas correspondências das contas de usuário no Microsoft Entra ID porque o status da conta de usuário estada Desabilitado.

Depois que o serviço de provisionamento do Microsoft Entra tiver feito a correspondência dos usuários com base nas atribuições de função de aplicativo criado, as alterações subsequentes a esses usuários serão enviadas para o aplicativo.

Selecionar os revisores apropriados

Quando você cria uma revisão de acesso, os administradores podem escolher um ou mais revisores. Todos os revisores podem iniciar e executar uma revisão escolhendo usuários para acesso contínuo a um recurso ou removendo-os.

Normalmente, um proprietário de recurso é responsável por executar uma revisão. Ao criar uma revisão de grupo durante a revisão do acesso de um aplicativo integrado ao padrão B, você poderá selecionar os proprietários do grupo como revisores. Como os aplicativos no Microsoft Entra ID não têm necessariamente um proprietário, não é possível selecionar o proprietário do aplicativo como revisor. Nesse caso, ao criar a revisão, você pode fornecer os nomes dos proprietários do aplicativo para serem os revisores.

Ao criar uma revisão de um grupo ou de um aplicativo, você também pode optar por fazer uma revisão em várias fases. Por exemplo, você pode selecionar que o gerente de cada usuário atribuído execute a primeira fase da revisão e o proprietário do recurso execute a segunda fase. Dessa forma, o proprietário do recurso pode se concentrar nos usuários que já foram aprovados pelo gerente.

Antes de criar as revisões, verifique se você tem estações suficientes do Microsoft Entra ID P2 ou do SKU do Microsoft Entra ID Governance em seu locatário. Além disso, verifique se todos os revisores são usuários ativos com endereços de email. Quando as revisões de acesso começarem, cada um deles revisará um email do Microsoft Entra ID. Se o revisor não tiver uma caixa de correio, ele não receberá o email quando a revisão for iniciada nem um lembrete por email. E, se eles forem impedidos de entrar no Microsoft Entra ID, não poderão executar a revisão.

Configurar revisões de acesso ou gerenciamento de direitos

Depois que os usuários estiverem nas funções de aplicativo e você tiver os revisores identificados, você poderá controlar esses usuários e quaisquer usuários adicionais que precisarão de acesso usando revisão de acesso ou gerenciamento de direitos.

  • Se o aplicativo tiver apenas uma única função de aplicativo, o aplicativo será representado por uma única entidade de serviço em seu diretório e nenhum usuário adicional precisará acessar o aplicativo. Depois, continue com a próxima seção para revisar e remover o acesso existente usando uma revisão de acesso.
  • Caso contrário, continue na seção deste artigo para controlar o acesso usando o gerenciamento de direitos.

Revisar e remover o acesso existente usando uma revisão de acesso de atribuições de função do aplicativo

Se o aplicativo tiver várias funções de aplicativo, for representado por várias entidades de serviço ou se você quiser ter um processo para que os usuários solicitem ou recebam acesso ao aplicativo, continue na seção a seguir deste artigo para controlar o acesso usando o gerenciamento de direitos.

Agora que os usuários existentes têm atribuições para uma função de aplicativo, você pode configurar o Microsoft Entra ID para iniciar uma revisão dessas atribuições.

  1. Para esta etapa, você precisará estar na função de Administrador Global ou de Administrador de Governança de Identidade.

  2. Siga as instruções na guia para criar uma revisão de acesso de grupos ou aplicativos, para criar a revisão das atribuições de função de aplicativo. Configure a revisão para aplicar resultados quando ela for concluída. Você pode criar a revisão de acesso no PowerShell com o cmdlet New-MgIdentityGovernanceAccessReviewDefinition do módulo cmdlets do Microsoft Graph PowerShell para governança de identidade. Para obter mais informações, consulte os exemplos.

    Observação

    Se você habilitar os auxiliares de decisão de revisão ao criar a revisão de acesso, as recomendações do auxiliar de decisão serão baseadas no período de intervalo de 30 dias, dependendo de quando o usuário entrou no aplicativo pela última vez usando o Microsoft Entra ID.

  3. Quando a revisão de acesso começar, solicite que os revisores enviem opiniões. Por padrão, cada um recebe um email do Microsoft Entra ID com um link para o painel de acesso, onde ele revisará o acesso ao aplicativo.

  4. Depois que as revisões forem iniciadas, você poderá monitorar o progresso e atualizar os aprovadores, se necessário, até que a revisão de acesso seja concluída. Depois, você poderá confirmar os usuários cujo acesso foi negado pelos revisores tiveram o acesso removido do aplicativo.

  5. Se a aplicação automática não for selecionada quando a revisão for criada, você precisará aplicar os resultados da revisão quando ela for concluída.

  6. Aguarde até que o status da revisão seja alterado para Resultado aplicado. Você deverá ver usuários negados, se houver, tendo suas atribuições de função de aplicativo sendo removidas em alguns minutos.

  7. Depois que os resultados forem aplicados, o Microsoft Entra ID começará a desprovisionar usuários negados do aplicativo. Com base na orientação de quanto tempo levará para provisionar usuários, aguarde até que o provisionamento do Microsoft Entra comece a desprovisionar os usuários negados. Monitore o status de provisionamento por meio do portal ou das APIs do Graph para garantir que todos os usuários negados tenham sido removidos com êxito.

    Se você não vir usuários sendo desprovisionados, verifique o guia de solução de problemas para o caso em que nenhum usuário é provisionado. Se você vir um erro no status de provisionamento e estiver provisionando para um aplicativo local, verifique o guia de solução de problemas para provisionamento de aplicativo local.

Agora que você tem uma linha de base que garante que o acesso existente foi revisado, você pode continuar na próxima seção para configurar o gerenciamento de direitos, para habilitar novas solicitações de acesso.

Controlar o acesso usando o gerenciamento de direitos

Em outras situações, como querer ter revisores diferentes para cada função de aplicativo, o aplicativo é representado por várias entidades de serviço ou se desejar ter um processo para que os usuários solicitem ou sejam atribuídos acesso ao aplicativo, então configure o Microsoft Entra ID com um pacote de acesso para cada função de aplicativo. Cada pacote de acesso pode ter uma política para revisão recorrente das atribuições feitas a esse pacote de acesso. Depois que os pacotes de acesso e as políticas forem criados, você poderá atribuir os usuários que têm atribuições de função de aplicativo existentes aos pacotes de acesso, para que suas atribuições possam ser revisadas pelo pacote de acesso.

Nesta seção, você configurará o gerenciamento de direitos do Microsoft Entra para obter uma revisão das atribuições do pacote de acesso que contêm as atribuições de função do aplicativo, além de configurar políticas adicionais para que os usuários possam solicitar acesso às funções de aplicativo.

  1. Para esta etapa, você precisará estar na função de Administrador Global ou Administrador de Governança de Identidade, ou ser delegado como criador de catálogos e proprietário do aplicativo.
  2. Se você ainda não tiver um catálogo para o cenário de governança de aplicativos, crie um catálogo no gerenciamento de direitos do Microsoft Entra. Você pode usar um script do PowerShell para criar cada catálogo.
  3. Propague o catálogo com os recursos necessários, adicionando o aplicativo e todos os grupos do Microsoft Entra dos quais o aplicativo depende, como recursos nesse catálogo. Você pode usar um script do PowerShell para adicionar cada recurso a um catálogo.
  4. Para cada um dos aplicativos e para cada uma das funções ou dos grupos de aplicativos, crie um pacote de acesso que inclua essa função ou grupo como recurso. Nesta fase da configuração desses pacotes de acesso, configure a primeira política de atribuição de pacote de acesso em cada pacote de acesso para que seja uma política de atribuição direta, de modo que somente os administradores possam criar atribuições nessa política, definir os requisitos de revisão de acesso dos usuários existentes, se houver, para que eles não mantenham o acesso indefinidamente. Se tiver muitos pacotes de acesso, você poderá usar um script do PowerShell para criar cada pacote de acesso em um catálogo.
  5. Para cada pacote de acesso, atribua usuários existentes da aplicação nessa função correspondente, ou membros desse grupo, ao pacote de acesso e à sua política de atribuição direta. Você pode atribuir diretamente um pacote de acesso a um usuário usando o centro de administração do Microsoft Entra, ou atribuir em massa usando o Graph ou o PowerShell.
  6. Se você configurou revisões de acesso nas políticas de atribuição do pacote de acesso, quando a revisão de acesso for iniciada, peça aos revisores que forneçam entrada. Por padrão, cada um recebe um email do Microsoft Entra ID com um link para o painel de acesso, onde revisarão as atribuições do pacote de acesso. Quando a revisão for concluída, você deverá ver usuários negados, se houver, tendo suas atribuições da função de aplicativo sendo removidas em alguns minutos. Posteriormente, o Microsoft Entra ID começará a desprovisionar os usuários negados do aplicativo. Com base na orientação de quanto tempo levará para provisionar usuários, aguarde até que o provisionamento do Microsoft Entra comece a desprovisionar os usuários negados. Monitore o status de provisionamento por meio do portal ou das APIs do Graph para garantir que todos os usuários negados tenham sido removidos com êxito.
  7. 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. 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.
  8. Se você quiser permitir que os usuários que ainda não têm acesso solicitem acesso, em cada pacote de acesso, crie políticas adicionais de atribuição de pacote de acesso para que os usuários solicitem acesso. Configure os requisitos de aprovação e revisão de acesso recorrente dessa política.

Próximas etapas