Utilizar conectores de API para personalizar e expandir fluxos de utilizador de inscrição e políticas personalizadas com origens de dados de identidade externa

Descrição Geral

Enquanto programador ou administrador de TI, pode utilizar conectores de API para integrar os fluxos de utilizadores de inscrição com APIs REST para personalizar a experiência de inscrição e integrar em sistemas externos. Por exemplo, com os conectores de API, pode:

• Valide os dados de entrada do utilizador. Validar relativamente a dados de utilizador inválidos ou inválidos. Por exemplo, pode validar dados fornecidos pelo utilizador relativamente a dados existentes num arquivo de dados externos ou lista de valores permitidos. Se for inválido, pode pedir a um utilizador para fornecer dados válidos ou impedir que o utilizador continue o fluxo de inscrição.
• Verifique a identidade do utilizador. Utilize um serviço de verificação de identidade ou origens de dados de identidade externa para adicionar um nível adicional de segurança às decisões de criação de contas.
• Integrar com um fluxo de trabalho de aprovação personalizado. Ligue-se a um sistema de aprovação personalizado para gerir e limitar a criação de contas.
• Aumente os tokens com atributos de origens externas. Melhore os tokens com atributos sobre o utilizador de origens externas ao Azure AD B2C, como sistemas cloud, arquivos de utilizadores personalizados, sistemas de permissões personalizados, serviços de identidade legados e muito mais.
• Substituir atributos de utilizador. Reformate ou atribua um valor a um atributo recolhido pelo utilizador. Por exemplo, se um utilizador introduzir o nome próprio em todas as letras minúsculas ou em maiúsculas, pode formatar o nome apenas com a primeira letra em maiúsculas.
• Executar lógica de negócio personalizada. Pode acionar eventos a jusante nos seus sistemas cloud para enviar notificações push, atualizar bases de dados empresariais, gerir permissões, auditar bases de dados e efetuar outras ações personalizadas.

Um conector de API fornece Azure AD B2C com as informações necessárias para chamar o ponto final da API ao definir o URL do ponto final HTTP e a autenticação para a chamada à API. Depois de configurar um conector de API, pode ativá-lo para um passo específico num fluxo de utilizador. Quando um utilizador atinge esse passo no fluxo de inscrição, o conector da API é invocado e materializa-se como um pedido HTTP POST à sua API, enviando informações do utilizador ("afirmações") como pares chave-valor num corpo JSON. A resposta da API pode afetar a execução do fluxo de utilizador. Por exemplo, a resposta da API pode impedir um utilizador de se inscrever, pedir ao utilizador para reintroduzir informações ou substituir atributos de utilizador.

Onde pode ativar um conector de API num fluxo de utilizador

Existem três locais num fluxo de utilizador onde pode ativar um conector de API:

• Depois de federar com um fornecedor de identidade durante a inscrição – aplica-se apenas a experiências de inscrição
• Antes de criar o utilizador – aplica-se apenas a experiências de inscrição
• Antes de enviar o token (pré-visualização) – aplica-se a inscrições e inícios de sessão

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

Neste passo, um conector de API no processo de inscrição é invocado imediatamente após o utilizador se autenticar com um fornecedor de identidade (como Google, Facebook e Microsoft Entra ID). Este passo precede a página de coleção de atributos, que é o formulário apresentado ao utilizador para recolher atributos de utilizador. Este passo não é invocado se um utilizador estiver a registar-se numa conta local. Seguem-se exemplos de cenários do conector de API que poderá ativar neste passo:

• Utilize o e-mail ou a identidade federada que o utilizador forneceu para procurar afirmações num sistema existente. Devolva estas afirmações do sistema existente, preencha previamente a página da coleção de atributos e disponibilize-as para devolução no token.
• Implementar uma lista de permissões ou bloqueios com base na identidade social.

Antes de criar o utilizador

Neste passo, um conector de API no processo de inscrição é invocado após a página da coleção de atributos, se estiver incluído um. Este passo é sempre invocado antes de ser criada uma conta de utilizador. Seguem-se exemplos de cenários que poderá ativar neste momento durante a inscrição:

• Valide os dados de entrada do utilizador e peça a um utilizador para submeter novamente os dados.
• Bloquear a inscrição de um utilizador com base nos dados introduzidos pelo utilizador.
• Verifique a identidade do utilizador.
• Consulte sistemas externos para dados existentes sobre o utilizador para devolvê-lo no token da aplicação ou armazená-lo no Microsoft Entra ID.

Antes de enviar o token (pré-visualização)

