Adicionar um conector de API a um fluxo de usuário

2025-05-04

Aplica-se a: Círculo verde com um símbolo de marca de verificação branco. Locatários da força de Círculo branco com um símbolo X cinzento. trabalho Locatários externos (saiba mais)

Para usar um conector de API, primeiro crie o conector de API e, em seguida, habilite-o em um fluxo de usuário.

Importante

A partir de 12 de julho de 2021, se os clientes do Microsoft Entra B2B configurarem novas integrações do Google para uso com inscrição de autoatendimento para seus aplicativos personalizados ou de linha de negócios, a autenticação com identidades do Google não funcionará até que as autenticações sejam movidas para as visualizações da Web do sistema. Mais informações.
Em 30 de setembro de 2021,o Google desativou o suporte de login de visualização da Web incorporado. Se seus aplicativos autenticarem usuários com uma exibição da Web incorporada e você estiver usando a federação do Google com o Azure AD B2C ou o Microsoft Entra B2B para convites de usuários externos ou inscrição de autoatendimento, os usuários do Google Gmail não poderão se autenticar. Mais informações.

Criar um conector de API

Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Usuário.
Navegue até Entra ID>Identidades Externas>Visão Geral.
Selecione Todos os conectores de API e, em seguida, selecione Novo conector de API.
Forneça um nome para exibição para a chamada. Por exemplo, Verifique o status de aprovação.
Forneça a URL do ponto de extremidade para a chamada de API.
Escolha o Tipo de autenticação e configure as informações de autenticação para chamar sua API. Saiba como proteger seu conector de API.
Selecione Guardar.

A solicitação enviada à sua API

Um conector de API se materializa como uma solicitação HTTP POST , enviando atributos de usuário ('declarações') como pares chave-valor em um corpo JSON. Os atributos são serializados de forma semelhante às propriedades do usuário do Microsoft Graph .

Exemplo de pedido

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

Somente as propriedades do utilizador e os atributos personalizados listados na Entra ID>Identidades Externas>Visão Geral>Experiência de Atributos Personalizados do Utilizador estão disponíveis para serem enviados na solicitação.

Os atributos personalizados existem no formato extension_<extensions-app-id>_AttributeName no diretório. Sua API deve esperar receber declarações nesse mesmo formato serializado. Para obter mais informações sobre atributos personalizados, consulte definir atributos personalizados para fluxos de inscrição de autoatendimento.

Além disso, as declarações são normalmente enviadas em todas as solicitações:

Localidades da interface do usuário ('ui_locales') - Localidades de um usuário final configuradas em seu dispositivo, que sua API pode usar para retornar respostas internacionalizadas.

Endereço de e-mail ('email') ou identidades ('identidades') - essas declarações podem ser usadas pela sua API para identificar o usuário final que está se autenticando no aplicativo.

Importante

Se uma declaração não tiver um valor no momento em que o ponto de extremidade da API for chamado, ela não será enviada para a API. Sua API deve ser projetada para verificar e lidar explicitamente com o caso em que uma reivindicação não está na solicitação.

Habilitar o conector de API em um fluxo de usuário

Siga estas etapas para adicionar um conector de API a um fluxo de usuário de inscrição de autoatendimento.

Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Usuário.
Navegue até Entra ID>Identidades Externas>Visão Geral.
Selecione Fluxos de usuário e, em seguida, selecione o fluxo de usuário ao qual você deseja adicionar o conector de API.
Selecione conectores de API e, em seguida, selecione os pontos de extremidade de API que você deseja invocar nas seguintes etapas no fluxo de usuário:
- Depois de federar com um provedor de identidade durante a inscrição
- Antes de criar o usuário
Selecione Guardar.

Um conector de API nesta etapa do processo de inscrição é invocado imediatamente após o usuário se autenticar com um provedor de identidade (como Google, Facebook ou Microsoft Entra ID). Esta etapa precede a página de coleta de atributos, que é o formulário apresentado ao usuário para coletar atributos de usuário.

Exemplo de solicitação enviada à API nesta etapa

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

As declarações exatas enviadas para a API dependem de quais informações são fornecidas pelo provedor de identidade. 'e-mail' é sempre enviado.

