Compartilhar via

Perguntas frequentes sobre o provisionamento de entrada controlado por API

Este artigo responde a perguntas frequentes sobre o provisionamento de entrada controlado por API.

Qual a diferença entre a API bulkUpload de provisionamento de entrada e a API de Usuários do MS Graph?

Há diferenças significativas entre a API de provisionamento /bulkUpload e o endpoint da API de Usuários do MS Graph.

  • Formato de payload: o ponto de extremidade da API de Usuários do MS Graph espera obter dados no formato OData. O formato de conteúdo de solicitação para a nova API de provisionamento de entrada /bulkUpload usa constructos de esquema SCIM. Ao invocar essa API, defina o cabeçalho 'Content-Type' como application/scim+json.
  • Resultado final da operação:
    • Quando os dados de identidade são enviados para o endpoint da API de Usuários do Microsoft Graph, eles são processados imediatamente e uma operação de criar/atualizar/excluir ocorre no perfil de usuário do Microsoft Entra.
    • Os dados de solicitação enviados à API de provisionamento /bulkUpload são processados de forma assíncrona pelo serviço de provisionamento do Microsoft Entra. O trabalho de provisionamento aplica regras de escopo, mapeamento de atributo e transformação configurados pelo administrador de TI. Isso inicia uma Create/Update/Delete operação no perfil de usuário do Microsoft Entra ou no perfil de usuário local do AD.
  • O administrador de TI mantém o controle: com o provisionamento de entrada controlado por API, o administrador de TI tem mais controle sobre como os dados de identidade de entrada são processados e mapeados para atributos do Microsoft Entra. Eles podem definir regras de escopo para excluir determinados tipos de dados de identidade (por exemplo, dados do contratante) e usar funções de transformação para derivar novos valores antes de definir os valores de atributo no perfil do usuário.

A API de provisionamento de entrada /bulkUpload é um endpoint SCIM padrão?

A API de provisionamento de entrada do MS Graph, /bulkUpload, usa o esquema SCIM no conteúdo da solicitação, mas não é um endpoint padronizado da API SCIM. Veja por quê.

Normalmente, um ponto de extremidade de serviço SCIM processa solicitações HTTP (POST, PUT, GET) com conteúdo SCIM e as converte em suas respectivas operações de (Criar, Atualizar, Pesquisar) no repositório de identidades. O ponto de extremidade de serviço SCIM coloca o ônus de especificar a semântica da operação, se deseja criar/atualizar/excluir uma identidade, no cliente da API SCIM. Esse mecanismo funciona bem para cenários em que o cliente de API está ciente de qual operação ele gostaria de executar para os usuários no repositório de identidades.

O provisionamento de entrada /bulkUpload do MS Graph foi projetado para lidar com um cenário de integração de identidade empresarial diferente moldado por três requisitos exclusivos:

  1. Capacidade de processar registros de forma assíncrona em massa (por exemplo, processamento de mais de 50 mil registros)
  2. Capacidade de incluir qualquer atributo de identidade no conteúdo (por exemplo, costCenter, pay grade, badgeId)
  3. Suporte a clientes de API sem conhecimento da semântica de operação. Esses clientes são clientes de API não SCIM que só têm acesso a dados brutos de origem (por exemplo, registros em arquivos CSV, tabela SQL ou registros de RH). Esses clientes não têm capacidade de processamento para ler cada registro e determinar a semântica de operação do Create/Update/Delete no repositório de identidades.

O objetivo principal do provisionamento de entrada /bulkUpload API do MS Graph é permitir que os clientes enviem dados de identidade (por exemplo, costCenter, pay grade, badgeId) de qualquer fonte de dados de identidade (por exemplo, CSV/SQL/HR) para processamento eventual pelo serviço de provisionamento do Microsoft Entra. O serviço de provisionamento do Microsoft Entra consome os dados de carga em massa recebidos neste endpoint, aplica as regras de mapeamento de atributos configuradas pelo administrador de TI e determina se a carga de dados leva a uma operação (Criar, Atualizar, Habilitar, Desabilitar) no repositório de identidade de destino (Microsoft Entra ID/AD local).

A API de provisionamento /bulkUpload dá suporte a domínios locais do Active Directory como um destino?

Sim, a API de provisionamento dá suporte a domínios do AD local como um destino.

Como obter o ponto de extremidade da API /bulkUpload para nosso aplicativo de provisionamento?

A API /bulkUpload está disponível apenas para aplicativos do tipo: "Provisionamento de entrada controlado por API para a ID do Microsoft Entra" e "Provisionamento de entrada controlado por API para o Active Directory local". Você pode recuperar o ponto de extremidade de API exclusivo para cada aplicativo de provisionamento na página inicial da folha Provisionamento. Em Estatísticas até a data>Exibir informações técnicas, copie o URL do Ponto de Extremidade da API de Provisionamento.

Ele tem o formato:

https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload

Como executar uma sincronização completa usando a API de provisionamento /bulkUpload?

Para executar uma sincronização completa, use seu cliente de API para enviar os dados de todos os usuários de sua fonte confiável para o ponto de extremidade da API como solicitação em massa. Depois de enviar todos os dados para o ponto de extremidade da API, o próximo ciclo de sincronização processará todos os registros do usuário e permitirá que você acompanhe o progresso usando o ponto de extremidade da API de logs de provisionamento.

Como executar a sincronização delta usando a API de provisionamento /bulkUpload?

Para executar uma sincronização delta, use seu cliente de API para enviar apenas informações sobre usuários cujos dados foram alterados na fonte confiável. Depois de enviar todos os dados para o ponto de extremidade da API, o próximo ciclo de sincronização processará todos os registros do usuário e permitirá que você acompanhe o progresso usando o ponto de extremidade da API de logs de provisionamento.

Como funciona a ação reiniciar provisionamento?

Use a opção Reiniciar provisionamento somente se necessário. Veja como funciona:

Cenário 1: quando você clica no botão Reiniciar provisionamento e o trabalho está em execução no momento, o trabalho continua processando os dados existentes que já estão preparados. A operação de reinicialização do provisionamento não interrompe o ciclo atual. No ciclo subsequente, o serviço de provisionamento libera todas as cauções e seleciona a nova solicitação em massa para processamento.

Cenário 2: Quando você clica no botão Reiniciar provisionamento e o trabalho não está em execução, antes de executar o ciclo subsequente, o mecanismo de provisionamento limpa os dados carregados antes da reinicialização, limpa todos os escrows e processa apenas novos dados de entrada.

Como criamos usuários usando o endpoint da API de provisionamento /bulkUpload?

Veja como o trabalho de provisionamento associado ao ponto de extremidade da API /bulkUpload processa cargas de usuário de entrada:

  1. O trabalho recupera o mapeamento de atributo para a tarefa de provisionamento e anota o par de atributos correspondente (por padrão, o atributo de API externalId é usado para corresponder ao employeeId no Microsoft Entra ID).
  2. Você pode alterar esse par de atributos correspondentes padrão.
  3. O trabalho extrai cada operação presente no conteúdo da solicitação em massa.
  4. O trabalho verifica o identificador de correspondência de valor na solicitação (por padrão, o atributo externalId) e o usa para verificar se há um usuário no Microsoft Entra ID com o valor employeeId correspondente.
  5. Se o trabalho não encontrar um usuário correspondente, o trabalho aplicará as regras de sincronização e criará um novo usuário no diretório de destino.

Para garantir que os usuários corretos sejam criados no Microsoft Entra ID, defina o par de atributos correspondente correto no mapeamento que identifica exclusivamente os usuários em sua origem e no Microsoft Entra ID.

Como geramos valores exclusivos para UPN?

O serviço de provisionamento não fornece a capacidade de marcar para duplicar userPrincipalName (UPN) e lidar com conflitos. Se a regra de sincronização padrão para o atributo UPN gerar um valor UPN existente, a operação de criação do usuário falhará.

Aqui estão algumas opções que você pode considerar para gerar UPNs exclusivos:

  1. Adicione a lógica para geração UPN exclusiva em seu cliente de API.
  2. Atualize a regra de sincronização do atributo UPN para usar a função RandomString e defina o parâmetro aplicar mapeamento como On object creation only. Exemplo:

Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

  1. Se você estiver provisionando para o Active Directory local, poderá usar a função SelectUniqueValue e definir o parâmetro aplicar mapeamento como On object creation only.

