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

Artigo
11/08/2023

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

O Azure Ative Directory B2C (Azure AD B2C) permite que os desenvolvedores de identidade integrem uma interação com uma API RESTful em seu fluxo de usuário usando 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 do 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 (visualização) para enriquecer 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 da API configurado no conector da API, que pode consultar informações sobre um usuário em serviços downstream, como serviços de nuvem, repositórios de usuários personalizados, sistemas de permissão personalizados, sistemas de identidade herdados e muito mais.

Nota

Esta funcionalidade está em pré-visualização pública.

Você pode criar um endpoint de API usando um de nossos exemplos.

Pré-requisitos

Crie um fluxo de usuários para que os usuários possam se inscrever e entrar em seu aplicativo.
Registe uma aplicação Web.

Conclua as etapas em Introdução às políticas personalizadas no Ative Directory B2C
Registe uma aplicação Web.

Um ponto de extremidade de API. Você pode criar um endpoint de API usando um de nossos exemplos.

Criar um conector de API

Para usar um conector de API, primeiro crie o conector de API e, em seguida, habilite-o em um fluxo de usuário.

Inicie sessão no portal do Azure.
Em Serviços do Azure, selecione Azure AD B2C.
Selecione Conectores de API e, em seguida, selecione Novo conector de API.
Forneça um nome para exibição para a chamada. Por exemplo, Enrich token de fonte externa.
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.

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.

Inicie sessão no portal do Azure.
Em Serviços do Azure, selecione Azure AD B2C.
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 o ponto de extremidade de API que você deseja invocar na etapa Antes de enviar o token (visualização) no fluxo de usuário:
Selecione Guardar.

Esta etapa só existe para os fluxos de usuário Inscrever-se e entrar (Recomendado), Inscrever-se (Recomendado) e Entrar (Recomendado).

Exemplo de solicitação enviada à 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 de forma semelhante às propriedades do usuário do Microsoft 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 do usuário e os atributos personalizados listados na experiência de atributos de usuário do Azure AD B2C>estão disponíveis para serem enviados na solicitação. Os atributos personalizados existem no formato extension_<extensions-app-id>_CustomAttribute 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 no Azure AD B2C. Além disso, essas declarações geralmente são enviadas em todas as solicitações para esta etapa:

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.
Etapa ('step') - A etapa ou ponto no fluxo de usuário para o qual o conector da API foi invocado. O valor para esta etapa é '
ID do Cliente ('client_id') - O appId valor do aplicativo no qual um usuário final está se autenticando em um fluxo de usuário. Isso não é do aplicativo de recurso em tokens de appId 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 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.

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

Resposta de continuação

Uma resposta de continuação indica que o fluxo de usuários deve continuar 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 de aplicativo do fluxo de usuário. O valor da declaração no token será o retornado pela API, não o 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 de usuário, com exceção de email.

Nota

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

Resposta 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	Necessá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	Eles 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. Eles podem ser retornados no token se selecionados como uma declaração de aplicativo.

Nesse cenário, enriquecemos os dados de token do usuário integrando-os a um fluxo de trabalho corporativo de linha de negócios. Durante a inscrição ou entrada com conta local ou federada, o Azure AD B2C invoca uma API REST para obter os dados de perfil estendido do usuário de uma fonte de dados remota. Neste exemplo, o Azure AD B2C envia o identificador exclusivo do usuário, o objectId. Em seguida, a API REST retorna o saldo da conta do usuário (um número aleatório). Use este exemplo como ponto de partida para integrar com seu próprio sistema de 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 estará validando dados na tela e retornando 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 de trabalho para inscrição e entrada com contas locais.
Saiba como integrar trocas de declarações da API REST em sua política personalizada do Azure AD B2C.

Preparar um ponto de extremidade da API REST

Para este passo a passo, você deve ter uma API REST que valide se o objectId do Azure AD B2C de um usuário está registrado em seu sistema back-end. Se estiver registrada, a API REST retornará o saldo da conta do usuário. Caso contrário, a API REST registra a nova conta no diretório e retorna o saldo 50.00inicial. O código JSON a seguir ilustra os dados que o Azure AD B2C enviará para seu 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 de função completo do Azure no GitHub.

Definir declarações

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

Abra o arquivo de extensões da sua política. Por exemplo, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
Procure 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

Um perfil técnico Restful fornece suporte para interface com seu próprio serviço RESTful. O Azure AD B2C envia dados para o serviço RESTful em uma coleção e recebe dados de volta em uma InputClaims OutputClaims coleção. Encontre o elemento ClaimsProviders em seu TrustFrameworkExtensions.xml arquivo 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, o será enviado para o userLanguage serviço REST como lang dentro da carga JSON útil. O valor da declaração contém o ID de userLanguage idioma do usuário atual. Para obter mais informações, consulte Solucionador de declarações.

