Controles de exibição

Importante

A partir de 1º de maio de 2025, o Azure AD B2C não estará mais disponível para compra para novos clientes. Saiba mais em nossas perguntas frequentes.

Observação

No Azure Active Directory B2C, as políticas personalizadas são projetadas principalmente para tratar de cenários complexos. Para a maioria dos cenários, recomendamos que você use fluxos de usuários predefinidos. Se você ainda não fez isso, saiba mais sobre o pacote de início de política personalizado em Introdução às políticas personalizadas no Active Directory B2C.

Um controle de exibição é um elemento de interface do usuário que tem funcionalidade especial e interage com o serviço de back-end do Azure AD B2C (Azure Active Directory B2C). Ele permite que o usuário execute ações na página que invocam um perfil técnico de validação no back-end. Os controles de exibição são exibidos na página e são referenciados por um perfil técnico autodeclarado.

Pré-requisitos

Na seção Metadados de um perfil técnico autodeclarado, o ContentDefinition referenciado precisa ter DataUri definido como contrato de página versão 2.1.9 ou superior. Por exemplo:

<ContentDefinition Id="api.selfasserted">
  <LoadUri>~/tenant/default/selfAsserted.cshtml</LoadUri>
  <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
  <DataUri>urn:com:microsoft:aad:b2c:elements:selfasserted:2.1.9</DataUri>
  ...

Definindo controles de exibição

O elemento DisplayControl contém os seguintes atributos:

Atributo	Obrigatório	Descrição
Id	Sim	Um identificador usado para o controle de exibição. Ele pode ser referenciado.
UserInterfaceControlType	Sim	O tipo do controle de exibição. Atualmente, há suporte para controles VerificationControl, TOTP e CAPTCHA.

Controle de verificação

O controle de exibição de verificação verifica as declarações, por exemplo, um endereço de email ou número de telefone, com um código de verificação enviado ao usuário. A imagem a seguir ilustra uma página de inscrição autodeclarada com dois controles de exibição que validam um endereço de email primário e secundário.

Controles TOTP

Os controles de exibição TOTP são um conjunto de controles de exibição que fornecem autenticação multifator TOTP com o aplicativo Microsoft Authenticator. A imagem a seguir ilustra uma página de registro TOTP com os três controles de exibição.

Controle de QrCodeControl

O elemento DisplayControl contém os seguintes elementos:

Elemento	Ocorrências	Descrição
InputClaims	0:1	InputClaims são usados para pré-preencher o valor das declarações a serem coletadas do usuário. Para obter mais informações, consulte o elemento InputClaims .
DisplayClaims	0:1	DisplayClaims são usados para representar declarações a serem coletadas do usuário. Para obter mais informações, consulte o elemento DisplayClaim .
OutputClaims	0:1	OutputClaims são usados para representar declarações a serem salvas temporariamente para este DisplayControl. Para obter mais informações, consulte o elemento OutputClaims .
Actions	0:1	As ações são usadas para listar os perfis técnicos de validação a serem invocados para ações do usuário que ocorrem no front-end.

Declarações de entrada

Em um controle de exibição, você pode usar elementos InputClaims para pré-preencher o valor das declarações a serem coletadas do usuário na página. Qualquer InputClaimsTransformations pode ser definida no perfil técnico autodeclarado, que faz referência a esse controle de exibição.

O exemplo a seguir preenche previamente o endereço de email a ser verificado com o endereço já presente.

<DisplayControl Id="emailControl" UserInterfaceControlType="VerificationControl">
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="emailAddress" />
  </InputClaims>
  ...

Exibir declarações

Cada tipo de controle de exibição requer um conjunto diferente de declarações de exibição, declarações de saída e ações a serem executadas.

Semelhante às declarações de exibição definidas em um perfil técnico autodeclarado, as declarações de exibição representam as declarações a serem coletadas do usuário dentro do controle de exibição. O elemento ClaimType referenciado precisa especificar o elemento UserInputType para um tipo de entrada de usuário compatível com o Azure AD B2C, como TextBox ou DropdownSingleSelect. Se um valor de declaração de exibição for exigido por uma Ação, defina o atributo Obrigatório para true forçar o usuário a fornecer um valor para essa declaração de exibição específica.

Determinadas declarações de exibição são necessárias para determinados tipos de controle de exibição. Por exemplo, VerificationCode é necessário para o controle de exibição do tipo VerificationControl. Use o atributo ControlClaimType para especificar qual DisplayClaim é designado para essa declaração necessária. Por exemplo:

<DisplayClaim ClaimTypeReferenceId="otpCode" ControlClaimType="VerificationCode" Required="true" />

Declarações de saída

As declarações de saída de um controle de exibição não são enviadas para a próxima etapa de orquestração. Eles são salvos temporariamente apenas para a sessão de controle de exibição atual. Essas declarações temporárias podem ser compartilhadas entre as diferentes ações do mesmo controle de exibição.

Para aumentar as declarações de saída para a próxima etapa de orquestração, use o OutputClaims do perfil técnico autodeclarado real, que faz referência a esse controle de exibição.

Exibir ações de controle

As Ações de um controle de exibição são procedimentos que ocorrem no back-end do Azure AD B2C quando um usuário executa uma determinada ação no lado do cliente (o navegador). Por exemplo, as validações a serem executadas quando o usuário seleciona um botão na página.

Uma ação define uma lista de perfis técnicos de validação. Eles são usados para validar algumas ou todas as declarações de exibição do controle de exibição. O perfil técnico de validação valida a entrada do usuário e pode retornar um erro ao usuário. Você pode usar ContinueOnError, ContinueOnSuccess e Preconditions na ação de controle de exibição semelhante à maneira como eles são usados em perfis técnicos de validação em um perfil técnico autodeclarado.

Ações

O elemento Actions contém o seguinte elemento:

Elemento	Ocorrências	Descrição
Action	1:n	Lista de ações a serem executadas.

Ação

O elemento Action contém o seguinte atributo:

Atributo	Obrigatório	Descrição
Id	Sim	O tipo de operação. Valores possíveis: SendCode ou VerifyCode. O SendCode valor envia um código para o usuário. Essa ação pode conter dois perfis técnicos de validação: um para gerar um código e outro para enviá-lo. O VerifyCode valor verifica o código que o usuário digitou na caixa de texto de entrada.

O elemento Action contém o seguinte elemento:

Elemento	Ocorrências	Descrição
ValidationClaimsExchange	1:1	Os identificadores de perfis técnicos usados para validar algumas ou todas as declarações de exibição do perfil técnico de referência. Todas as declarações de entrada do perfil técnico referenciado devem aparecer nas declarações de exibição do perfil técnico de referência.

ValidationClaimsExchange

O elemento ValidationClaimsExchange contém o seguinte elemento:

Elemento	Ocorrências	Descrição
ValidationClaimsExchangeTechnicalProfile	1:n	Um perfil técnico a ser usado para validar algumas ou todas as declarações de exibição do perfil técnico de referência.

O elemento ValidationClaimsExchangeTechnicalProfile contém o seguinte atributo:

Atributo	Obrigatório	Descrição
TechnicalProfileReferenceId	Sim	Um identificador de um perfil técnico já definido na política ou na política pai.

O elemento ValidationClaimsExchangeTechnicalProfile contém o seguinte elemento:

Elemento	Ocorrências	Descrição
Preconditions	0:1	Uma lista de pré-condições que devem ser atendidas para que o perfil técnico de validação seja executado.

O elemento Precondition contém os seguintes atributos:

Atributo	Obrigatório	Descrição
Type	Sim	O tipo de verificação ou consulta a ser executada para a pré-condição. Valores possíveis: ClaimsExist ou ClaimEquals. ClaimsExist especifica que as ações devem ser executadas se as declarações especificadas existirem no conjunto de declarações atual do usuário. ClaimEquals especifica que as ações devem ser executadas se a declaração especificada existir e seu valor for igual ao valor especificado.
ExecuteActionsIf	Sim	Indica se as ações na pré-condição devem ser executadas se o teste for verdadeiro ou falso.

O elemento Precondition contém os seguintes elementos:

Elemento	Ocorrências	Descrição
Value	1:n	Os dados usados pela verificação. Se o tipo dessa verificação for ClaimsExist, esse campo especificará um ClaimTypeReferenceId para consultar. Se o tipo de verificação for ClaimEquals, esse campo especificará um ClaimTypeReferenceId para consultar. Especifique o valor a ser verificado em outro elemento de valor.
Action	1:1	A ação que deve ser executada se a verificação de pré-condição em uma etapa de orquestração for verdadeira. O valor da Ação é definido como SkipThisValidationTechnicalProfile, que especifica que o perfil técnico de validação associado não deve ser executado.

O exemplo a seguir envia e verifica o endereço de email usando o perfil técnico do Microsoft Entra ID SSPR.

<DisplayControl Id="emailVerificationControl" UserInterfaceControlType="VerificationControl">
  <InputClaims></InputClaims>
  <DisplayClaims>
    <DisplayClaim ClaimTypeReferenceId="email" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="verificationCode" ControlClaimType="VerificationCode" Required="true" />
  </DisplayClaims>
  <OutputClaims></OutputClaims>
  <Actions>
    <Action Id="SendCode">
      <ValidationClaimsExchange>
        <ValidationClaimsExchangeTechnicalProfile TechnicalProfileReferenceId="AadSspr-SendCode" />
      </ValidationClaimsExchange>
    </Action>
    <Action Id="VerifyCode">
      <ValidationClaimsExchange>
        <ValidationClaimsExchangeTechnicalProfile TechnicalProfileReferenceId="AadSspr-VerifyCode" />
      </ValidationClaimsExchange>
    </Action>
  </Actions>
</DisplayControl>

O exemplo a seguir envia um código por email ou SMS com base na seleção do usuário da declaração mfaType com pré-condições.

<Action Id="SendCode">
  <ValidationClaimsExchange>
    <ValidationClaimsExchangeTechnicalProfile TechnicalProfileReferenceId="AzureMfa-SendSms">
      <Preconditions>
        <Precondition Type="ClaimEquals" ExecuteActionsIf="true">
          <Value>mfaType</Value>
          <Value>email</Value>
          <Action>SkipThisValidationTechnicalProfile</Action>
        </Precondition>
      </Preconditions>
    </ValidationClaimsExchangeTechnicalProfile>
    <ValidationClaimsExchangeTechnicalProfile TechnicalProfileReferenceId="AadSspr-SendEmail">
      <Preconditions>
        <Precondition Type="ClaimEquals" ExecuteActionsIf="true">
          <Value>mfaType</Value>
          <Value>phone</Value>
          <Action>SkipThisValidationTechnicalProfile</Action>
        </Precondition>
      </Preconditions>
    </ValidationClaimsExchangeTechnicalProfile>
  </ValidationClaimsExchange>
</Action>

Referenciando controles de exibição

Os controles de exibição são referenciados nas declarações de exibição do perfil técnico autodeclarado.

Por exemplo:

<TechnicalProfile Id="SelfAsserted-ProfileUpdate">
  ...
  <DisplayClaims>
    <DisplayClaim DisplayControlReferenceId="emailVerificationControl" />
    <DisplayClaim DisplayControlReferenceId="PhoneVerificationControl" />
    <DisplayClaim ClaimTypeReferenceId="displayName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="givenName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="surName" Required="true" />

Próximas etapas

Para obter exemplos de como usar o controle de exibição, consulte:

• Verificação de email personalizada com o Mailjet
• Verificação de email personalizada com SendGrid