Adicionar um conector de API a um fluxo de usuário de inscrição

  • Artigo

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.

Como desenvolvedor ou administrador de TI, você pode usar conectores de API para integrar seus fluxos de inscrição de usuários com APIs REST de maneira a personalizar a experiência de inscrição e fazer integração com sistemas externos. Ao final deste passo a passo, você estará apto a criar um fluxo do usuário do Azure AD B2C que interage com serviços API REST para modificar as experiências de inscrição.

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

Nesse cenário, adicionaremos a capacidade para os usuários inserirem um número de fidelidade na página de inscrição Azure AD B2C. A API REST valida se a combinação de email e número de fidelidade é mapeada para um código promocional. Se a API REST encontrar um código promocional para esse usuário, ela será retornada para Azure AD B2C. Por fim, o código promocional será inserido nas declarações de token para que o aplicativo consuma.

Você também pode criar a interação como uma etapa de orquestração. Isso é adequado quando a API REST não for validar dados na tela e sempre retorna declarações. Para obter mais informações, consulte Passo a passo: Integrar as trocas de declarações da API REST no percurso do usuário do Azure AD B2C como uma etapa de orquestração.

Pré-requisitos

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 osConectores de API e depois Novo conector de API.

    Screenshot of basic configuration for an API connector

  4. Forneça um nome de exibição para a chamada. Por exemplo, Validar as informações do usuário.

  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.

    Screenshot of authentication configuration for an API connector

  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": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "11111111-0000-0000-0000-000000000000",
 "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",
 "step": "<step-name>",
 "client_id":"93fd07aa-333c-409d-955d-96008fd08dd9",
 "ui_locales":"en-US"
}

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:

  • 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. Os valores são:
    • PostFederationSignup – corresponde a "Após a federação com um provedor de identidade durante a inscrição"
    • PostAttributeCollection – corresponde a "Antes de criar o usuário"
    • PreTokenIssuance – corresponde a "Antes de enviar o token (versão prévia)". Saiba mais sobre esta 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. Este não é o aplicativo de recurso appId em tokens de acesso.
  • 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.

  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 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
    • Antes de enviar o token (versão prévia)

    Selecting an API connector for a step in the user flow

  5. Selecione Salvar.

Essas etapas existem apenas para Inscrever-se e fazer login (recomendado) e Inscrever-se (recomendado) , mas se aplicam apenas à parte da experiência de inscrição.

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 e o 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. Essa etapa não será invocada se um usuário estiver se registrando com uma conta local.

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

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "step": "PostFederationSignup",
 "client_id":"<guid>",
 "ui_locales":"en-US"
}

As declarações exatas enviadas para a API dependem das informações 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:

  • Preencherá 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.

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

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "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",
 "step": "PostAttributeCollection",
 "client_id":"93fd07aa-333c-409d-955d-96008fd08dd9",
 "ui_locales":"en-US"
}

As declarações que são enviadas para a API dependem das informações coletadas do usuário ou 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:

  • Substitui qualquer valor que já tenha sido fornecido por um usuário na página coleção de atributos.

Para gravar declarações no diretório na inscrição que não devem ser coletadas do usuário, você ainda deve selecionar as declarações em Atributos de usuário do fluxo do usuário, o que, por padrão, pede ao usuário valores, mas você pode usar JavaScript ou CSS personalizado para ocultar os campos de entrada de um usuário final.

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

Antes de enviar o token (versão prévia)

Importante

Os conectores de API usados nesta etapa estão em versão prévia. Para obter mais informações, consulte Termos de Produtos para Serviços Online.

Um conector de API nesta etapa é invocado quando um token está prestes a ser emitido durante entradas e inscrições. Um conector de API para esta etapa pode ser usado para enriquecer o token com valores de declaração de fontes externas.

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

POST <API-endpoint>
Content-type: application/json

{
 "clientId": "231c70e8-8424-48ac-9b5d-5623b9e4ccf3",
 "step": "PreTokenApplicationClaims",
 "ui_locales":"en-US",
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
}

As declarações que são enviadas para a API dependem das informações definidas para 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 do usuário, ela pode retornar estas respostas:

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

Confira um exemplo de uma resposta de continuação.

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.

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ório Descrição
version String Sim A versão da API.
ação String Sim O valor precisa ser Continue.
<builtInUserAttribute> <attribute-type> No Os valores retornados podem substituir os valores coletados de um usuário.
<extension_{extensions-app-id}_CustomAttribute> <attribute-type> No A declaração não precisa conter _<extensions-app-id>_ e é 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 a problem with your request. You are not able to sign up at this time. Please contact your system administrator",
}
Parâmetro Type Obrigatório Descrição
version String 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

Example of a blocking response

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ório Descrição
version String 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

Example of a validation-error response

Preparar um ponto de extremidade da API REST

Para esta explicação, você deve ter uma API REST que valida se um endereço de email está registrado em seu sistema de back-end com uma ID de fidelidade. Se registrado, a API REST deve retornar um código de promoção de registro, que o cliente pode usar para comprar bens dentro de seu aplicativo. Caso contrário, a API REST deverá retornar uma mensagem de erro HTTP 409: "A ID de fidelidade '{ID de fidelidade}' não está associada ao endereço de email '{email}'.".

O código JSON a seguir ilustra os dados que o Azure AD B2C enviará para o ponto de extremidade da API REST.

{
    "email": "User email address",
    "language": "Current UI language",
    "loyaltyId": "User loyalty ID"
}

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

{
    "promoCode": "24534"
}

Se a validação falhar, a API REST deverá retornar um HTTP 409 (Conflito) com o elemento JSON userMessage. O IEF espera a declaração userMessage retornada pela API REST. Essa declaração será apresentada como uma cadeia de caracteres para o usuário se a validação falhar.

{
    "version": "1.0.1",
    "status": 409,
    "userMessage": "LoyaltyId ID '1234' is not associated with 'david@contoso.com' email address."
}

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.

  1. Abra o arquivo de extensões da sua 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 seguintes declarações ao elemento ClaimsSchema.
<ClaimType Id="loyaltyId">
  <DisplayName>Your loyalty ID</DisplayName>
  <DataType>string</DataType>
  <UserInputType>TextBox</UserInputType>
</ClaimType>
<ClaimType Id="promoCode">
  <DisplayName>Your promo code</DisplayName>
  <DataType>string</DataType>
  <UserInputType>Paragraph</UserInputType>
</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 coleçãoInputClaims e recebe dados de volta em uma coleçãoOutputClaims. Localize o elementoClaimsProviders e adicione um novo provedor de declarações da seguinte maneira:

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-ValidateProfile">
      <DisplayName>Check loyaltyId 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/ValidateProfile?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="loyaltyId" />
        <InputClaim ClaimTypeReferenceId="email" />
        <InputClaim ClaimTypeReferenceId="userLanguage" PartnerClaimType="lang" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
      </InputClaims>
      <OutputClaims>
        <!-- Claims parsed from your REST API -->
        <OutputClaim ClaimTypeReferenceId="promoCode" />
      </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-ValidateProfile 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. Defina o tipo de autenticação que está sendo executada pelo provedor de declarações RESTful.
  • AllowInsecureAuthInProduction. Em um ambiente de produção, certifique-se de definir esses metadados para true

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.

Validar a entrada do usuário

Para obter o número de fidelidade do usuário durante a inscrição, você deve permitir que o usuário insira esses dados na tela. Adicione a declaração de saída do loyaltyId à página de inscrição adicionando-a ao elemento da seção de perfil técnico de inscrição existente OutputClaims. Especifique a lista completa de declarações de saída para controlar a ordem em que as declarações são apresentadas na tela.

