Share via


Provisionamento de entrada controlado por API com script do PowerShell

Este tutorial descreve como usar o script do PowerShell para implementar o provisionamento de entrada controlado por API do Microsoft Entra ID. Usando as etapas neste tutorial, você pode converter um arquivo CSV que contém dados de RH em uma carga de solicitação em massa e enviá-lo para o ponto de extremidade da API de provisionamento /bulkUpload do Microsoft Entra. O artigo também fornece diretrizes sobre como o mesmo padrão de integração pode ser usado com qualquer sistema de registro.

Cenário de integração

Requisito de negócios

Seu sistema de registro gera periodicamente exportações de arquivo CSV que contêm dados de trabalho. Você deseja implementar uma integração que leia dados do arquivo CSV e provisione automaticamente contas de usuário em seu diretório de destino (Active Directory local para usuários híbridos e Microsoft Entra ID para usuários somente na nuvem).

Requisito de implementação

Sob uma perspectiva de implementação:

  • Você deseja usar um script autônomo do PowerShell para ler dados das exportações de arquivo CSV e enviá-los para o ponto de extremidade da API de provisionamento de entrada.
  • No script do PowerShell, você não deseja implementar a lógica complexa de comparação de dados de identidade entre o sistema de registro e o diretório de destino.
  • Você deseja usar o serviço de provisionamento do Microsoft Entra para aplicar suas regras de provisionamento gerenciado de TI para criar/atualizar/habilitar/desabilitar automaticamente contas no diretório de destino (Active Directory local ou Microsoft Entra ID).

Graphic of PowerShell-based integration.

Variações do cenário de integração

Embora este tutorial use um arquivo CSV como um sistema de registro, você pode personalizar o script do PowerShell de exemplo para ler dados de qualquer sistema de registro. Aqui está uma lista de variações do cenário de integração empresarial, em que o provisionamento de entrada controlado por API pode ser implementado com um script do PowerShell.

# Sistema de registro Diretrizes de integração sobre como usar o PowerShell para ler dados de origem
1 Tabela do banco de dados Se você estiver usando um banco de dados SQL do Azure ou um SQL Server local, poderá usar o cmdlet Read-SqlTableData para ler dados armazenados em uma tabela de um banco de dados SQL. Você pode usar o cmdlet Invoke-SqlCmd para executar scripts Transact-SQL ou XQuery.
Se você estiver usando um banco de dados Oracle/MySQL/Postgres, poderá encontrar um módulo do PowerShell publicado pelo fornecedor ou disponível na Galeria do PowerShell. Use o módulo para ler dados da tabela de banco de dados.
2 Servidor LDAP Use a API .NET System.DirectoryServices.Protocols ou um dos módulos LDAP disponíveis na Galeria do PowerShell para consultar o servidor LDAP. Entenda o esquema LDAP e a hierarquia para recuperar dados de usuário do servidor LDAP.
3 Qualquer sistema que exponha APIs REST Para ler dados de um ponto de extremidade da API REST usando o PowerShell, você pode usar o cmdlet Invoke-RestMethod do módulo Microsoft.PowerShell.Utility. Verifique a documentação da API REST e descubra quais parâmetros e cabeçalhos ele espera, qual formato ele retorna e qual método de autenticação ele usa. Em seguida, você pode ajustar o comando Invoke-RestMethod adequadamente.
4 Qualquer sistema que exponha APIs SOAP Para ler dados de um ponto de extremidade da API SOAP usando o PowerShell, você pode usar o cmdlet New-WebServiceProxy do módulo Microsoft.PowerShell.Management. Verifique a documentação da API SOAP e descubra quais parâmetros e cabeçalhos ela espera, qual formato ela retorna e qual método de autenticação ela usa. Em seguida, você pode ajustar o comando New-WebServiceProxy adequadamente.

Depois de ler os dados de origem, aplique suas regras de pré-processamento e converta a saída do sistema de registro em uma solicitação em massa que pode ser enviada ao ponto de extremidade da API bulkUpload de provisionamento do Microsoft Entra.

Importante