Neste passo, é invocado um conector de API no processo de inscrição ou início de sessão antes de um token ser emitido. Seguem-se exemplos de cenários que poderá ativar neste passo:

• Melhorar o token com atributos sobre o utilizador de origens diferentes do diretório, incluindo sistemas de identidade legados, sistemas de RH, arquivos de utilizadores externos e muito mais.
• Melhorar o token com atributos de grupo ou função que armazena e gere no seu próprio sistema de permissões.
• Aplicar transformações ou manipulações de afirmações a valores de afirmações no diretório.

O Identity Experience Framework, subjacente ao Azure Active Directory B2C (Azure AD B2C), pode ser integrado com APIs RESTful num percurso de utilizador. Este artigo mostra como criar um percurso de utilizador que interage com um serviço RESTful através de um perfil técnico RESTful.

Ao utilizar Azure AD B2C, pode adicionar a sua própria lógica de negócio a um percurso de utilizador ao chamar o seu próprio serviço RESTful. O Identity Experience Framework pode enviar e receber dados do seu serviço RESTful para trocar afirmações. Pode, por exemplo:

• Utilize a origem de dados de identidade externa para validar os dados de entrada do utilizador. Por exemplo, pode verificar se o endereço de e-mail fornecido pelo utilizador existe na base de dados do cliente e, caso contrário, apresentar um erro. Também pode pensar nos conectores de API como uma forma de suportar webhooks de saída porque a chamada é efetuada quando ocorre um evento, por exemplo, uma inscrição.
• Processar afirmações. Se um utilizador introduzir o nome próprio em todas as letras minúsculas ou em maiúsculas, a API REST pode formatar o nome apenas com a primeira letra em maiúsculas e devolvê-lo ao Azure AD B2C. No entanto, ao utilizar uma política personalizada, a opção ClaimsTransformations é preferencial em vez de chamar uma API RESTful.
• Melhore dinamicamente os dados dos utilizadores ao integrar ainda mais com aplicações de linha de negócio empresariais. O serviço RESTful pode receber o endereço de e-mail do utilizador, consultar a base de dados do cliente e devolver o número de fidelização do utilizador para Azure AD B2C. Em seguida, as afirmações de devolução podem ser armazenadas na conta Microsoft Entra do utilizador, avaliadas nos passos de orquestração seguintes ou incluídas no token de acesso.
• Executar lógica de negócio personalizada. Pode enviar notificações push, atualizar bases de dados empresariais, executar um processo de migração de utilizadores, gerir permissões, auditar bases de dados e executar outros fluxos de trabalho.

Chamar um serviço RESTful

A interação inclui uma troca de afirmações de informações entre as afirmações da API REST e Azure AD B2C. Pode estruturar a integração com os serviços RESTful das seguintes formas:

• Perfil técnico de validação. A chamada para o serviço RESTful ocorre dentro de um perfil técnico de validação do perfil técnico auto-afirmado especificado ou de um controlo de visualização de verificação de um controlo de visualização. O perfil técnico de validação valida os dados fornecidos pelo utilizador antes de o percurso do utilizador avançar. Com o perfil técnico de validação, pode:

  • Enviar afirmações para a API REST.
  • Valide afirmações e lance mensagens de erro personalizadas que são apresentadas ao utilizador.
  • Envie afirmações da API REST para os próximos passos de orquestração.

• Troca de afirmações. Uma troca de afirmações diretas pode ser configurada ao chamar um perfil técnico da API REST diretamente a partir de um passo de orquestração de um percurso de utilizador. Esta definição está limitada a:

  • Enviar afirmações para a API REST.
  • Valide afirmações e lance mensagens de erro personalizadas que são devolvidas à aplicação.
  • Envie afirmações da API REST para os próximos passos de orquestração.

Pode adicionar uma chamada à API REST em qualquer passo no percurso do utilizador definido por uma política personalizada. Por exemplo, pode chamar uma API REST:

• Durante o início de sessão, imediatamente antes de Azure AD B2C valida as credenciais.
• Imediatamente após o início de sessão.
• Antes de Azure AD B2C cria uma nova conta no diretório.
• Depois de Azure AD B2C cria uma nova conta no diretório.
• Antes de Azure AD B2C emite um token de acesso.

Enviar dados

No perfil técnico RESTful, o InputClaims elemento contém uma lista de afirmações a enviar para o seu serviço RESTful. Pode mapear o nome da afirmação para o nome definido no serviço RESTful, definir um valor predefinido e utilizar resoluções de afirmações.

Pode configurar a forma como as afirmações de entrada são enviadas para o fornecedor de afirmações RESTful com o atributo SendClaimsIn. Os valores possíveis são:

