Partilhar via

Perguntas frequentes sobre o provisionamento de entrada orientado por API

  • Artigo

Este artigo responde a perguntas freqüentes (FAQs) sobre o provisionamento de entrada controlado por API.

Qual é a diferença entre a nova API de provisionamento /bulkUpload de entrada e a API de usuários do MS Graph?

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

  • Formato de carga útil: O ponto de extremidade da API de usuários do MS Graph espera dados no formato OData. O formato de carga útil de solicitação para a nova API de provisionamento /bulkUpload de entrada usa construções de esquema SCIM. Ao invocar esta 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 imediatamente processados e uma operação Criar/Atualizar/Excluir ocorre no perfil de usuário do Microsoft Entra.
    • Os dados de solicitação enviados para a 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 atributos 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 do AD local.
  • O administrador de TI mantém o controle: com o provisionamento de entrada orientado por API, o administrador de TI tem mais controle sobre como os dados de identidade de entrada são processados e mapeados para os atributos do Microsoft Entra. Eles podem definir regras de escopo para excluir certos 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.

O provisionamento de entrada /bulkUpload API é um ponto de extremidade SCIM padrão?

O provisionamento de entrada /bulkUpload API do MS Graph usa o esquema SCIM na carga útil da solicitação, mas não é um ponto de extremidade padronizado da API SCIM. Eis como.

Normalmente, um ponto de extremidade de serviço SCIM processa solicitações HTTP (POST, PUT, GET) com a carga útil SCIM e as traduz para as respetivas operações de (Criar, Atualizar, Pesquisar) no repositório de identidades. O ponto de extremidade do 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 provisionamento de entrada /bulkUpload do MS Graph foi projetado para lidar com um cenário diferente de integração de identidade corporativa moldado por três requisitos exclusivos:

  1. Capacidade de processar registros em massa de forma assíncrona (por exemplo, processando registros 50K+)
  2. Capacidade de incluir qualquer atributo de identidade na carga útil (por exemplo, costCenter, pay grade, badgeId)
  3. Clientes de API de suporte que desconhecem a semântica da 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 HR). Esses clientes não têm a capacidade de processamento para ler cada registro e determinar a semântica da operação no repositório de Create/Update/Delete identidades.

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

A API de provisionamento /bulkUpload oferece suporte a domínios locais do Ative Directory como destino?

Sim, a API de provisionamento oferece suporte a domínios do AD locais como destino.

Como obtemos 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 o Microsoft Entra ID" e "Provisionamento de entrada controlado por API para o Ative 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é o momento>Exibir informações técnicas, copie a URL do ponto de extremidade da API de provisionamento.

Tem o formato:

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

Como executamos 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 processa todos os registros do usuário e permite que você acompanhe o progresso usando o ponto de extremidade da API de logs de provisionamento.

Como executamos 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 processa todos os registros do usuário e permite que você acompanhe o progresso usando o ponto de extremidade da API de logs de provisionamento.

Como funciona o provisionamento de reinicialização?

Use a opção Reiniciar provisionamento somente se necessário. Eis 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. Aoperação de provisionamento Reiniciar não interrompe um ciclo existente. No ciclo subsequente, o serviço de provisionamento limpa todas as garantias 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 todas as garantias e processa apenas novos dados recebidos.

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

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

  1. O trabalho recupera o mapeamento de atributos para o trabalho de provisionamento e anota o par de atributos correspondente (por padrão externalId , o atributo API é usado para corresponder ao employeeId Microsoft Entra ID).
  2. Você pode alterar esse par de correspondência de atributo padrão.
  3. O trabalho extrai cada operação presente na carga útil de 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 ID do Microsoft Entra com valor correspondente employeeId .
  5. Se o trabalho não encontrar um usuário correspondente, ele aplicará as regras de sincronização e criará um novo usuário no diretório de destino.

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

Como geramos valores únicos para a UPN?

O serviço de provisionamento não fornece a capacidade de verificar se há duplicados 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 a geração exclusiva de UPN em seu cliente de API.
  2. Atualize a regra de sincronização para o atributo UPN para usar a função RandomString e defina 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 Ative Directory local, poderá usar a função SelectUniqueValue e definir o parâmetro apply mapping como On object creation only.

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