Caso queira compartilhar seu script de integração do PowerShell com a comunidade, publique-o na Galeria do PowerShell e notifique-nos sobre o repositório do GitHub entra-id-inbound-provisioning, para que possamos adicioná-lo.

Como usar este tutorial

O script de exemplo do PowerShell publicado no repositório GitHub de provisionamento de entrada do Microsoft Entra automatiza várias tarefas. Ele tem lógica para lidar com arquivos CSV grandes e agrupar a solicitação em massa para enviar 50 registros em cada solicitação. Veja como você pode testá-la e personalizá-la de acordo com seus requisitos de integração.

Observação

O script de exemplo do PowerShell é fornecido "no estado em que se encontra" para referência de implementação. Se você tiver dúvidas relacionadas ao script ou se quiser aprimorá-lo, use o repositório de projetos do GitHub.

# Tarefa de automação Diretrizes de implementação Personalização avançada
1 Leia os dados do trabalho no arquivo CSV. Baixe o script do PowerShell. Ele tem uma lógica pronta para uso para ler dados de qualquer arquivo CSV. Consulte os detalhes de uso do CSV2SCIM PowerShell para se familiarizar com os diferentes modos de execução desse script. Se o sistema de registro for diferente, confira as diretrizes fornecidas na seção Variações do cenário de integração sobre como você pode personalizar o script do PowerShell.
2 Pré-processar e converter dados para o formato SCIM. Por padrão, o script do PowerShell converte cada registro do arquivo CSV em uma representação de Usuário Principal e Usuário Corporativo do SCIM. Siga as etapas da seção Gerar conteúdo de solicitação em massa com esquema padrão para se familiarizar com esse processo. Se o arquivo CSV tiver campos diferentes, ajuste o arquivo AttributeMapping.psd para gerar um usuário SCIM válido. Você também pode gerar solicitações em massa com um esquema SCIM personalizado. Atualize o script do PowerShell para incluir qualquer lógica de validação de dados CSV personalizada.
3 Use um certificado para autenticação no Microsoft Entra ID. Crie uma entidade de serviço que possa acessar a API de provisionamento de entrada. Consulte as etapas na seção Configurar o certificado do cliente para autenticação da entidade de serviço para saber como usar o certificado do cliente para autenticação. Se você quiser usar a identidade gerenciada em vez de uma entidade de serviço para autenticação, examine o uso de Connect-MgGraph no script de exemplo e atualize-o para usar identidades gerenciadas.
4 Provisione contas no Active Directory local ou no Microsoft Entra ID. Configure o aplicativo de provisionamento de entrada controlado por API. Isso gerará um ponto de extremidade exclusivo da API /bulkUpload. Consulte as etapas na seção Gerar e carregar conteúdo de solicitação em massa como usuário administrador para saber como carregar dados para o ponto de extremidade. Valide o fluxo de atributos e personalize os mapeamentos de atributos de acordo com os requisitos de integração. Para executar o script usando uma entidade de serviço com autenticação baseada em certificado, consulte as etapas na seção Carregar conteúdo de solicitação em massa usando autenticação de certificado de cliente Se você planeja usar a solicitação em massa com esquema SCIM personalizado, estenda o esquema do aplicativo de provisionamento para incluir elementos de esquema SCIM personalizados.
5 Examine os logs de provisionamento e tente novamente o provisionamento de registros com falha. Consulte as etapas na seção Obter logs de provisionamento dos últimos ciclos de sincronização para saber como buscar e analisar dados de log de provisionamento. Identifique os registros de usuários com falha e inclua-os no próximo ciclo de upload. -
6 Implante sua automação baseada no PowerShell na produção. Depois de verificar o fluxo de provisionamento controlado por API e personalizar o script do PowerShell para atender aos seus requisitos, você poderá implantar a automação como um runbook de Fluxo de Trabalho do PowerShell na Automação do Azure ou como um processo de servidor agendado para ser executado em um Windows Server. -

Baixar o script do PowerShell

  1. Acesse o repositório GitHub entra-id-inbound-provisioning.
  2. Use a opção Código ->Clone ou Código ->Baixar ZIP para copiar o conteúdo do repositório em sua pasta local.
  3. Navegue até a pasta PowerShell/CSV2SCIM. Ele tem a seguinte estrutura de diretórios:
    • src
      • CSV2SCIM.ps1 (script main)
      • ScimSchemaRepresentations (pasta que contém definições de esquema SCIM padrão para validar arquivos AttributeMapping.psd1)
        • EnterpriseUser.json, Group.json, Schema.json, User.json
    • Exemplos
      • AttributeMapping.psd1 (exemplo de mapeamento de colunas no arquivo CSV para atributos SCIM padrão)
      • csv-with-2-records.csv (exemplo de arquivo CSV com dois registros)
      • csv-with-1000-records.csv (exemplo de arquivo CSV com 1.000 registros)
      • Test-ScriptCommands.ps1 (exemplos de comandos de uso)
      • UseClientCertificate.ps1 (script para gerar certificado autoassinado e carregá-lo como credencial da entidade de serviço para uso no fluxo OAuth)
      • Sample1 (pasta com mais exemplos de como as colunas do arquivo CSV podem ser mapeadas para os atributos padrão do SCIM. Se você obtiver arquivos CSV diferentes para funcionários, prestadores de serviços e estagiários, poderá criar um arquivo AttributeMapping.psd1 separado para cada entidade).
  4. Baixe e instale a versão mais recente do PowerShell.
  5. Execute o comando para habilitar a execução de scripts assinados remotamente:
    set-executionpolicy remotesigned
    
  6. Instale os seguintes módulos de pré-requisito:
    Install-Module -Name Microsoft.Graph.Applications,Microsoft.Graph.Reports
    

Gerar conteúdo de solicitação em massa com esquema padrão

Esta seção explica como gerar um conteúdo de solicitação em massa com atributos padrão de Usuário Principal e Usuário Corporativo do SCIM a partir de um arquivo CSV. Para ilustrar o procedimento, usaremos o arquivo CSV Samples/csv-with-2-records.csv.

  1. Abra o arquivo CSV Samples/csv-with-2-records.csv no Notepad++ ou no Excel para verificar as colunas presentes no arquivo. Screenshot of columns in Excel.

  2. No Notepad++ ou em um editor de código-fonte como o Visual Studio Code, abra o arquivo de dados do PowerShell Samples/AttributeMapping.psd1 que permite o mapeamento das colunas do arquivo CSV para os atributos do esquema padrão do SCIM. O arquivo enviado pronto para uso já tem um mapeamento pré-configurado das colunas do arquivo CSV para os atributos correspondentes do esquema SCIM.

        @{
        externalId   = 'WorkerID'
        name         = @{
            familyName = 'LastName'
            givenName  = 'FirstName'
        }
        active       = { $_.'WorkerStatus' -eq 'Active' }
        userName     = 'UserID'
        displayName  = 'FullName'
        nickName     = 'UserID'
        userType     = 'WorkerType'
        title        = 'JobTitle'
        addresses    = @(
            @{
                type          = { 'work' }
                streetAddress = 'StreetAddress'
                locality      = 'City'
                postalCode    = 'ZipCode'
                country       = 'CountryCode'
            }
        )
        phoneNumbers = @(
            @{
                type  = { 'work' }
                value = 'OfficePhone'
            }
        )
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" = @{
            employeeNumber = 'WorkerID'
            costCenter     = 'CostCenter'
            organization   = 'Company'
            division       = 'Division'
            department     = 'Department'
            manager        = @{
                value = 'ManagerID'
            }
        }
    }
    
  3. Abra o PowerShell e altere para o diretório CSV2SCIM\src.

  4. Execute o seguinte comando para inicializar a variável AttributeMapping.

    $AttributeMapping = Import-PowerShellDataFile '..\Samples\AttributeMapping.psd1'
    
  5. Execute o seguinte comando para validar se o arquivo AttributeMapping tem atributos de esquema SCIM válidos. Esse comando retorna True se a validação for bem-sucedida.

    .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ValidateAttributeMapping
    
  6. Se o arquivo AttributeMapping tiver um atributo SCIM inválido chamado userId, o modo ValidateAttributeMapping exibirá o seguinte erro.

    Screenshot of a mapping error.

  7. Depois de verificar se o arquivo AttributeMapping é válido, execute o seguinte comando para gerar uma solicitação em massa no arquivo BulkRequestPayload.json que inclui os dois registros presentes no arquivo CSV.

    .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping > BulkRequestPayload.json
    
  8. Você pode abrir o conteúdo do arquivo BulkRequestPayload.json para verificar se os atributos SCIM estão definidos de acordo com o mapeamento definido no arquivo AttributeMapping.psd1.

  9. Você pode postar o arquivo gerado acima como está no ponto de extremidade da API /bulkUpload associado ao aplicativo de provisionamento usando o Explorador do Graph, o Postman ou o cURL. Referência:

  10. Para carregar diretamente o conteúdo gerado no ponto de extremidade da API usando o mesmo script do PowerShell, consulte a próxima seção.