Configurar o perfil técnico da API RESTful

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

ServiceUrl. Defina 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. Defina o tipo de autenticação que está sendo executada pelo provedor de declarações RESTful, como Basic ou ClientCertificate
AllowInsecureAuthInProduction. Em um ambiente de produção, certifique-se de definir esses metadados como false.

Consulte os metadados do perfil técnico RESTful para obter mais configurações. Os comentários acima AuthenticationType e AllowInsecureAuthInProduction especificar as alterações que você deve fazer quando você se move para um ambiente de produção. Para saber como proteger suas APIs RESTful para produção, consulte Proteger sua API RESTful.

Adicionar uma etapa de orquestração

Os percursos do utilizador especificam caminhos explícitos através dos quais uma política permite que uma aplicação de entidade confiadora obtenha as afirmações desejadas para um utilizador. Uma jornada do usuário é representada como uma sequência de orquestração que deve ser seguida para uma transação bem-sucedida. Você pode adicionar ou subtrair etapas de orquestração. Nesse caso, você adicionará uma nova etapa de orquestração que é usada para aumentar as informações fornecidas ao aplicativo após a inscrição ou entrada do usuário por meio da chamada da API REST.

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

Localize o <UserJourney Id="SignUpOrSignIn">, e adicione a seguinte etapa de orquestração 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 o Order para 8. Suas duas etapas finais de orquestração devem ter a seguinte aparência:

<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 as jornadas do usuário ProfileEdit e PasswordReset .

Incluir uma declaração no token

Para retornar a balance declaração de volta ao aplicativo de terceira parte confiável, adicione uma declaração de saída ao SocialAndLocalAccounts/SignUpOrSignIn.xml arquivo. Adicionar uma declaração de saída emitirá a declaração no token após uma jornada de usuário bem-sucedida 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 esta etapa para as jornadas de usuário ProfileEdit.xml e PasswordReset.xml . Salve os arquivos alterados: TrustFrameworkBase.xml e TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml e PasswordReset.xml.

Testar a política personalizada

Inicie sessão no portal do Azure.
Se você tiver acesso a vários locatários, selecione o ícone Configurações no menu superior para alternar para seu locatário do Azure AD B2C no menu Diretórios + assinaturas .
Escolha Todos os serviços no canto superior esquerdo do portal do Azure e, em seguida, procure e selecione Registos de aplicações.
Selecione Identity Experience Framework.
Selecione Carregar Política Personalizada e carregue os arquivos de política que você alterou: TrustFrameworkBase.xml e TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml e PasswordReset.xml.
Selecione a política de inscrição ou entrada que você carregou e clique no botão Executar agora .
Você deve ser capaz de se inscrever usando um endereço de e-mail ou uma conta do Facebook.
O token enviado de volta ao seu aplicativo inclui a balance reivindicação.

{
  "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

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. 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 Azure AD B2C aguardará 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 você 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" em produção. Para o Azure Functions, é recomendável usar no mínimo o plano Premium em 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. Versões e cifras TLS mais antigas foram preteridas. Para obter mais informações, consulte Azure AD B2C TLS e requisitos do pacote de codificação.

Utilizar o registo

Usando funções de nuvem sem servidor

Usando o registro em log

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. Além disso, o Azure AD B2C registra metadados sobre as transações de API que acontecem durante as autenticações de usuário por meio de um fluxo de usuário. Para encontrá-los:

Ir para Azure AD B2C
Em Atividades, selecione Logs de auditoria.
Filtrar o modo de exibição de lista: Em Data, selecione o intervalo de tempo desejado e, em Atividade, selecione Uma API foi chamada como parte de um fluxo de usuário.
Inspecione logs individuais. Cada linha representa um conector de API que tenta ser chamado durante um fluxo de usuário. Se uma chamada de 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. Este valor pode ser 1ou 2. Outras informações sobre a chamada de API são detalhadas nos logs.

Próximos passos

Comece com as nossas amostras.
Proteja seu conector de API

Para saber como proteger suas APIs, consulte os seguintes artigos:

Partilhar via

Enriqueça 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 à API nesta etapa

Tipos de resposta esperados da API da Web nesta etapa

Resposta de continuação

Resposta de exemplo

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

Testar a política personalizada

Práticas recomendadas e como solucionar problemas

Usando funções de nuvem sem servidor

Melhores práticas

Utilizar o registo

Usando funções de nuvem sem servidor

Usando o registro em log

Próximos passos

Comentários

Recursos adicionais