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 seleção branca. Locatários da força de trabalho Círculo branco com um símbolo X cinza. Locatários externos (saiba mais)

Para usar um conector de API, você deve primeiro criar o conector de API e habilitá-lo 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 a 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 exibições da Web do sistema. Saiba mais.
Em 30 de setembro de 2021, o Google descontinuou o suporte para login via web-view incorporado. Se seus aplicativos autenticarem usuários com uma exibição da Web inserida e você estiver usando a federação do Google com o Azure AD B2C ou o Microsoft Entra B2B para convites de usuário externos ou inscrição de autoatendimento, os usuários do Google Gmail não poderão se autenticar. Saiba mais.

Criar um conector de API

Entre no centro de administração do Microsoft Entra como, no mínimo, Administrador de Usuários.
Navegue até Entra ID>Identidades Externas>Visão Geral.
Selecione Todos os conectores de API e depois Novo conector de API.
Forneça um nome de exibição para a chamada. Por exemplo, Verificar o status de aprovação.
Forneça a URL do ponto de extremidade para a chamada à API.
Escolha o Tipo de autenticação e configure as informações de autenticação para chamar a API. Saiba como Proteger seu Conector de API.
Clique em Salvar.

A solicitação enviada à 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 da mesma forma para as propriedades de usuário doMicrosoft Graph.

Solicitação de exemplo

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 usuário e os atributos personalizados listados na experiência de Entra ID>Identidades Externas>Visão Geral>Atributos Personalizados de Usuário estão disponíveis para serem enviados na solicitação.

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

Além disso, normalmente essa declaração é enviada em toda solicitação:

Localidades de 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 email ("email") ou identidades ("identities"): 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 à API. Sua API deve ser projetada para verificar e manipular explicitamente o caso em que uma declaraçã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 por autoatendimento.

Entre no centro de administração do Microsoft Entra como, no mínimo, Administrador de Usuários.
Navegue até Entra ID>Identidades Externas>Visão Geral.
Selecione Fluxos de usuário e depois selecione o fluxo de usuário no qual deseja adicionar o conector de API.
Selecione Conectores de APIe, em seguida, selecione os pontos de extremidade de API que deseja invocar nas etapas a seguir no fluxo do usuário:
- Após a federação com um provedor de identidade durante a inscrição
- Antes de criar o usuário
Clique em Salvar.

Nesta etapa do processo de inscrição, um conector de API é invocado imediatamente depois que o usuário se autentica com um provedor de identidade (como o Google, o Facebook ou Microsoft Entra ID). Essa etapa precede a página de coleta de atributos, que é o formulário apresentado ao usuário para coletar os atributos de usuário.

Exemplo de solicitação enviada para a 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 à API dependem de quais informações são fornecidas pelo provedor de identidade. ‘email’ é sempre enviado.

Tipos de resposta esperados da API Web nesta etapa

Quando a API Web recebe uma solicitação HTTP da ID do Microsoft Entra durante um fluxo do 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 seguir para a próxima etapa: a página de coleção de atributos.

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

Preenche previamente o campo de entrada na página de coleção de atributos.

Confira 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 propositalmente 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 bloco exibe o userMessage fornecido pela API.

Confira um exemplo de uma resposta de bloqueio.

Antes de criar o usuário

Nesta etapa no processo de inscrição, um conector de API é invocado após a página de coleção de atributos, se incluída. Essa etapa é sempre invocada antes da criação de uma conta de usuário no Microsoft Entra.

Exemplo de solicitação enviada para a 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 à API dependem de quais informações são coletadas do usuário ou foram fornecidas pelo provedor de identidade.

Tipos de resposta esperados da API Web nesta etapa

Quando a API Web recebe uma solicitação HTTP da ID do Microsoft Entra durante um fluxo do 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 do usuário deve seguir 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 de que:

Substituirá qualquer valor já atribuído à declaração da página de coleção de atributos.

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

Resposta de bloqueio

Confira 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 coleção de atributos e um userMessage é exibido para o usuário. O usuário pode editar e reenviar o formulário. Esse tipo de resposta pode ser usado para validação de entrada.

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

Respostas de exemplo

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
version	Cadeia de caracteres	Sim	A versão da API.
ação	Cadeia de caracteres	Sim	O valor deve ser `Continue`.
<atributoDeUsuárioIntegrado>	<tipo de atributo>	Não	Os valores podem ser armazenados no diretório se forem selecionados como uma Declaração para receber na configuração do conector de API e nos Atributos de usuário para um fluxo de usuário. Os valores podem ser retornados no token se uma Declaração de aplicativo estiver selecionada.
<extensão_{extensions-app-id}_AtributoPersonalizado>	<tipo de atributo>	Não	A declaração não precisa conter `_<extensions-app-id>_`, pois isso é 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
version	Cadeia de caracteres	Sim	A versão da API.
ação	Cadeia de caracteres	Sim	O valor deve ser `ShowBlockPage`
mensagem do usuário	Cadeia de caracteres	Sim	Mensagem a ser exibida ao usuário.

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

Uma imagem de exemplo da aparência da 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
version	Cadeia de caracteres	Sim	A versão da API.
ação	Cadeia de caracteres	Sim	O valor deve ser `ValidationError`.
status	Inteiro / cadeia de caracteres	Sim	Deve ser valor `400` ou `"400"` para uma resposta ValidationError.
mensagem do usuário	Cadeia de caracteres	Sim	Mensagem a ser exibida ao usuário.

Observação

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

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

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

Práticas recomendadas e como solucionar problemas

Usar funções de nuvem sem servidor

As funções sem servidor, como os 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 a lógica de validação e limitar as entradas a domínios de email específicos. A função de nuvem sem servidor também pode chamar e invocar outras APIs Web, armazenamentos de dados e outros serviços de nuvem para cenários complexos.

Práticas recomendadas

Verifique se:

Sua API está seguindo os contratos de solicitação e resposta da API, conforme descrito anteriormente.
A URL do ponto de extremidade do conector de API aponta para o ponto de extremidade de API correto.
A API verifica explicitamente se há valores nulos de declarações recebidas das quais depende.
Sua API implementa um método de autenticação descrito em proteger seu conector de API.
A API responde o mais rápido possível para garantir uma experiência de usuário fluida.
- O Microsoft Entra ID aguarda até, no máximo, 20 segundos para receber uma resposta. Caso não receba nenhuma resposta, ele faz mais uma tentativa (repetição) de chamar sua API.
- Se estiver usando uma função sem servidor ou um serviço Web escalonável, use um plano de hospedagem que mantenha a API "ativa" ou "quente" na produção. No caso do 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 TLS e criptografia do Microsoft Entra. Para obter mais informações, consulte requisitos do conjunto de TLS e criptografia.

Usar o log

Em geral, é útil usar as ferramentas de registro em log habilitadas pelo serviço de API Web, como o Application Insights, para monitorar a API para códigos de erro inesperados, exceções e baixo desempenho.

Monitore os códigos de status HTTP que não são HTTP 200 ou 400.
Um código de status HTTP 401 ou 403 normalmente indica que há um problema com a autenticação. Verifique a camada de autenticação da API e a configuração correspondente no conector da API.
Se necessário, use níveis mais agressivos do log (por exemplo, “rastreamento” ou “depuração”) no desenvolvimento.
Monitore a API para tempos de resposta longos.

Próximas etapas

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

Compartilhar via

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

Criar um conector de API

A solicitação enviada à API

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

Após a federação com um provedor de identidade durante a inscrição

Exemplo de solicitação enviada para a API nesta etapa

Tipos de resposta esperados da API Web nesta etapa

Resposta de continuação

Resposta de bloqueio

Antes de criar o usuário

Exemplo de solicitação enviada para a API nesta etapa

Tipos de resposta esperados da API Web nesta etapa

Resposta de continuação

Resposta de bloqueio

Resposta de erro de validação

Respostas de exemplo

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

Usar funções de nuvem sem servidor

Práticas recomendadas

Usar o log

Próximas etapas

Comentários

Recursos adicionais