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

Artigo
02/05/2024

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 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 as visualizações da Web do sistema. Mais informações.
A partir de 30 de setembro de 2021, o Google está desativando o suporte de login incorporado à visualização da Web. Se seus aplicativos autenticarem usuários com uma visualizaçã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

Gorjeta

As etapas neste artigo podem variar ligeiramente com base no portal a partir do qual você começou.

Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Usuário.
Navegue até Visão>geral de identidades>externas.
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 usuário e os atributos personalizados listados na Visão geral>das> identidades>externas de identidade A experiência de atributos de usuário personalizados está disponível para ser enviada 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') - Localidade(s) de um usuário final conforme configurado em seu dispositivo. Isso pode ser usado pela sua API 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, a declaração 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é Visão>geral de identidades>externas.
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 declarações. Se uma declaração for retornada pela API, ela fará o seguinte:

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. Ele pode ser emitido propositalmente pela API 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 declarações. Se uma declaração for retornada pela API, ela fará o seguinte:

Substitui qualquer valor que já tenha sido 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	Type	Obrigatório	Description
versão	Cadeia (de carateres)	Sim	A versão da sua API.
action	Cadeia (de carateres)	Sim	O valor deve ser `Continue`.
<builtInUserAttribute>	<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}_CustomAttribute>	<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	Type	Obrigatório	Description
versão	Cadeia (de carateres)	Sim	A versão da sua API.
action	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	Type	Obrigatório	Description
versão	Cadeia (de carateres)	Sim	A versão da sua API.
action	Cadeia (de carateres)	Sim	O valor deve ser `ValidationError`.
status	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 acima.
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.

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

Recursos adicionais