Perguntas frequentes sobre o provisionamento de entrada orientado por API

  • Artigo

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 /bulkUpload de provisionamento e o ponto de extremidade 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 da solicitação para a nova API /bulkUpload de provisionamento de entrada 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 ponto de extremidade da API de Usuários do MS Graph, eles são processados imediatamente e uma operação Criar/Atualizar/Excluir ocorre no perfil do usuário do Microsoft Entra.
    • Os dados de solicitação enviados à API /bulkUpload de provisionamento 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 operação Create/Update/Delete no perfil de usuário do Microsoft Entra ou no perfil de usuário do AD local.
  • 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 /bulkUpload de provisionamento de entrada é um ponto de extremidade SCIM padrão?

A API /bulkUpload de provisionamento de entrada do MS Graph usa o esquema SCIM no conteúdo da solicitação, mas não é um ponto de extremidade 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 gostaria de executar para os usuários no repositório de identidades.

O /bulkUpload de provisionamento de entrada 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. Compatibilidade com 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 de origem brutos (por exemplo, registros em arquivo 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 da API /bulkUpload de provisionamento de entrada do MS Graph é habilitar os clientes para o envio de quaisquer 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 conteúdo em massa recebidos nesse ponto de extremidade, aplica regras de mapeamento de atributo configuradas pelo administrador de TI e determina se o conteúdo de dados leva à operação (Criar, Atualizar, Habilitar, Desabilitar) no repositório de identidade de destino (Microsoft Entra ID/AD local).

A API /bulkUpload de provisionamento é compatível com domínios do Active Directory local como destino?

Sim, a API de provisionamento é compatível com domínios do AD local como destino.

Como podemos 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 Microsoft Entra" e "Provisionamento de entrada controlado por API para 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 a URL Ponto de Extremidade da API de Provisionamento.

Ela tem o seguinte 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 de 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 /bulkUpload de provisionamento?

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 de 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çãoReiniciar provisionamento não interrompe um ciclo existente. No ciclo subsequente, o serviço de provisionamento limpa todas as cauções e escolhe 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 todas as cauções e processa apenas novos dados de entrada.

Como criar usuários usando o ponto de extremidade da API /bulkUpload de provisionamento?

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 o trabalho de provisionamento e anota o par de atributos correspondente (por padrão, o atributo de API externalId é usado para corresponder a employeeId no Microsoft Entra ID).
  2. Você pode alterar esse par de correspondência de atributo 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 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 gerar 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. Adicionar a lógica para geração de UPN exclusiva em seu cliente de API.
  2. Atualizar a regra de sincronização do atributo UPN para usar a função RandomString e definir o parâmetro apply mapping 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 de mapeamento apply como On object creation only.

Como enviar mais atributos de RH para o ponto de extremidade da API /bulkUpload de provisionamento?

Por padrão, o ponto de extremidade de API é compatível com o processamento de qualquer atributo que faça parte do esquema de usuário corporativo e do usuário do SCIM Core. Se você quiser enviar mais atributos, poderá ampliar o esquema do aplicativo de provisionamento, mapear os novos atributos para 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 incluir apenas determinados usuários no fluxo de provisionamento e excluir 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 Vendas) ou uma "regra de exclusão" (por exemplo, excluir usuários pertencentes a Vendas, departamento NOT EQUALS Vendas).

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

Como atualizar usuários usando o ponto de extremidade da API /bulkUpload de provisionamento?

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 o trabalho de provisionamento e anota o par de atributos correspondente (por padrão, o atributo de API externalId é usado para corresponder a employeeId no Microsoft Entra ID). Você pode alterar esse par de correspondência de atributo 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 compatível com o 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 prestadores de serviços 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 ponto de extremidade de API exclusivo e você pode enviar os respectivos conteúdos para cada ponto de extremidade.

Você pode recuperar o ponto de extremidade de API exclusivo para cada trabalho na página inicial da folha Provisionamento. Em Estatísticas até o momento>Exibir informações técnicas e copie a URL do Ponto de Extremidade 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 Atribuição de Selo fornece atributos de informações de notificação (por exemplo badgeId, que é representado por meio de um atributo de extensão). Nesse cenário, você pode configurar dois aplicativos de provisionamento:

  • Aplicativo de Provisionamento nº 1, que recebe atributos da fonte 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.

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

Como processar terminações usando o ponto de extremidade 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 atributo accountDisabled.

Por padrão, o valor associado ao atributo de esquema de Usuário Principal do SCIM active 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 evitar a desabilitação/exclusão acidental de usuários?

Para evitar e se 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 .

Como recuperar 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 poderá ser visto na página Usuários excluídos do Centro de administração do Microsoft Entra pelos próximos 30 dias e poderá 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 de verdade" em cada solicitação. Basta enviar os usuários que você deseja criar ou atualizar.

A API é compatível com todas as ações HTTP (GET/POST/PUT/PATCH)?

Não, o ponto de extremidade da API /bulkUpload de provisionamento é compatível apenas com a 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 é compatível com a 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 o write-back é compatível?

A API atual é compatível apenas com 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 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 documentado.
    • 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, considere 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