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

  • Artigo

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.

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

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

Nesse cenário, adicionaremos a capacidade de os usuários inserirem um número de fidelidade na página de inscrição do Azure AD B2C. A API REST valida se a combinação de e-mail e número de fidelidade está mapeada para um código promocional. Se a API REST encontrar um código promocional para esse usuário, ele será retornado ao Azure AD B2C. Finalmente, o código promocional será inserido nas reivindicações de token para o aplicativo consumir.

Você também pode projetar a interação como uma etapa de orquestração. Isso é adequado quando a API REST não valida dados na tela e sempre retorna declarações. Para obter mais informações, consulte Passo a passo: integrar trocas de declarações da API REST em sua jornada 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, primeiro crie o conector de API e, em seguida, habilite-o em um fluxo de usuário.

  1. Inicie sessão no portal do Azure.

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

  3. Selecione Conectores de API e, em seguida, selecione Novo conector de API.

    Screenshot of basic configuration for an API connector

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

  5. Forneça a URL do ponto de extremidade para a chamada de API.

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

    Screenshot of authentication configuration for an API connector

  7. Selecione Guardar.

A solicitação enviada à sua 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 de forma semelhante às propriedades do usuário do Microsoft Graph .

Exemplo de pedido

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

  • 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. Os valores incluem:
    • PostFederationSignup - corresponde a "Depois de federar com um provedor de identidade durante a inscrição"
    • PostAttributeCollection - corresponde a "Antes de criar o utilizador"
    • PreTokenIssuance - corresponde a "Antes de enviar o token (pré-visualização)". Saiba mais sobre 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.
  • Endereço de e-mail ('email') ou identidades ('identidades') - 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 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.

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. Inicie sessão no portal do Azure.

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

  3. Selecione Fluxos de usuário e, em seguida, selecione o fluxo de usuário ao qual você deseja adicionar o conector de API.

  4. Selecione conectores de API e, em seguida, selecione os pontos de extremidade de API que você deseja invocar nas seguintes etapas no fluxo de usuário:

    • Depois de federar com um provedor de identidade durante a inscrição
    • Antes de criar o usuário
    • Antes de enviar o token (pré-visualização)

    Selecting an API connector for a step in the user flow

  5. Selecione Guardar.

Estes passos só existem para Inscrever-se e iniciar sessão (Recomendado) e Inscrever-se (Recomendado), mas aplicam-se apenas à parte de inscrição da experiência.

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

Um conector de API nesta etapa do processo de inscrição é invocado imediatamente após o usuário se autenticar com um provedor de identidade (como Google, Facebook e Microsoft Entra ID). Esta etapa precede a página de coleta de atributos, que é o formulário apresentado ao usuário para coletar atributos de usuário. Esta etapa não é invocada se um usuário estiver se registrando com uma conta local.

Exemplo de solicitação enviada à 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. 'e-mail' é sempre enviado.

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 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 continuar para a próxima etapa: a página de coleta de atributos.

Em uma resposta de continuação, a API pode retornar declarações. Se uma declaração for retornada pela API, ela fará o seguinte:

  • Pré-preenche o campo de entrada na página de coleção de atributos.

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

Resposta de bloqueio

Uma resposta de bloqueio sai do fluxo do usuário. Ele pode ser emitido propositalmente pela API para interromper a continuação do fluxo do usuário, exibindo uma página de bloqueio para o usuário. A página de bloqueio exibe o userMessage fornecido pela API.

Veja um exemplo de uma resposta de bloqueio.

Antes de criar o usuário

Um conector de API nesta etapa do processo de inscrição é invocado após a página de coleta de atributos, se uma estiver incluída. Esta etapa é sempre invocada antes da criação de uma conta de usuário.

Exemplo de solicitação enviada à 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 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 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 de usuário deve continuar 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, ela fará o seguinte:

  • Substitui qualquer valor que já tenha sido fornecido por um usuário na página de 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 de usuário, que por padrão solicitará valores ao usuário, mas você pode usar JavaScript ou CSS personalizados para ocultar os campos de entrada de um usuário final.

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

Resposta de bloqueio

Uma resposta de bloqueio sai do fluxo do usuário. Ele pode ser emitido propositalmente pela API para interromper a continuação do fluxo do usuário, exibindo uma página de bloqueio para o usuário. A página de bloqueio exibe o userMessage fornecido pela API.

Veja 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 coleta de atributos e um userMessage é exibido para o usuário. O usuário pode então editar e reenviar o formulário. Este tipo de resposta pode ser usado para validação de entrada.

Veja um exemplo de uma resposta de erro de validação.

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

Importante

Os conectores de API usados nesta etapa estão em visualização. Para obter mais informações sobre visualizações, consulte Termos do produto 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 à 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 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 estas respostas:

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

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

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.

Exemplos de respostas

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 Os valores retornados podem substituir os valores coletados de um usuário.
<extension_{extensions-app-id}_CustomAttribute> <tipo de atributo> Não A reivindicação não precisa conter _<extensions-app-id>_, é 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 Necessário Description
versão Cadeia (de carateres) Sim A versão da sua API.
action Cadeia (de carateres) Sim O valor deve ser ShowBlockPage
userMensagem Cadeia (de carateres) Sim A mensagem a apresentar ao utilizador.

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 Necessário Description
versão Cadeia (de carateres) Sim A versão da sua API.
action Cadeia (de carateres) Sim O valor deve ser ValidationError.
estado Inteiro / String Sim Deve ser value 400, ou "400" para uma resposta ValidationError.
userMensagem Cadeia (de carateres) Sim A mensagem a apresentar ao utilizador.

Nota

O código de status HTTP deve ser "400", além do valor "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 este passo a passo, você deve ter uma API REST que valide se um endereço de e-mail está registrado em seu sistema back-end com um ID de fidelidade. Se estiver registada, a API REST deve devolver um código promocional de registo, que o cliente pode utilizar para comprar produtos dentro da sua aplicação. Caso contrário, a API REST deve retornar uma mensagem de erro HTTP 409: "ID de fidelidade '{ID de fidelidade}' não está associado ao endereço de e-mail '{email}'.".

O código JSON a seguir ilustra os dados que o Azure AD B2C enviará para seu 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 (Conflict), com o userMessage elemento JSON. O IEF espera a declaração de que a userMessage API REST retorna. 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 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 .

  1. Abra o arquivo de extensões da sua política. Por exemplo, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
  2. Procure 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 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 InputClaimsOutputClaims coleção. Encontre o elemento ClaimsProviders 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, 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-ValidateProfile 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.
  • AllowInsecureAuthInProduction. Em um ambiente de produção, certifique-se de definir esses metadados como true

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 Secure RESTful API.

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 loyaltyId à página de inscrição adicionando-a ao elemento da OutputClaims seção de perfil técnico de inscrição existente. Especifique toda a lista de declarações de saída para controlar a ordem em que as declarações são apresentadas na tela.

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

  1. Encontre 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 de código promocional de volta ao aplicativo de terceira parte confiável, adicione uma declaração de saída ao SocialAndLocalAccounts/SignUpOrSignIn.xml arquivo. A declaração de saída permitirá que a declaração seja adicionada ao 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 a promoCode declaração como 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>

Testar a política personalizada

  1. Inicie sessão 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 seu 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, em seguida, procure e selecione Registos de aplicações.
  4. Selecione Identity Experience Framework.
  5. Selecione Carregar Política Personalizada e carregue os arquivos de política que você alterou: TrustFrameworkExtensions.xml e SignUpOrSignin.xml.
  6. Selecione a política de inscrição ou entrada que você carregou e clique no botão Executar agora .
  7. Você deve ser capaz de se inscrever usando um endereço de e-mail.
  8. Clique no link Inscreva-se agora .
  9. No Seu ID de fidelidade, digite 1234 e clique em Continuar. Neste ponto, você deve receber uma mensagem de erro de validação.
  10. Mude para outro valor e clique em Continuar.
  11. O token enviado de volta ao seu aplicativo inclui a promoCode reivindicação.
{
  "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

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. Você pode usar a função de nuvem sem servidor para, por exemplo, executar lógica de validação e limitar inscrições a domínios de e-mail específicos. 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 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" na 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

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:

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

Example of an API connector transaction during user authentication

Usando funções de nuvem sem servidor

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

Melhores práticas

Certifique-se de que:

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

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.

Próximos passos