Por padrão, o ponto de extremidade da API suporta o processamento de qualquer atributo que faça parte do esquema SCIM Core User e Enterprise User. Se quiser enviar mais atributos, você pode estender o esquema do 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 provisionamento controlado por API para sincronizar atributos personalizados.

Como excluímos 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 conseguir 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 apenas usuários onde o departamento EQUALS Sales) ou uma "regra de exclusão" (por exemplo, excluir usuários pertencentes a Vendas, departamento NÃO IGUAL a Vendas).

Consulte Escopo de usuários ou grupos a serem provisionados com filtros de escopo.

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

Veja como o trabalho de provisionamento associado ao ponto de extremidade da API /bulkUpload processa as cargas úteis do 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 externalId , o atributo API é usado para corresponder ao employeeId Microsoft Entra ID). Você pode alterar esse par de correspondência de atributo padrão.
  2. O trabalho extrai as operações da carga útil de solicitação em massa.
  3. O trabalho verifica o identificador de correspondência de valor na solicitação SCIM (por padrão: atributo externalIdAPI) e o usa para verificar se há um usuário no ID do Microsoft Entra com valor correspondente employeeId .
  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 correspondente correto em seu mapeamento que identifica exclusivamente os usuários em sua origem e o ID do Microsoft Entra.

Podemos criar mais de um aplicativo que ofereça suporte ao provisionamento de entrada orientado por API?

Sim, 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 contratados 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 atributos distintos. Cada aplicativo de provisionamento tem um ponto de extremidade de API exclusivo e você pode enviar as respetivas cargas úteis 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. Navegue até Estatísticas até a data>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 Badging fornece atributos de informações de selo (por exemplo badgeId , que é representado usando um atributo de extensão). Nesse cenário, você pode configurar dois aplicativos de provisionamento:

  • Aplicativo de provisionamento #1 que recebe atributos de sua fonte de RH e cria o usuário.

  • Aplicativo de provisionamento #2 que recebe atributos do sistema Badging e atualiza apenas os atributos do usuário. O mapeamento de atributos neste aplicativo é restrito aos atributos Informações 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 ponto de extremidade da API /bulkUpload?

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

Por padrão, o valor associado ao atributo active de esquema SCIM Core User 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 estiver definido como false, a regra de mapeamento padrão desativará a conta.

Como podemos evitar a desativação/eliminação acidental de utilizadores?

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 Ative Directory local. Na folha Mapeamento de Atributos do seu aplicativo de provisionamento, em Ações do objeto de destino, desative a operação Excluir .

Recuperando contas excluídas

  • Se o diretório de destino para a operação for o Microsoft Entra ID, o usuário correspondente será excluído suavemente. O usuário pode ser visto na página de 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 Ative Directory local, o usuário correspondente será excluído. Se a Lixeira do Ative 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 todas as solicitações?

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ê gostaria de criar ou atualizar.

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

Não, o ponto de extremidade da API de provisionamento /bulkUpload suporta apenas a ação HTTP POST.

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

Não, o ponto de extremidade da API não suporta a solicitação PUT/PATCH. Para atualizar um usuário, envie os dados associados ao usuário na carga útil de solicitação em massa do POST.

O trabalho de provisionamento que processa os dados recebidos pelo ponto de extremidade da API deteta automaticamente se o usuário recebido na carga útil da 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 precisa executar mais nenhuma etapa se quiser que um perfil de usuário seja atualizado.

Como é suportado o write-back?

A API atual suporta apenas dados de entrada. Aqui estão algumas opções a considerar para implementar write-back de atributos como e-mail / nome de usuário / telefone gerado pelo Microsoft Entra ID, que você pode fluir de volta para o sistema de RH:

  • Opção 1 – Conectividade SCIM com o serviço de endpoint/proxy de RH que, por sua vez, atualiza a fonte de RH

    • Se o sistema de registro fornecer um ponto de extremidade SCIM para atualizações do usuário, você poderá criar um aplicativo SCIM personalizado na galeria de aplicativos corporativos 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 recebe a atualização e propaga 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 / Web Services).

  • Opção 3 – Usar a tarefa de extensão personalizada Lifecycle Workflows em um fluxo de trabalho Joiner

Próximos passos