• Corpo, enviado no corpo do pedido HTTP POST no formato JSON.
• Formulário, enviado no corpo do pedido HTTP POST num formato de valor de chave separado "&" e comercial.
• Cabeçalho, enviado no cabeçalho do pedido HTTP GET.
• QueryString, enviada na cadeia de consulta de pedido HTTP GET.

Quando a opção Corpo está configurada, o perfil técnico da API REST permite-lhe enviar um payload JSON complexo para um ponto final. Para obter mais informações, veja Enviar um payload JSON.

A receber dados

O OutputClaims elemento do perfil técnico RESTful contém uma lista de afirmações devolvidas pela API REST. Poderá ter de mapear o nome da afirmação definida na política para o nome definido na API REST. Também pode incluir afirmações que não são devolvidas pelo fornecedor de identidade da API REST, desde que defina o atributo DefaultValue.

As afirmações de saída analisadas pelo fornecedor de afirmações RESTful esperam sempre analisar uma resposta de Corpo JSON simples, como:

{
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "loyaltyNumber":  1234
}

As afirmações de saída devem ter um aspeto semelhante ao seguinte fragmento xml:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
</OutputClaims>

Processar valores nulos

É utilizado um valor nulo numa base de dados quando o valor numa coluna é desconhecido ou está em falta. Não inclua chaves JSON com um null valor. No exemplo seguinte, o e-mail devolve null o valor:

{
  "name": "Emily Smith",
  "email": null,
  "loyaltyNumber":  1234
}

Quando um elemento é nulo:

• Omita o par chave-valor do JSON.
• Devolver um valor que corresponda ao tipo de dados de afirmação B2C Azure AD. Por exemplo, para um tipo de dados, devolva uma string cadeia ""vazia. Para um integer tipo de dados, devolva um valor 0zero. Para um tipo de dateTime dados, devolva um valor 1970-00-00T00:00:00.0000000Zmínimo .

O exemplo seguinte demonstra como lidar com um valor nulo. O e-mail é omitido do JSON:

{
  "name": "Emily Smith",
  "loyaltyNumber":  1234
}

Analisar um corpo JSON aninhado

Para analisar uma resposta do corpo JSON aninhada, defina os metadados ResolveJsonPathsInJsonTokens como verdadeiros. Na afirmação de saída, defina PartnerClaimType como o elemento de caminho JSON que pretende exportar.

"contacts": [
  {
    "id": "MAINCONTACT_1",
    "person": {
      "name": "Emily Smith",
      "loyaltyNumber":  1234,
      "emails": [
        {
          "id": "EMAIL_1",
          "type": "WORK",
          "email": "email@domain.com"
        }
      ]
    }
  }
],

As afirmações de saída devem ter o seguinte aspeto:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts[0].person.name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts[0].person.emails[0].email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts[0].person.loyaltyNumber" />
</OutputClaims>

Localizar a API REST

Num perfil técnico RESTful, poderá querer enviar o idioma/região da sessão atual e, se necessário, enviar uma mensagem de erro localizada. Com a resolução de afirmações, pode enviar uma afirmação contextual, como o idioma do utilizador. O exemplo seguinte mostra um perfil técnico RESTful que demonstra este cenário.

<TechnicalProfile Id="REST-ValidateUserData">
  <DisplayName>Validate user input data</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

Processar mensagens de erro

A API REST poderá ter de devolver uma mensagem de erro, como "O utilizador não foi encontrado no sistema CRM". Se ocorrer um erro, a API REST deverá devolver uma mensagem de erro HTTP 409 (Código de estado de resposta a conflitos). Para obter mais informações, veja o perfil técnico RESTful.

Este comportamento só pode ser alcançado ao chamar um perfil técnico da API REST a partir de um perfil técnico de validação. Permitir que o utilizador corrija os dados na página e execute novamente a validação após a submissão da página.

Se referenciar um perfil técnico da API REST diretamente a partir de um percurso de utilizador, o utilizador é redirecionado de volta para a aplicação da entidade confiadora com a mensagem de erro relevante.

• Saiba como adicionar um conector de API para modificar experiências de inscrição
• Saiba como adicionar um conector de API para enriquecer tokens com afirmações externas
• Saiba como proteger o Conector de API
• Introdução aos nossos exemplos

Veja os seguintes artigos para obter exemplos de como utilizar um perfil técnico RESTful:

• Instruções: adicionar um conector de API a um fluxo de utilizador de inscrição
• Instruções: Adicionar trocas de afirmações da API REST a políticas personalizadas no Azure Active Directory B2C
• Proteger os serviços da API REST
• Referência: Perfil técnico RESTful