Gerar e carregar o conteúdo da solicitação em massa como usuário administrador

Esta seção explica como enviar o conteúdo da solicitação em massa gerada para o ponto de extremidade da API de provisionamento de entrada.

  1. Faça logon no Centro de administração do Microsoft Entra como, no mínimo, um Administrador de Aplicativos.

  2. Navegue até Aplicativo de Provisionamento>Propriedades>ID do Objeto e copie o ServicePrincipalId associado ao aplicativo de provisionamento.

    Screenshot of the Object ID.

  3. Como usuário com função de Administrador Global, execute o seguinte comando fornecendo os valores corretos para ServicePrincipalId e TenantId. Ele solicitará a autenticação se ainda não houver uma sessão autenticada para o locatário. Dê consentimento para as permissões solicitadas durante a autenticação.

    .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com"
    
  4. Visite a folha Logs de provisionamento do seu aplicativo de provisionamento para verificar o processamento da solicitação acima.

Configurar o certificado do cliente para autenticação da entidade de serviço

Observação

As instruções aqui mostram como gerar um certificado autoassinado. Por padrão, os certificados autoassinados não são confiáveis e podem ser difíceis de manter. Além disso, eles podem usar códigos hash e conjuntos de criptografia desatualizados que podem não ser fortes. Para obter mais segurança, adquira um certificado assinado por uma autoridade de certificação conhecida.

  1. Execute o seguinte script do PowerShell para gerar um certificado autoassinado. Você pode ignorar essa etapa se tiver adquirido um certificado assinado por uma autoridade de certificação conhecida.
    $ClientCertificate = New-SelfSignedCertificate -Subject 'CN=CSV2SCIM' -KeyExportPolicy 'NonExportable' -CertStoreLocation Cert:\CurrentUser\My
    $ThumbPrint = $ClientCertificate.ThumbPrint
    
    O certificado gerado é armazenado em Current User\Personal\Certificates. Você pode exibi-lo usando a opção Painel de Controle ->Gerenciar certificados de usuário.
  2. Para associar esse certificado a uma entidade de serviço válida, faça logon no Centro de administração do Microsoft Entra como Administrador de Aplicativos.
  3. Abra a entidade de serviço que você configurou em Registros de Aplicativos.
  4. Copie a ID do Objeto da folha Visão Geral. Use o valor para substituir a cadeia de caracteres <AppObjectId>. Copie a ID do Aplicativo (cliente). Nós a usaremos mais tarde e ela é referenciada como <AppClientId>.
  5. Execute o seguinte comando para carregar seu certificado para a entidade de serviço registrada.
    Connect-MgGraph -Scopes "Application.ReadWrite.All"
    Update-MgApplication -ApplicationId '<AppObjectId>' -KeyCredentials @{
       Type = "AsymmetricX509Cert"
       Usage = "Verify"
       Key = $ClientCertificate.RawData
    }
    
    Você deverá ver o certificado na folha Certificados e segredos do aplicativo registrado. Screenshot of client certificate.
  6. Adicione os dois escopos de permissão de Aplicativo a seguir ao aplicativo da entidade de serviço: Application.Read.All e Synchronization.Read.All. Eles são necessários para que o script do PowerShell procure o aplicativo de provisionamento pela ServicePrincipalId e busque o provisionamento JobId.