Como enviamos mais atributos de RH ao endpoint da API de provisionamento /bulkUpload?

Por padrão, o ponto de extremidade da API dá suporte ao processamento de qualquer atributo que faça parte do esquema de Usuário Básico do SCIM e do esquema de Usuário Corporativo. Se você quiser enviar mais atributos, poderá estender o esquema de aplicativo de provisionamento, mapear os novos atributos para os atributos do Microsoft Entra e atualizar a solicitação em massa para enviar esses atributos. Consulte o tutorial Estender o provisionamento controlado por API para sincronizar atributos personalizados.

Como excluir determinados usuários do fluxo de provisionamento?

Você pode ter um cenário em que deseja enviar todos os usuários para o ponto de extremidade da API, mas inclua apenas determinados usuários no fluxo de provisionamento e exclua o restante.

Você pode fazer isso usando o filtro de escopo. Na configuração do aplicativo de provisionamento, você pode definir um escopo de objeto de origem e excluir determinados usuários do processamento usando uma "regra de inclusão" (por exemplo, processar somente usuários em que o departamento EQUALS Sales) ou uma "regra de exclusão" (por exemplo, excluir usuários pertencentes a Vendas, departamento NOT EQUALS Sales).

Consulte Como definir o escopo de usuários ou grupos a serem provisionados por meio de filtros de escopo.

Como atualizamos usuários usando o endpoint da API de provisionamento /bulkUpload?

Veja como o trabalho de provisionamento associado ao ponto de extremidade da API /bulkUpload processa cargas de usuário de entrada:

  1. O trabalho de provisionamento recupera o mapeamento de atributos para o trabalho de provisionamento e anota o par de atributos correspondente (por padrão, o atributo externalId de API é usado para corresponder a employeeId no Microsoft Entra ID). Você pode alterar esse par de atributos correspondentes padrão.
  2. O trabalho extrai as operações do conteúdo da solicitação em massa.
  3. O trabalho verifica o identificador de correspondência de valores na solicitação SCIM (por padrão: atributo API externalId) e o utiliza para verificar se há um usuário no Microsoft Entra ID com o valor employeeId correspondente.
  4. Se o trabalho encontrar um usuário correspondente, ele aplicará as regras de sincronização e comparará os perfis de origem e de destino.
  5. Se o trabalho determinar que alguns valores foram alterados, ele atualizará o registro de usuário correspondente no diretório.

Para garantir que os usuários certos sejam atualizados no Microsoft Entra ID, certifique-se de definir o par de atributos correspondentes corretos em seu mapeamento que identifique exclusivamente os usuários em sua origem e no Microsoft Entra ID.

Podemos criar mais de um aplicativo que dá suporte ao provisionamento de entrada controlado por API?

Sim, você pode. Aqui estão alguns cenários que podem exigir mais de um aplicativo de provisionamento:

Cenário 1: Digamos que você tenha três fontes de dados confiáveis: uma para funcionários, uma para empreiteiros e outra para fornecedores. Você pode criar três aplicativos de provisionamento separados – um para cada tipo de identidade com seu próprio mapeamento de atributo distinto. Cada aplicativo de provisionamento tem um endpoint de API exclusivo e você pode enviar os respectivos payloads para cada endpoint.

Você pode recuperar o ponto de extremidade de API exclusivo para cada trabalho na página inicial da folha Provisionamento. Navegue até Estatísticas até o momento>Exibir informações técnicas e copie a URL do Endpoint da API de Provisionamento.

Cenário 2: Digamos que você tenha várias fontes de verdade, cada uma com seu próprio conjunto de atributos. Por exemplo, o RH fornece atributos de informações de trabalho (por exemplo, jobTitle, employeeType) e o Sistema de Crachás fornece atributos de informações de crachá (por exemplo badgeId que são representados usando um atributo de extensão). Nesse cenário, você pode configurar dois aplicativos de provisionamento:

  • Aplicativo de Provisionamento #1 que recebe atributos do sistema de RH e cria o usuário.

  • Aplicativo de Provisionamento nº 2 que recebe atributos do sistema de atribuição de selo e atualiza apenas os atributos de usuário. O mapeamento de atributo nesse aplicativo é restrito aos atributos Informações de Atribuição de Selo e, em Ações de Objeto de Destino, apenas a atualização está habilitada.

  • Ambos os aplicativos usam o mesmo par de identificadores correspondentes (externalId<->employeeId)

