Enriquecer tokens com declarações de fontes externas usando conectores de API

Artigo
05/23/2023

Antes de começar, use o seletor Escolher um tipo de política para escolher o tipo de política que você está configurando. O Azure Active Directory B2C oferece dois métodos para definir como os usuários interagem com seus aplicativos: por meio de fluxos dos usuários predefinidos ou de políticas personalizadas totalmente configuráveis. As etapas necessárias neste artigo são diferentes para cada método.

O Azure Active Directory B2C (Azure AD B2C) permite que os desenvolvedores de identidade integrem uma interação com uma API RESTful em um fluxo de usuário usando os conectores de API. Ele permite que os desenvolvedores recuperem dinamicamente dados de fontes de identidade externas. No final deste passo a passo, você poderá criar um fluxo de usuário Azure AD B2C que interage com APIs para enriquecer tokens com informações de fontes externas.

Você pode usar conectores de API aplicados à etapa antes de enviar o token (versão prévia) para enriquecer os tokens para seus aplicativos com informações de fontes externas. Quando um usuário entra ou se inscreve, o Azure AD B2C chamará o ponto de extremidade de API configurado no conector de API, que pode consultar informações sobre um usuário em serviços downstream, como serviços de nuvem, armazenamentos de usuários personalizados, sistemas de permissões personalizados, sistemas de identidade herdados e muito mais.

Observação

Esse recurso está em uma versão prévia.

Você pode criar um ponto de extremidade da API usando uma das nossas amostras.

Pré-requisitos

Criar um fluxo do usuário para que os usuários podem se registrar e entrar no seu aplicativo.
Registrar um aplicativo Web.

Conclua as etapas em Introdução às políticas personalizadas no Active Directory B2C
Registrar um aplicativo Web.

Um ponto de extremidade de API. Você pode criar um ponto de extremidade da API usando uma das nossas amostras.

Criar um conector de API

Para usar um conector de API, você deve primeiro criar o conector de API e habilitá-lo em um fluxo de usuário.

Entre no portal do Azure.
Em Serviços do Azure, selecione Azure AD B2C.
Selecione osConectores de API e depois Novo conector de API.
Forneça um nome de exibição para a chamada. Por exemplo, Enriquecer token de uma fonte externa.
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.
Selecione Salvar.

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.

Entre no portal do Azure.
Em Serviços do Azure, selecione Azure AD B2C.
Selecione Fluxos de usuário e depois selecione o fluxo de usuário no qual deseja adicionar o conector de API.
Selecione Conectores de API e depois selecione os pontos de extremidade de API que deseja invocar na etapa Antes de enviar o token (versão prévia) no fluxo do usuário:
Selecione Salvar.

Essa etapa existe apenas para os fluxos de usuário Criar conta e entrar (recomendável) , Criar conta (recomendável) e Entrar (recomendável) .

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

Um conector de API nesta etapa é invocado quando um token está prestes a ser emitido durante entradas e inscrições. 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.

POST <API-endpoint>
Content-type: application/json
{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "ab3ec3b2-a435-45e4-b93a-56a005e88bb7",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "client_id": "231c70e8-8424-48ac-9b5d-5623b9e4ccf3",
 "step": "PreTokenIssuance",
 "ui_locales":"en-US"
}

As declarações que são enviadas para a API dependem das informações definidas para o usuário. Somente as propriedades de usuário e os atributos personalizados listados em Azure AD B2C>Atributos 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>_CustomAttribute. A API receberá declarações nesse mesmo formato serializado. Para obter mais informações sobre atributos personalizados, confira Definir atributos personalizados no Azure AD B2C. Além disso, essas declarações são normalmente enviadas em todas as solicitações para essa etapa:

Localidades da IU ('ui_locales') ─ as localidades de um usuário final, conforme configuradas no dispositivo. Isso pode ser usado pela sua API para retornar respostas internacionalizadas.
Etapa ('step') – a etapa ou o ponto no fluxo de usuário para o qual o conector de API foi invocado. O valor desta etapa é
ID do cliente ('client_id') – o valor appId do aplicativo em que um usuário final está se autenticando no fluxo de usuário. Isto não é do aplicativo de recursoappId nos tokens de acesso.
objectId - O identificador do usuário. Você pode usar isso para consultar serviços downstream para obter informações sobre o usuário.

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.

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 uma “resposta de continuação”.