Carregar conteúdo de solicitação em massa usando autenticação de certificado do cliente

Esta seção explica como enviar o conteúdo da solicitação em massa gerada para o ponto de extremidade da API de provisionamento de entrada usando um certificado de cliente confiável.

  1. Abra o aplicativo de provisionamento controlado por API que você configurou. Copie a ServicePrincipalId associada ao aplicativo de provisionamento de Aplicativo de Provisionamento>Propriedades>ID do Objeto.

    Screenshot of the Object ID.

  2. Execute o comando a seguir, fornecendo os valores corretos para ServicePrincipalId, ClientId e TenantId.

    $ClientCertificate = Get-ChildItem -Path cert:\CurrentUser\my\ | Where-Object {$_.Subject -eq "CN=CSV2SCIM"}  
    $ThumbPrint = $ClientCertificate.ThumbPrint
    
    .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -TenantId "contoso.onmicrosoft.com" -ServicePrincipalId "<ProvisioningAppObjectId>" -ClientId "<AppClientId>" -ClientCertificate (Get-ChildItem Cert:\CurrentUser\My\$ThumbPrint)
    
  3. Visite a folha Logs de provisionamento do seu aplicativo de provisionamento para verificar o processamento da solicitação acima.

Gerar solicitação em massa com esquema SCIM personalizado

Esta seção descreve como gerar uma solicitação em massa com um namespace de esquema SCIM personalizado que consiste em campos no arquivo CSV.

  1. No Notepad++ ou em um editor de código-fonte como o Visual Studio Code, abra o arquivo de dados do PowerShell Samples/AttributeMapping.psd1 que permite o mapeamento das colunas do arquivo CSV para os atributos do esquema padrão do SCIM. O arquivo enviado pronto para uso já tem um mapeamento pré-configurado das colunas do arquivo CSV para os atributos correspondentes do esquema SCIM.

  2. Abra o PowerShell e altere para o diretório CSV2SCIM\src.

  3. Execute o seguinte comando para inicializar a variável AttributeMapping.

    $AttributeMapping = Import-PowerShellDataFile '..\Samples\AttributeMapping.psd1'
    
  4. Execute o seguinte comando para validar se o arquivo AttributeMapping tem atributos de esquema SCIM válidos. Esse comando retorna True se a validação for bem-sucedida.

    .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ValidateAttributeMapping
    
  5. Além dos atributos de Usuário Principal e Usuário Corporativo do SCIM, para obter uma lista simples de todos os campos CSV em um namespace de esquema SCIM personalizado urn:ietf:params:scim:schemas:extension:contoso:1.0:User, execute o seguinte comando.

     .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ScimSchemaNamespace "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"  > BulkRequestPayloadWithCustomNamespace.json
    

    Os campos CSV serão exibidos no namespace do esquema SCIM personalizado. Screenshot of user details under custom schema.

Estender o esquema de trabalho de provisionamento

Muitas vezes, o arquivo de dados enviado pelas equipes de RH contém mais atributos que não têm uma representação direta no esquema SCIM padrão. Para representar esses atributos, recomendamos a criação de um esquema de extensão SCIM e a adição de atributos no namespace.

O script CSV2SCIM fornece um modo de execução chamado UpdateSchema que lê todas as colunas no arquivo CSV, adiciona-as em um namespace de esquema de extensão e atualiza o esquema do aplicativo de provisionamento.

Observação

Se as extensões de atributo já estiverem presentes no esquema do aplicativo de provisionamento, esse modo emitirá apenas um aviso de que a extensão de atributo já existe. Portanto, não há problema em executar o script CSV2SCIM no modo UpdateSchema se novos campos forem adicionados ao arquivo CSV e você quiser adicioná-los como extensão.

Para ilustrar o procedimento, usaremos o arquivo CSV Samples/csv-with-2-records.csv presente na pasta CSV2SCIM.

  1. Abra o arquivo CSV Samples/csv-with-2-records.csv em um Bloco de Notas, Excel ou TextPad para verificar as colunas presentes no arquivo.

    Screenshot of how to check CSV columns.

  2. Execute o comando a seguir:

    .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -UpdateSchema -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -ScimSchemaNamespace "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"
    
  3. Você pode verificar a atualização do esquema do aplicativo de provisionamento abrindo a página Mapeamento de Atributos e acessando a opção Editar lista de atributos para API em Opções avançadas.

  4. A Lista de Atributos mostra os atributos do novo namespace.

Obter logs de provisionamento dos ciclos de sincronização mais recentes

Depois de enviar a solicitação em massa, você pode consultar os registros dos ciclos de sincronização mais recentes processados pelo Microsoft Entra ID. Você pode recuperar as estatísticas de sincronização e os detalhes de processamento com o script do PowerShell e salvá-los para análise.

  1. Para exibir os detalhes do log e as estatísticas de sincronização no console, execute o seguinte comando:

    .\CSV2SCIM.ps1 -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -GetPreviousCycleLogs -NumberOfCycles 1
    

    Screenshot of sync statistics.

    Observação

    O NumberOfCycles é 1 por padrão. Especifique um número para recuperar mais ciclos de sincronização.

  2. Para exibir as estatísticas de sincronização no console e salvar os detalhes dos logs em uma variável, execute o seguinte comando:

    $logs=.\CSV2SCIM.ps1 -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -GetPreviousCycleLogs
    

    Para executar o comando usando a autenticação do certificado do cliente, execute o comando fornecendo os valores corretos para ServicePrincipalId, ClientId e TenantId:

    $ClientCertificate = Get-ChildItem -Path cert:\CurrentUser\my\ | Where-Object {$_.Subject -eq "CN=CSV2SCIM"}  
    $ThumbPrint = $ClientCertificate.ThumbPrint
    
    $logs=.\CSV2SCIM.ps1 -ServicePrincipalId "<ProvisioningAppObjectId>" -TenantId "contoso.onmicrosoft.com" -ClientId "<AppClientId>" -ClientCertificate (Get-ChildItem Cert:\CurrentUser\My\$ThumbPrint) -GetPreviousCycleLogs -NumberOfCycles 1
    
    • Para ver os detalhes de um registro específico, podemos fazer um loop na coleção ou selecionar um índice específico dela, por exemplo: $logs[0]

      Screenshot of a selected index.

    • Também podemos usar a instrução where-object para pesquisar um registro específico usando sourceID ou DisplayName. Na propriedade ProvisioningLogs, podemos encontrar todos os detalhes da operação realizada para esse registro específico.

      $user = $logs | where sourceId -eq '1222'
      $user.ProvisioningLogs | fl
      

      Screenshot of provisioning logs.

    • Podemos ver as propriedades específicas afetadas pelo usuário no atributo ModifiedProperties. $user.ProvisioningLogs.ModifiedProperties

      Screenshot of properties.

Apêndice

Detalhes de uso do CSV2SCIM PowerShell

Aqui está uma lista de parâmetros de linha de comando aceitos pelo script CSV2SCIM do PowerShell.

PS > CSV2SCIM.ps1 -Path <path-to-csv-file> 
[-ScimSchemaNamespace <customSCIMSchemaNamespace>] 
[-AttributeMapping $AttributeMapping] 
[-ServicePrincipalId <spn-guid>] 
[-ValidateAttributeMapping]
[-UpdateSchema]
[-ClientId <client-id>]
[-ClientCertificate <certificate-object>]
[-RestartService]

Observação

Os parâmetros da linha de comando AttributeMapping e ValidateAttributeMapping referem-se ao mapeamento dos atributos da coluna CSV para os elementos do esquema SCIM padrão. Isso não se refere aos mapeamentos de atributos que você executa no aplicativo de provisionamento no centro de administração do Microsoft Entra entre os elementos do esquema SCIM de origem e os atributos de destino do Microsoft Entra/Active Directory local.

