Controles de exibição

Artigo
01/11/2024

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 aparecem na página e são referenciados por um perfil técnico autodeclarado.

Pré-requisitos

Na seção de Metadados de um perfil técnico autodeclarado, o ContentDefinition referenciado precisa ter o DataUri definido como a versão de contrato de página 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>
  ...

Definir 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 o endereço de email primário e secundário.

Screenshot showing email verification display control

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.

Screenshot showing TOTP display controls

QrCodeControl

O elemento DisplayControl contém os seguintes elementos:

Elemento	Ocorrências	Descrição
`InputClaims`	0:1	InputClaims são usados para preencher previamente o valor das declarações a serem coletadas do usuário. Para saber mais, confira o elemento InputClaims.
`DisplayClaims`	0:1	DisplayClaims são usados para representar as declarações a serem coletadas do usuário. Para saber mais, confira o elemento DisplayClaim.
`OutputClaims`	0:1	OutputClaims são usados para representar as declarações a serem salvas temporariamente para este DisplayControl. Para saber mais, confira o elemento OutputClaims.
`Actions`	0:1	Actions 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 os elementos InputClaims para preencher previamente o valor das declarações a serem coletadas do usuário na página. Qualquer InputClaimsTransformations pode ser definido 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.

Semelhantes à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 o tipo de entrada do usuário com o Azure AD B2C, como TextBox ou DropdownSingleSelect. Se um valor de declaração de exibição for exigido por uma Action, defina o atributo Required como true para 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. Elas são salvas 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 surgirem 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 Actions de controle

Actions 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. Elas são usadas para validar algumas ou todas as declarações de exibição do controle de exibição. O perfil técnico de validação autoriza a entrada do usuário e pode retornar um erro ao usuário. Você pode usar ContinueOnError, ContinueOnSuccess e Preconditions na Action de controle de exibição semelhante à forma como 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 valor `SendCode` envia um código para o usuário. Essa ação pode conter dois perfis técnicos de validação: um para gerar o código e outro para enviá-lo. O valor `VerifyCode` 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 dos 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 precisam 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 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 deve ser atendida para o perfil técnico de validação para executar.

O elemento Precondition contém os seguintes atributos:

Atributo	Obrigatório	Descrição
`Type`	Sim	O tipo de verificação ou consulta ser executada para a pré-condição. Valores possíveis: `ClaimsExist` ou `ClaimEquals`. `ClaimsExist` especifica que as ações deverão ser executadas se as declarações especificadas existirem no conjunto de declarações atual do usuário. `ClaimEquals` especifica que as ações deverão 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 que são usados pela verificação. Se o tipo dessa verificação for `ClaimsExist`, este campo especifica um ClaimTypeReferenceId para consultar. Se o tipo dessa verificação for `ClaimEquals`, este campo especifica um ClaimTypeReferenceId para consultar. Especifica o valor a ser verificado em outro elemento de valor.
`Action`	1:1	A ação que deverá ser executada se a verificação de pré-condição dentro de uma etapa de orquestração for verdadeira. O valor da Action é 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 da SSPR do Microsoft Entra ID.

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

Referenciar 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, confira: