Apresentar controlos

Artigo
02/24/2024

Nota

No Azure Ative Directory B2C, as políticas personalizadas são projetadas principalmente para lidar com cenários complexos. Para a maioria dos cenários, recomendamos que você use fluxos de usuário internos. Se você não tiver feito isso, saiba mais sobre o pacote inicial de políticas personalizadas em Introdução às políticas personalizadas no Ative Directory B2C.

Um controle de exibição é um elemento da interface do usuário que tem funcionalidade especial e interage com o serviço back-end do Azure Ative Directory B2C (Azure AD 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 para a página de contrato 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	Necessário	Descrição
`Id`	Sim	Um identificador usado para o controle de exibição. Pode ser referenciado.
`UserInterfaceControlType`	Sim	O tipo do controle de exibição. Atualmente, há suporte para VerificationControl, controles TOTP e controles CAPTCHA.

Controlo de verificação

O controle de exibição de verificação verifica declarações, por exemplo, um endereço de e-mail 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 e-mail principal e secundário.

Screenshot showing email verification display control

Controlos 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	Description
`InputClaims`	0:1	InputClaims são usados para preencher previamente o valor das declarações a serem coletadas do usuário. Para obter mais informações, consulte InputClaims element.
`DisplayClaims`	0:1	DisplayClaims são usados para representar reivindicações a serem coletadas do usuário. Para obter mais informações, consulte 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 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 acontecem 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 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 e-mail 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 suportado pelo 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 como true para forçar o usuário a fornecer um valor para essa declaração de exibição específica.

Certas declarações de exibição são necessárias para certos 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 borbulhar 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 para o usuário. Você pode usar ContinueOnError, ContinueOnSuccess e Preconditions na ação de controle de exibição semelhante à maneira como eles são usados na validação de perfis técnicos em um perfil técnico autodeclarado.

Ações

O elemento Actions contém o seguinte elemento:

Elemento	Ocorrências	Description
`Action`	1:n	Lista de ações a serem executadas.

Ação

O elemento Action contém o seguinte atributo:

Atributo	Necessá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. Esta 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	Description
`ValidationClaimsExchange`	1:1	Os identificadores de perfis técnicos que são 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	Description
`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	Necessá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	Description
`Preconditions`	0:1	Uma lista de pré-condições que devem ser satisfeitas para que o perfil técnico de validação seja executado.

O elemento Precondition contém os seguintes atributos:

Atributo	Necessá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	Description
`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 de verificação for `ClaimEquals`, este campo especifica um ClaimTypeReferenceId para consultar. Especifique o valor a ser verificado em outro elemento de valor.
`Action`	1:1	A ação que deve ser tomada se a verificação de pré-condição dentro de 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 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 por e-mail 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>

Fazendo referência a 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óximos passos

Para obter exemplos do uso do controle de exibição, consulte: