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

Você pode usar conectores de API aplicados à etapa Antes de enviar o token (versão prévia) 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 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.

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

Pré-requisitos

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

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.

1. Entre no portal do Azure.

2. Em Serviços do Azure, selecione Azure AD B2C.

3. Selecione conectores de API e selecione Novo conector de API.

   

4. Forneça um nome de exibição para a chamada. Por exemplo, Enriquecer token de uma fonte externa.

5. Forneça o endpoint URL 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. Clique em 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.

1. Entre no portal do Azure.

2. Em Serviços do Azure, selecione Azure AD B2C.

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 selecione o ponto de extremidade da API que você deseja invocar na etapa Antes de enviar o token (versão prévia) no fluxo do usuário:

   

5. Clique em Salvar.

Esta etapa só existe para Inscrição e entrada (Recomendado), Inscrição (Recomendado), e Entrada (Recomendado) nos fluxos de usuário.

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 logins e registros. 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": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
 "step": "PreTokenIssuance",
 "ui_locales":"en-US"
}

As declarações enviadas à 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. 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 normalmente são enviadas em todas as solicitações para esta etapa:

• Localidades da interface do usuário ('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 ('etapa') – a etapa ou o ponto no fluxo do usuário para o qual o conector de API foi invocado. O valor desta etapa é '
• ID do cliente ('client_id') – o appId valor do aplicativo para o qual um usuário final está se autenticando em um fluxo de usuário. Isso não é o appId do aplicativo de recurso nos tokens de acesso.
• objectId - O identificador do usuário. Você pode usá-lo para consultar serviços downstream para obter informações sobre o usuário.

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 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ário 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 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 de usuário , com exceção de email.

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
}

Nesse cenário, enriquecemos os dados de token do usuário ao integrá-los em um fluxo de trabalho corporativo de linha de negócios. Durante a inscrição ou entrada com uma conta local ou federada, o Azure AD B2C invoca uma API REST para obter os dados de perfil estendidos 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 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 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 funcional para registrar-se e fazer login com contas locais.
• Saiba como integrar as trocas de declarações da API REST em sua política personalizada do Azure AD B2C.

Preparar um endpoint da API REST

Para este passo a passo, você deve ter uma API REST que valide se a objectId do Azure AD B2C de um usuário está registrada em seu sistema de back-end. Se registrado, a API REST retornará o saldo da conta de usuário. Caso contrário, a API REST registrará a nova conta no diretório e retornará o saldo 50.00inicial. O código JSON a seguir ilustra os dados que o Azure AD B2C enviará ao 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 uma execução de política do Azure AD B2C. Você pode declarar declarações na seção de esquema de declarações .

1. Abra o arquivo de extensões da política. Por exemplo, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
2. Pesquise o elemento BuildingBlocks . Se o elemento não existir, adicione-o.
3. Localize o elemento ClaimsSchema . Se o elemento não existir, adicione-o.
4. Adicione as declarações a seguir 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 a interface com seu próprio serviço RESTful. O Azure AD B2C envia dados para o serviço RESTful em uma InputClaims coleção e recebe dados de volta em uma OutputClaims coleção. Localize 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, userLanguage será enviado para o serviço REST como lang no conteúdo do JSON. O valor da userLanguage declaração contém a ID do idioma do usuário atual. Para obter mais informações, consulte resolvedor de declarações.

Configurar o perfil técnico da API RESTful

Depois de implantar sua API REST, defina os metadados do REST-GetProfile 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 ao provedor de declarações RESTful.
• Tipo de autenticação. Definir 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, defina esses metadados como false.

Consulte os metadados de perfil técnico RESTful para obter mais configurações. Os comentários acima AuthenticationType e AllowInsecureAuthInProduction especificam as alterações que você deve fazer ao migrar 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

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. 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 à API REST.

1. Abra o arquivo base da política. Por exemplo, SocialAndLocalAccounts/TrustFrameworkBase.xml.
2. Pesquise o <UserJourneys> elemento. Copie todo o elemento e exclua-o.
3. Abra o arquivo de extensões da política. Por exemplo, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
4. Cole o <UserJourneys> no arquivo de extensões, após o fechamento do elemento <ClaimsProviders>.
5. 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>
   

6. Refatorar a última etapa de orquestração alterando o Order para 8. As duas etapas finais de orquestração devem ser semelhantes às seguintes:

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

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

Incluir uma reivindicação dentro do 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.xmle TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xmle PasswordReset.xml.

Teste a política personalizada

1. Entre no portal do Azure.
2. Se você tiver acesso a vários locatários, selecione o ícone Configurações no menu superior para alternar para o locatário do Microsoft Entra no menu Diretórios + assinaturas.
3. Escolha Todos os serviços no canto superior esquerdo do portal do Azure e pesquise e selecione registros de aplicativo.
4. Selecione a Estrutura de Experiência de Identidade.
5. Selecione Carregar Política Personalizada e carregue os arquivos de política que você alterou: TrustFrameworkBase.xmle TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xmle PasswordReset.xml.
6. Selecione a política de cadastro ou login que você carregou e clique no botão Executar agora.
7. Você deve ser capaz de se inscrever usando um endereço de email ou uma conta do Facebook.
8. 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/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/",
  "aud": "11112222-bbbb-3333-cccc-4444dddd5555",
  "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 os gatilhos HTTP no Azure Functions, oferecem uma maneira de criar endpoints de API para serem usados 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

Certifique-se de que:

• A sua 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á no máximo 20 segundos para receber uma resposta. Se não receber nenhuma, ele fará mais uma tentativa (tentar novamente) de chamar sua API.
  • Se você 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" em produção. Para o Azure Functions, é recomendável que você use 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.

Usar o log

Usar funções de nuvem sem servidor

As funções sem servidor, como os gatilhos HTTP no Azure Functions, oferecem uma maneira de criar endpoints de API para serem usados 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.

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, utilize níveis mais detalhados de registro de log (como "trace" ou "debug") no desenvolvimento.
• Monitore a API para tempos de resposta longos.

Além disso, o Azure AD B2C registra metadados sobre as transações de API que ocorrem durante autenticações de usuário por meio de um fluxo de usuário. Para encontrar essas informações:

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

• Comece com nossas amostras.
• Proteger seu Conector de API

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

• Passo a passo: integrar as trocas de declarações da API REST em seu percurso de usuário do Azure AD B2C como uma etapa de orquestração
• Proteger sua API RESTful
• Referência: perfil técnico RESTful