Como processamos rescisões usando o endpoint da API /bulkUpload?

Para processar terminações, identifique um atributo em sua origem que será usado para definir o sinalizador accountEnabled no Microsoft Entra ID. Se você estiver provisionando para o Active Directory local, mapeie esse atributo de origem para o accountDisabled atributo.

Por padrão, o valor associado ao atributo active de esquema de usuário scim core determina o status da conta do usuário no diretório de destino.

Se o atributo for definido como true, a regra de mapeamento padrão habilitará a conta. Se o atributo for definido como false, a regra de mapeamento padrão desabilita a conta.

Como podemos impedir a desabilitação/exclusão acidental de usuários?

Para evitar e recuperar de exclusões acidentais, recomendamos configurar o limite de exclusão acidental no aplicativo de provisionamento e habilitar a lixeira do Active Directory local. Na folha Mapeamento de Atributos do aplicativo de provisionamento, em Ações de objeto de destino desabilite a operação Excluir .

Recuperando contas excluídas

  • Se o diretório de destino da operação for o Microsoft Entra ID, o usuário correspondente será excluído temporariamente. O usuário pode ser visto na página usuários excluídos do centro de administração do Microsoft Entra pelos próximos 30 dias e pode ser restaurado durante esse período.
  • Se o diretório de destino da operação for o Active Directory local, o usuário correspondente será excluído. Se a Lixeira do Active Directory estiver habilitada, você poderá restaurar o objeto de usuário do AD local excluído.

Precisamos enviar todos os usuários do sistema de RH em cada solicitação?

Não, você não precisa enviar todos os usuários do sistema de RH/"fonte da verdade" em cada solicitação. Basta enviar os usuários que você deseja criar ou atualizar.

A API dá suporte a todas as ações HTTP (GET/POST/PUT/PATCH)?

Não, o ponto de extremidade da API de provisionamento /bulkUpload só dá suporte à ação HTTP POST.

Se eu quiser atualizar um usuário, preciso enviar uma solicitação PUT/PATCH?

Não, o ponto de extremidade da API não dá suporte à solicitação PUT/PATCH. Para atualizar um usuário, envie os dados associados ao usuário no conteúdo da solicitação em massa POST.

O trabalho de provisionamento que processa dados recebidos pelo ponto de extremidade da API detecta automaticamente se o usuário recebido na carga de solicitação POST precisa ser criado/atualizado/habilitado/desabilitado com base nas regras de sincronização configuradas. Como um cliente de API, você não precisará executar mais nenhuma etapa se quiser que um perfil de usuário seja atualizado.

Como é oferecido suporte para write-back?

A API atual só dá suporte a dados de entrada. Aqui estão algumas opções a serem consideradas para implementar o write-back de atributos como email/nome de usuário/telefone gerados pelo Microsoft Entra ID, que você poderá devolver para o sistema de RH:

  • Opção 1: conectividade SCIM com o serviço de proxy/ponto de extremidade do RH que, por sua vez, atualiza a fonte do RH

    • Se o sistema de registro de dados fornecer um ponto de extremidade SCIM para atualizações de usuário, você poderá criar um aplicativo SCIM personalizado na galeria de aplicativos empresariais e configurar o provisionamento conforme descrito na documentação.
    • Se o sistema de registro não fornecer um ponto de extremidade SCIM, explore a possibilidade de configurar um serviço SCIM proxy, que receba a atualização e propague a alteração para o sistema de RH.

  • Opção 2: usar o conector ECMA do Microsoft Entra para o cenário de write-back

    • Dependendo do requisito do cliente, explore se um dos conectores ECMA pode ser usado (PowerShell/SQL/Serviços Web).

  • Opção 3: usar a tarefa de extensão personalizada de Fluxos de Trabalho do Ciclo de Vida em um fluxo de trabalho do Joiner

Próximas etapas

  • Last updated on