Controles de exibição

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.

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.

Exemplo de controle de exibição renderizado

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.0.0 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.0.0</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 VerificationControl

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.
Ações 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
Ação 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
Pré-condições 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
Valor 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.
Ação 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 Azure AD.

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