Adicione a referência de perfil técnico de validação ao perfil técnico de inscrição, que chama REST-ValidateProfile. O novo perfil técnico de validação será adicionado à parte superior da coleção <ValidationTechnicalProfiles> definida na política de base. Esse comportamento significa que somente após a validação bem-sucedida, Azure AD B2C se move para criar a conta no diretório.

  1. Localize o elemento ClaimsProviders. Adicione um novo provedor de declarações da seguinte maneira:

    <ClaimsProvider>
  <DisplayName>Local Account</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="Verified.Email" Required="true"/>
        <OutputClaim ClaimTypeReferenceId="newPassword" Required="true"/>
        <OutputClaim ClaimTypeReferenceId="reenterPassword" Required="true"/>
        <OutputClaim ClaimTypeReferenceId="displayName"/>
        <OutputClaim ClaimTypeReferenceId="givenName"/>
        <OutputClaim ClaimTypeReferenceId="surName"/>
        <!-- Required to present the text box to collect the data from the user -->
        <OutputClaim ClaimTypeReferenceId="loyaltyId"/>
        <!-- Required to pass the promoCode returned from "REST-ValidateProfile" 
        to subsequent orchestration steps and token issuance-->
        <OutputClaim ClaimTypeReferenceId="promoCode" />
      </OutputClaims>
      <ValidationTechnicalProfiles>
        <ValidationTechnicalProfile ReferenceId="REST-ValidateProfile" />
      </ValidationTechnicalProfiles>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>
<ClaimsProvider>
  <DisplayName>Self Asserted</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="SelfAsserted-Social">
      <InputClaims>
        <InputClaim ClaimTypeReferenceId="email" />
      </InputClaims>
        <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" />
        <OutputClaim ClaimTypeReferenceId="displayName"/>
        <OutputClaim ClaimTypeReferenceId="givenName"/>
        <OutputClaim ClaimTypeReferenceId="surname"/>
        <!-- Required to present the text box to collect the data from the user -->
        <OutputClaim ClaimTypeReferenceId="loyaltyId"/>
        <!-- Required to pass the promoCode returned from "REST-ValidateProfile" 
        to subsequent orchestration steps and token issuance-->
        <OutputClaim ClaimTypeReferenceId="promoCode" />
      </OutputClaims>
      <ValidationTechnicalProfiles>
        <ValidationTechnicalProfile ReferenceId="REST-ValidateProfile"/>
      </ValidationTechnicalProfiles>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

Incluir uma declaração no token

Para retornar a declaração do código de promoção 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 promoCode 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="promoCode" DefaultValue="" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

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 ID 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 Estrutura de Experiência de Identidade.
  5. Selecione Carregar Política Personalizada e carregue o arquivo de política que você alterou, TrustFrameworkExtensions.xml e SignUpOrSignin.xml.
  6. Selecione a política de inscrição ou de entrada carregada e clique no botão Executar agora.
  7. Você deverá conseguir se inscrever usando um endereço de email.
  8. Clique no link Inscrever-se agora.
  9. Na sua ID de fidelidade, digite 1234 e clique em Continuar. Neste ponto, você deve obter uma mensagem de erro de validação.
  10. Altere para outro valor e clique em Continuar.
  11. O token enviado de volta ao seu aplicativo inclui a declaração promoCode.
{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584295703,
  "nbf": 1584292103,
  "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": 1584292103,
  "auth_time": 1584292103,
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "given_name": "Emily",
  "family_name": "Smith",
  "promoCode": "84362"
  ...
}

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

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:

  1. Acesse Azure AD B2C.
  2. Em Atividades, selecione Logs de auditoria.
  3. 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.
  4. 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.

Example of an API connector transaction during user authentication

Usar funções de nuvem sem servidor

Funções de nuvem sem servidor, como gatilhos http no Azure Functions, fornecem uma maneira simples, altamente disponível e de alto desempenho para criar pontos de extremidade de API para usar como conectores de API.

Práticas recomendadas

Verifique se:

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

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