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

Aplica-se a: Locatários da força de trabalho 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 com o Google para serem usadas com a inscrição por autoatendimento em 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 exibições da Web do sistema. Saiba mais.
• A partir de 30 de setembro de 2021, o Google deixará de dar suporte para o logon de exibição da Web integrado. Caso seus aplicativos autentiquem usuários com um modo de exibição da Web inserido e você use a federação do Google com o Azure AD B2C ou o Microsoft Entra B2B para convites de usuário externo ou de inscrição por autoatendimento, os usuários do Gmail não poderão se autenticar. Saiba mais.

Criar um conector de API

Dica

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

1. Entre no centro de administração do Microsoft Entra como, no mínimo, Administrador de Usuários.

2. Navegue até Identidade>Identidades Externas>Visão geral.

3. Selecione Todos os conectores de API e depois Novo conector de API.

   

4. Forneça um nome de exibição para a chamada. Por exemplo, Verificar o status de aprovação.

5. Forneça a URL do ponto de extremidade para a chamada à API.

6. 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.

   

7. Selecione 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 de usuário e os atributos personalizados listados na experiência Identidade>Identidades Externas>Visão geral>Atributos de usuário personalizados 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 da IU ('ui_locales')- as localidades de um usuário final, conforme configuradas no dispositivo.42 Isso pode ser usado pela sua API 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 de API for chamado, a declaração não será enviada à API. A API deve ser criada para verificar explicitamente e tratar 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.

1. Entre no centro de administração do Microsoft Entra como, no mínimo, Administrador de Usuários.

2. Navegue até Identidade>Identidades Externas>Visão geral.

3. Selecione Fluxos de usuário e depois selecione o fluxo de usuário no qual deseja adicionar o conector de API.

4. Selecione Conectores de API e depois 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

   

5. Selecione Save.

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

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 declarações. Se uma declaração for retornada pela API, a declaração fará o seguinte:

• 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. Ela pode ser emitida intencionalmente pela API para interromper a continuação do fluxo do usuário, exibindo uma página de bloco ao 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 declarações. Se uma declaração for retornada pela API, a declaração fará o seguinte:

• Substituirá qualquer valor que já tenha sido atribuído à declaração da 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. Ela pode ser emitida intencionalmente pela API para interromper a continuação do fluxo do usuário, exibindo uma página de bloco ao usuário. A página de bloco exibe o userMessage fornecido pela API.

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	Type	Obrigatória	Descrição
version	Cadeia de caracteres	Sim	A versão da API.
ação	String	Sim	O valor precisa ser Continue.
<builtInUserAttribute>	<attribute-type>	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.
<extension_{extensions-app-id}_CustomAttribute>	<attribute-type>	No	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	Type	Obrigatória	Descrição
version	Cadeia de caracteres	Sim	A versão da API.
ação	String	Sim	O valor deve ser ShowBlockPage
userMessage	String	Sim	Mensagem a ser exibida ao usuário.

Experiência do usuário final com 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ória	Descrição
version	Cadeia de caracteres	Sim	A versão da API.
ação	String	Sim	O valor precisa ser ValidationError.
status	Inteiro / cadeia de caracteres	Sim	Deve ser valor 400 ou "400" para uma resposta ValidationError.
userMessage	String	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

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:

• A API está seguindo os contratos de solicitação e resposta da API, conforme descrito acima.
• 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 registro em 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 de registro em 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.