Partilhar via

Perguntas frequentes sobre o provisionamento de entrada orientado por API

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?

Existem diferenças significativas entre a API de provisionamento /bulkUpload e o endpoint da API de utilizadores do MS Graph.

  • Formato de carga útil: O endpoint da API de utilizadores do MS Graph espera dados no formato OData. O formato da carga útil da solicitação para a nova API de provisionamento de entrada /bulkUpload utiliza 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 utilizadores do Microsoft Graph, eles são imediatamente processados e uma operação de Criação/Atualização/Eliminação ocorre no perfil de utilizador 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 aprovisionamento de entrada da API /bulkUpload do MS Graph utiliza o esquema SCIM na carga da solicitação, mas não é um endpoint padronizado da API SCIM. Aqui está o porquê.

Normalmente, um endpoint de serviço SCIM processa solicitações HTTP (POST, PUT, GET) com SCIM payload 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 atribui ao cliente da API SCIM a responsabilidade de especificar a semântica da operação, seja para criar, atualizar ou excluir uma identidade. 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. Fornecer suporte a clientes da API 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 registo e determinar a semântica da operação de Create/Update/Delete no repositório de 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 útil 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 a uma operação (Criar, Atualizar, Ativar, 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 endpoint de API exclusivo para cada aplicativo de provisionamento na página inicial da seção 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 a configuração na reinicialização?

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

Cenário 1: Quando se clica no botão Reiniciar provisionamento e o trabalho está atualmente em execução, o trabalho continua a processar os dados existentes que já estão preparados. A operação Reiniciar de provisionamento 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 de entrada.

Como criamos utilizadores usando o endpoint da API de provisionamento /bulkUpload?

Eis como o trabalho de provisionamento associado ao endpoint da API /bulkUpload processa as cargas de dados de utilizador recebidas:

  1. O trabalho recupera o mapeamento de atributos para o trabalho de provisionamento e anota o par de atributos correspondente (o atributo API externalId é utilizado por padrão para corresponder ao employeeId no Microsoft Entra ID).
  2. Você pode alterar este 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 usa-o para verificar se existe um utilizador na ID do Microsoft Entra com o valor correspondente a 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 utilizadores certos sejam criados no Microsoft Entra ID, defina o par de atributos correspondente correto no seu mapeamento, que identifica unicamente os utilizadores na sua origem e no Microsoft Entra ID.

Como geramos valores únicos para a UPN?

O serviço de provisionamento não fornece a capacidade de verificar duplicados userPrincipalName (UPN) e de 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 Delimitar utilizadores ou grupos a serem aprovisionados com filtros de delimitação.

Como atualizamos os utilizadores usando o endpoint da API de provisionamento /bulkUpload?

Eis como o trabalho de provisionamento associado ao endpoint da API /bulkUpload processa as cargas de dados de utilizador recebidas:

  1. O trabalho de aprovisionamento recupera o mapeamento de atributos e anota o par de atributos correspondente (por padrão, o atributo API externalId é usado para corresponder ao employeeId no Microsoft Entra ID). Você pode alterar este 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 valor na solicitação SCIM (por padrão: atributo de API externalId) e utiliza-o para verificar se existe um usuário no Microsoft Entra ID com o 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 utilizadores certos sejam atualizados no Microsoft Entra ID, certifique-se de definir o par de atributos correspondente correto no seu mapeamento que identifica exclusivamente os utilizadores na sua origem de dados e no Microsoft Entra ID.

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 aplicação de provisionamento tem um endpoint de API exclusivo e pode-se enviar as respetivas cargas úteis para cada endpoint.

Você pode obter o ponto de extremidade exclusivo da API para cada tarefa na página inicial do painel de 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 Emissão de Crachás fornece atributos de informações de crachá (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 nesta aplicação é restrito aos atributos de Informações do Distintivo e, nas Ações do Objeto de Destino, apenas a opção de 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 na sua origem que será usado para definir o sinalizador accountEnabled no Microsoft Entra ID. 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 Active Directory estiver ativada, poderá restaurar o objeto de utilizador do AD no local que foi eliminado.

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 a escrita de volta de atributos como e-mail, nome de utilizador e telefone gerados pelo Microsoft Entra ID, que podem ser transferidos 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

  • Last updated on