Resposta de continuação

Uma resposta de continuação indica que o fluxo do usuário deve seguir para a próxima etapa: emitir o token. Em uma resposta de continuação, a API pode retornar declarações adicionais. Uma declaração retornada pela API que você deseja retornar no token deve ser uma declaração interna ou definida como um atributo personalizado e deve ser selecionada na configuração de Declarações do aplicativo do fluxo do usuário. O valor da declaração no token será o valor retornado pela API, não pelo valor no diretório. Alguns valores de declaração não podem ser substituídos pela resposta da API. As declarações que podem ser retornadas pela API correspondem ao conjunto encontrado em Atributos do usuário, com exceção de email.

Observação

A API é invocada apenas durante uma autenticação inicial. Ao usar tokens de atualização para obter silenciosamente novos tokens de acesso ou de ID, o token incluirá os valores avaliados durante a autenticação inicial.

Exemplo de resposta

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	Descrição
version	String	Sim	A versão da API.
ação	String	Sim	O valor precisa ser `Continue`.
<builtInUserAttribute>	<attribute-type>	Não	Eles 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>_` e é opcional. Eles podem ser retornados no token se uma Declaração de aplicativo estiver selecionada.

Neste cenário, enriquecemos os dados de token do usuário integrando a um fluxo de trabalho corporativo de linha de negócios. Durante a inscrição ou a entrada com a conta local ou federada, o Azure AD B2C invoca uma API REST para obter os dados de perfil estendido do usuário em uma fonte de dados remota. Neste exemplo, o Azure AD B2C envia o identificador exclusivo do usuário, o objectId. A API REST retorna o saldo da conta do usuário (um número aleatório). Use este exemplo como um ponto de partida para integração com seu próprio sistema CRM, banco de dados de marketing ou qualquer fluxo de trabalho de linha de negócios. Você também pode projetar a interação como um perfil técnico de validação. Isso é adequado quando a API REST for validar dados na tela e retornar declarações. Para obter mais informações, consulte Passo a passo: adicionar um conector de API a um fluxo de usuário de inscrição.

Pré-requisitos

Conclua as etapas em Introdução às políticas personalizadas. Você deve ter uma política personalizada funcional para inscrição e conexão com contas locais.
Saiba como Integrar trocas de declarações da API REST em sua política personalizada no Azure AD B2C.

Preparar um ponto de extremidade da API REST

Para esta explicação, você deve ter uma API REST que valide se o objectId do Azure AD B2C de um usuário está registrado no sistema back-end. Se estiver registrado, a API REST retornará o saldo da conta do usuário. Caso contrário, a API REST registrará a nova conta no diretório e retornará o saldo inicial 50.00. O código JSON a seguir ilustra os dados que o Azure AD B2C enviará para o ponto de extremidade da API REST.

{
    "objectId": "User objectId",
    "lang": "Current UI language"
}

Depois que a API REST validar os dados, ela deverá retornar um HTTP 200 (Ok), com os seguintes dados JSON:

{
    "balance": "760.50"
}

A configuração do ponto de extremidade da API REST está fora do escopo deste artigo. Criamos um exemplo do Azure Functions. Você pode acessar o código completo de função do Azure no GitHub.

Definir declarações

Uma declaração fornece armazenamento temporário de dados durante uma execução de política do Azure AD B2C. Você pode definir declarações na seção de esquema de declarações.

Abra o arquivo de extensões da sua política. Por exemplo, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
Pesquise o elemento BuildingBlocks. Se o elemento não existir, adicione-o.
Localize o elemento ClaimsSchema. Se o elemento não existir, adicione-o.
Adicione as seguintes declarações ao elemento ClaimsSchema.

<ClaimType Id="balance">
  <DisplayName>Your Balance</DisplayName>
  <DataType>string</DataType>
</ClaimType>
<ClaimType Id="userLanguage">
  <DisplayName>User UI language (used by REST API to return localized error messages)</DisplayName>
  <DataType>string</DataType>
</ClaimType>

Adicionar o perfil técnico da API RESTful

Umperfil técnico RESTful fornece suporte para a interface com seu próprio serviço RESTful. O Azure AD B2C envia dados para o serviço RESTful em uma coleçãoInputClaims e recebe dados de volta em uma coleçãoOutputClaims. Localize o elementoClaimsProviders no arquivo TrustFrameworkExtensions.xml e adicione um novo provedor de declarações da seguinte maneira:

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-GetProfile">
      <DisplayName>Get user extended profile Azure Function web hook</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <!-- Set the ServiceUrl with your own REST API endpoint -->
        <Item Key="ServiceUrl">https://your-account.azurewebsites.net/api/GetProfile?code=your-code</Item>
        <Item Key="SendClaimsIn">Body</Item>
        <!-- Set AuthenticationType to Basic or ClientCertificate in production environments -->
        <Item Key="AuthenticationType">None</Item>
        <!-- REMOVE the following line in production environments -->
        <Item Key="AllowInsecureAuthInProduction">true</Item>
      </Metadata>
      <InputClaims>
        <!-- Claims sent to your REST API -->
        <InputClaim ClaimTypeReferenceId="objectId" />
        <InputClaim ClaimTypeReferenceId="userLanguage" PartnerClaimType="lang" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
      </InputClaims>
      <OutputClaims>
        <!-- Claims parsed from your REST API -->
        <OutputClaim ClaimTypeReferenceId="balance" />
      </OutputClaims>
      <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

Neste exemplo, userLanguage será enviado para o serviço REST como lang no conteúdo do JSON. O valor da declaração userLanguage contém a ID de idioma do usuário atual. Para obter mais informações, confira resolvedor de declarações.

Configurar o perfil técnico da API RESTful

Depois de implantar sua API REST, defina os metadados do perfil técnico REST-GetProfile para refletir sua própria API REST, incluindo:

ServiceUrl. A URL do ponto de extremidade da API REST.
SendClaimsIn. Especifique como as declarações de entrada são enviadas para o provedor de declarações RESTful.
AuthenticationType. Definir o tipo de autenticação sendo executada pelo provedor de declarações RESTful como Basic ou ClientCertificate
AllowInsecureAuthInProduction. Em um ambiente de produção, defina esses metadados como false.

Consulte os Metadados do perfil técnico RESTful para obter mais configurações. Os comentários acima de AuthenticationType e AllowInsecureAuthInProduction especificam as alterações que você deve fazer ao mudar para um ambiente de produção. Para saber como proteger suas APIs RESTful para produção, confira Proteger API RESTful.

Adicionar uma etapa de orquestração

Percursos do usuário especificam caminhos explícitos por meio dos quais uma política permite que um aplicativo de terceira parte confiável obtenhas as declarações desejadas para um usuário. Um percurso do usuário é representado como uma sequência de orquestração que deve ser seguida para ter uma transação bem-sucedida. Você pode adicionar ou subtrair etapas de orquestração. Neste caso, você adicionará uma nova etapa de orquestração usada para aumentar as informações fornecidas ao aplicativo após a inscrição ou entrada do usuário por meio da chamada à API REST.

Abra o arquivo base da sua política. Por exemplo, SocialAndLocalAccounts/TrustFrameworkBase.xml.
Pesquise o elemento <UserJourneys>. Copie o elemento inteiro e, em seguida, exclua-o.
Abra o arquivo de extensões da sua política. Por exemplo, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
Cole o <UserJourneys> no arquivo de extensões, após o fechamento do elemento <ClaimsProviders>.

Localize o <UserJourney Id="SignUpOrSignIn"> e adicione a etapa de orquestração a seguir antes da última.

<OrchestrationStep Order="7" Type="ClaimsExchange">
  <ClaimsExchanges>
    <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
  </ClaimsExchanges>
</OrchestrationStep>

Refatore a última etapa de orquestração alterando Order para 8. Suas duas etapas finais de orquestração devem ser semelhantes a estas:

<OrchestrationStep Order="7" Type="ClaimsExchange">
  <ClaimsExchanges>
    <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
  </ClaimsExchanges>
</OrchestrationStep>
<OrchestrationStep Order="8" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="JwtIssuer" />

Repita as duas últimas etapas para os percursos do usuário ProfileEdit e PasswordReset.

Incluir uma declaração no token

Para retornar a declaração balance de volta para o aplicativo de terceira parte confiável, adicione uma declaração de saída ao arquivo SocialAndLocalAccounts/SignUpOrSignIn.xml. A adição de uma declaração de saída emitirá a declaração para o token, após um percurso do usuário bem-sucedido, e será enviada para o aplicativo. Modifique o elemento de perfil técnico na seção de terceira parte confiável para adicionar balance como uma declaração de saída.

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
      <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
      <OutputClaim ClaimTypeReferenceId="balance" DefaultValue="" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

Repita essa etapa para os percursos do usuário ProfileEdit. xml e PasswordReset. xml. Salve os arquivos que você alterou: TrustFrameworkBase.xml e TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml e PasswordReset.xml.

Teste a política personalizada

Entre no portal do Azure.
Se você tiver acesso a vários locatários, selecione o ícone Configurações no menu superior para alternar para o seu locatário do Azure Active Directory B2C no menu Diretórios + assinaturas.
Escolha Todos os serviços no canto superior esquerdo do portal do Azure e pesquise e selecione Registros de aplicativo.
Selecione Estrutura de Experiência de Identidade.
Selecione Carregar política personalizada e carregue os arquivos de política alterados: TrustFrameworkBase.xml e TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml e PasswordReset.xml.
Selecione a política de inscrição ou de entrada carregada e clique no botão Executar agora.
Você conseguirá se inscrever usando um endereço de email ou uma conta do Facebook.
O token enviado de volta ao seu aplicativo inclui a declaração balance.

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584961516,
  "nbf": 1584957916,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/f06c2fe8-709f-4030-85dc-38a4bfd9e82d/v2.0/",
  "aud": "e1d2612f-c2bc-4599-8e7b-d874eaca1ee1",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1584957916,
  "auth_time": 1584957916,
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "given_name": "Emily",
  "family_name": "Smith",
  "balance": "202.75"
  ...
}

Práticas recomendadas e como solucionar problemas

Usar 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. 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 Azure AD B2C aguardará um máximo de 20 segundos para receber uma resposta. Se não receber nenhuma, ele fará mais uma tentativa (tentar novamente) 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. Para o Azure Functions, é recomendável usar no mínimo o plano Premium na produção.
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.

Importante

Seus pontos de extremidade devem estar em conformidade com os requisitos de segurança do Azure AD B2C. As versões e as criptografias de TLS mais antigas foram preterida. Para obter mais informações, consulte TLS do Azure AD B2C e requisitos do conjunto de criptografias.

Usar registro em log

Usar funções de nuvem sem servidor

Usar o 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. Além disso, o Azure AD B2C registra em log os metadados sobre as transações de API que ocorrem durante as autenticações de usuário por meio do fluxo de usuário. Para encontrar isso:

Acesse Azure AD B2C
Em Atividades, selecione Logs de auditoria.
Filtre a exibição de lista: Para Data, selecione o intervalo de tempo desejado e em Atividade, selecione Uma API foi chamada como parte de um fluxo de usuário.
Inspecione os logs individuais. Cada linha representa um conector de API que tenta ser chamado durante um fluxo de usuário. Se a chamada à API falhar e ocorrer uma nova tentativa, ela ainda será representada como uma única linha. O numberOfAttempts indica o número de vezes que sua API foi chamada. Esse valor pode ser 1 ou 2. Outras informações sobre a chamada à API estão detalhadas nos logs.

Próximas etapas

Comece agora com os nossos exemplos.
Proteger seu Conector de API

Para saber mais sobre como proteger suas APIs, confira os seguintes arquivos:

Enriquecer tokens com declarações de fontes externas usando conectores de API

Pré-requisitos

Criar um conector de API

Habilitar o conector de API em um fluxo de 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

Exemplo de resposta

Exemplo de uma resposta de continuação

Pré-requisitos

Preparar um ponto de extremidade da API REST

Definir declarações

Adicionar o perfil técnico da API RESTful

Configurar o perfil técnico da API RESTful

Adicionar uma etapa de orquestração

Incluir uma declaração no token

Teste a política personalizada

Práticas recomendadas e como solucionar problemas

Usar funções de nuvem sem servidor

Práticas recomendadas

Usar registro em log

Usar funções de nuvem sem servidor

Usar o registro em log

Próximas etapas

Recursos adicionais