Tipos de resposta esperados da API da Web nesta etapa

Quando a API da Web recebe uma solicitação HTTP do Microsoft Entra ID durante um fluxo de usuário, ela pode retornar estas respostas:

Resposta de continuação
Resposta de bloqueio

Resposta de continuação

Uma resposta de continuação indica que o fluxo do usuário deve continuar para a próxima etapa: a página de coleta de atributos.

Em uma resposta de continuação, a API pode retornar uma declaração que:

Pré-preenche o campo de entrada na página de coleção de atributos.

Veja um exemplo de uma resposta de continuação.

Resposta de bloqueio

Uma resposta de bloqueio sai do fluxo do usuário. A API pode emitir propositadamente uma resposta de bloqueio para interromper a continuação do fluxo do usuário, exibindo uma página de bloqueio para o usuário. A página de bloqueio exibe o userMessage fornecido pela API.

Veja um exemplo de uma resposta de bloqueio.

Antes de criar o usuário

Um conector de API nesta etapa do processo de inscrição é invocado após a página de coleta de atributos, se uma estiver incluída. Esta etapa é sempre invocada antes que uma conta de usuário seja criada no Microsoft Entra ID.

Exemplo de solicitação enviada à API nesta etapa

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

As declarações exatas enviadas para a API dependem de quais informações são coletadas do usuário ou fornecidas pelo provedor de identidade.

Tipos de resposta esperados da API da Web nesta etapa

Quando a API da Web recebe uma solicitação HTTP do Microsoft Entra ID durante um fluxo de usuário, ela pode retornar estas respostas:

Resposta de continuação
Resposta de bloqueio
Resposta de validação

Resposta de continuação

Uma resposta de continuação indica que o fluxo de usuário deve continuar para a próxima etapa: criar o usuário no diretório.

Em uma resposta de continuação, a API pode retornar uma declaração que:

Substitui qualquer valor já atribuído à declaração na página de coleta de atributos.

Veja um exemplo de uma resposta de continuação.

Resposta de bloqueio

Veja um exemplo de uma resposta de bloqueio.

Resposta de erro de validação

Quando a API responde com uma resposta de erro de validação, o fluxo do usuário permanece na página de coleta de atributos e um userMessage é exibido para o usuário. O usuário pode então editar e reenviar o formulário. Este tipo de resposta pode ser usado para validação de entrada.

Veja um exemplo de uma resposta de erro de validação.

Exemplos de respostas

Exemplo de uma resposta de continuação

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}

Parâmetro	Tipo	Obrigatório	Descrição
versão	Cadeia (de carateres)	Sim	A versão da sua API.
ação	Cadeia (de carateres)	Sim	O valor deve ser `Continue`.
<atributoDeUtilizadorIncorporado>	<tipo de atributo>	Não	Os valores podem ser armazenados no diretório se forem selecionados como uma Declaração a receber na configuração do conector da API e atributos de usuário para um fluxo de usuário. Os valores podem ser retornados no token se selecionados como uma declaração de aplicativo.
<extension_{extensions-app-id}_AtributoPersonalizado>	<tipo de atributo>	Não	A reivindicação não precisa conter `_<extensions-app-id>_`, é opcional. Os valores retornados podem substituir os valores coletados de um usuário.

Exemplo de uma resposta de bloqueio

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "There was an error with your request. Please try again or contact support.",
}

Parâmetro	Tipo	Obrigatório	Descrição
versão	Cadeia (de carateres)	Sim	A versão da sua API.
ação	Cadeia (de carateres)	Sim	O valor deve ser `ShowBlockPage`
userMensagem	Cadeia (de carateres)	Sim	A mensagem a apresentar ao utilizador.

Experiência do usuário final com uma resposta de bloqueio

Uma imagem de exemplo de como é a experiência do usuário final depois que uma API retorna uma resposta de bloqueio.

Exemplo de uma resposta de erro de validação

HTTP/1.1 400 Bad Request
Content-type: application/json

{
    "version": "1.0.0",
    "status": 400,
    "action": "ValidationError",
    "userMessage": "Please enter a valid Postal Code.",
}

Parâmetro	Tipo	Obrigatório	Descrição
versão	Cadeia (de carateres)	Sim	A versão da sua API.
ação	Cadeia (de carateres)	Sim	O valor deve ser `ValidationError`.
Situação	Inteiro / String	Sim	Deve ser value `400`, ou `"400"` para uma resposta ValidationError.
userMensagem	Cadeia (de carateres)	Sim	A mensagem a apresentar ao utilizador.

Nota

O código de status HTTP deve ser "400", além do valor "status" no corpo da resposta.

Experiência do usuário final com uma resposta de erro de validação

Uma imagem de exemplo de como é a experiência do usuário final depois que uma API retorna uma resposta de erro de validação.

Práticas recomendadas e como solucionar problemas

Usando funções de nuvem sem servidor

As funções sem servidor, como gatilhos HTTP no Azure Functions, fornecem uma maneira de criar pontos de extremidade de API para usar com o conector de API. Você pode usar a função de nuvem sem servidor para, por exemplo, executar lógica de validação e limitar inscrições a domínios de e-mail específicos. A função de nuvem sem servidor também pode chamar e invocar outras APIs da Web, armazenamentos de dados e outros serviços de nuvem para cenários complexos.

Melhores práticas

Certifique-se de que:

Sua API está seguindo os contratos de solicitação e resposta da API, conforme descrito anteriormente.
A URL do ponto de extremidade do conector da API aponta para o ponto de extremidade da API correto.
Sua API verifica explicitamente se há valores nulos de declarações recebidas das quais ela depende.
Sua API implementa um método de autenticação descrito em proteger seu conector de API.
Sua API responde o mais rápido possível para garantir uma experiência de usuário fluida.
- O Microsoft Entra ID aguarda um máximo de 20 segundos para receber uma resposta. Se nenhum for recebido, ele fará mais uma tentativa (repetir) de chamar sua API.
- Se estiver usando uma função sem servidor ou um serviço Web escalável, use um plano de hospedagem que mantenha a API "acordada" ou "quente" na produção. Para o Azure Functions, recomendamos usar no mínimo o plano Premium.
Garanta a alta disponibilidade da sua API.
Monitore e otimize o desempenho de APIs downstream, bancos de dados ou outras dependências de sua API.
Seus pontos de extremidade devem estar em conformidade com os requisitos de segurança do Microsoft Entra TLS e de cifra. Para obter mais informações, consulte TLS e requisitos do conjunto de codificações.

Utilizar o registo

Em geral, é útil usar as ferramentas de log habilitadas pelo serviço de API da Web, como o Application insights, para monitorar sua API em busca de códigos de erro inesperados, exceções e desempenho insatisfatório.

Monitore códigos de status HTTP que não sejam HTTP 200 ou 400.
Um código de status HTTP 401 ou 403 normalmente indica que há um problema com sua autenticação. Verifique novamente a camada de autenticação da API e a configuração correspondente no conector da API.
Use níveis mais agressivos de registro em log (por exemplo, "trace" ou "debug") no desenvolvimento, se necessário.
Monitore sua API para longos tempos de resposta.

Próximos passos

Saiba como adicionar um fluxo de trabalho de aprovação personalizado à inscrição de autoatendimento
Comece com nossos exemplos de início rápido.

Partilhar via

Adicionar um conector de API a um fluxo de usuário

Criar um conector de API

A solicitação enviada à sua API

Habilitar o conector de API em um fluxo de usuário

Depois de federar com um provedor de identidade durante a inscrição

Exemplo de solicitação enviada à API nesta etapa

Tipos de resposta esperados da API da Web nesta etapa

Resposta de continuação

Resposta de bloqueio

Antes de criar o usuário

Exemplo de solicitação enviada à API nesta etapa

Tipos de resposta esperados da API da Web nesta etapa

Resposta de continuação

Resposta de bloqueio

Resposta de erro de validação

Exemplos de respostas

Exemplo de uma resposta de continuação

Exemplo de uma resposta de bloqueio

Exemplo de uma resposta de erro de validação

Práticas recomendadas e como solucionar problemas

Usando funções de nuvem sem servidor

Melhores práticas

Utilizar o registo

Próximos passos

Comentários

Recursos adicionais