Parâmetro Descrição Processamento de comentários
Caminho O caminho completo ou relativo para o arquivo CSV. Por exemplo: .\Samples\csv-with-1000-records.csv Obrigatório: Sim
ScimSchemaNamespace O namespace do esquema SCIM personalizado a ser usado para enviar todas as colunas do arquivo CSV como atributos SCIM personalizados pertencentes a um namespace específico. Por exemplo, urn:ietf:params:scim:schemas:extension:csv:1.0:User Obrigatório: somente quando você quiser:
- Atualizar o esquema do aplicativo de provisionamento ou
Quando você quiser incluir atributos SCIM personalizados no conteúdo.
AttributeMapping Aponta para um arquivo de dados do PowerShell (extensão .psd1) que mapeia colunas do arquivo CSV para os atributos de Usuário Principal e Usuário Corporativo do SCIM.
Veja o exemplo: Arquivo AttributeMapping.psd para o script CSV2SCIM.
Por exemplo: powershell $AttributeMapping = Import-PowerShellDataFile '.\Samples\AttributeMapping.psd1'`-AttributeMapping $AttributeMapping
Obrigatório: Sim
O único cenário em que você não precisa especificar isso é quando estiver usando a opção de UpdateSchema.
ValidateAttributeMapping Use esse sinalizador Opção para validar se o arquivo AttributeMapping contém atributos que estão em conformidade com o esquema de Usuário Principal e Corporativo do SCIM. Obrigatório: Não
Recomenda-se usá-lo para garantir a conformidade.
ServicePrincipalId O valor GUID da ID da entidade de serviço do aplicativo de provisionamento que você pode recuperar do Aplicativo de Provisionamento>Propriedades>ID do Objeto Obrigatório: somente quando você quiser:
- Atualizar o esquema do aplicativo de provisionamento ou
- Enviar a solicitação em massa gerada para o ponto de extremidade da API.
UpdateSchema Use essa opção para instruir o script a ler as colunas CSV e adicioná-las como atributos SCIM personalizados no esquema de aplicativo de provisionamento.
ClientId A ID do cliente de um aplicativo registrado no Microsoft Entra a ser usado para o fluxo de autenticação do OAuth. Esse aplicativo deve ter credenciais de certificado válidas. Obrigatório: somente ao executar a autenticação baseada em certificado.
ClientCertificate O certificado de autenticação do cliente a ser usado durante o fluxo do OAuth. Obrigatório: somente ao executar a autenticação baseada em certificado.
GetPreviousCycleLogs Para obter logs de provisionamento dos ciclos de sincronização mais recentes.
NumberOfCycles Para especificar quantos ciclos de sincronização devem ser recuperados. Esse valor é 1 por padrão.
RestartService Com essa opção, o script pausa temporariamente o trabalho de provisionamento antes de carregar os dados. Ele carrega os dados e, em seguida, inicia o trabalho novamente para garantir o processamento imediato do conteúdo. Use essa opção somente durante o teste.

Arquivo AttributeMapping.psd

Esse arquivo é usado para mapear as colunas do arquivo CSV para os elementos padrão do esquema de atributos de Usuário Principal e Usuário Corporativo do SCIM. O arquivo também gera uma representação apropriada do conteúdo do arquivo CSV como um conteúdo de solicitação em massa.

No próximo exemplo, mapeamos as seguintes colunas do arquivo CSV para os atributos correspondentes de Usuário Principal e Usuário Corporativo do SCIM.

Screenshot of CSV columns for mapped attributes.

    @{
    externalId   = 'WorkerID'
    name         = @{
        familyName = 'LastName'
        givenName  = 'FirstName'
    }
    active       = { $_.'WorkerStatus' -eq 'Active' }
    userName     = 'UserID'
    displayName  = 'FullName'
    nickName     = 'UserID'
    userType     = 'WorkerType'
    title        = 'JobTitle'
    addresses    = @(
        @{
            type          = { 'work' }
            streetAddress = 'StreetAddress'
            locality      = 'City'
            postalCode    = 'ZipCode'
            country       = 'CountryCode'
        }
    )
    phoneNumbers = @(
        @{
            type  = { 'work' }
            value = 'OfficePhone'
        }
    )
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" = @{
        employeeNumber = 'WorkerID'
        costCenter     = 'CostCenter'
        organization   = 'Company'
        division       = 'Division'
        department     = 'Department'
        manager        = @{
            value = 'ManagerID'
        }
    }
}

Próximas etapas