Controlli di visualizzazione

Articolo
01/11/2024

Nota

In Azure Active Directory B2C i criteri personalizzati sono stati progettati principalmente per far fronte a scenari complessi. Per la maggior parte degli scenari, è consigliabile usare i flussi utente predefiniti. In caso contrario, vedere Introduzione ai criteri personalizzati in Active Directory B2C.

Un controllo display è un elemento dell'interfaccia utente con funzionalità speciali e interagisce con il servizio back-end di Azure Active Directory B2C (Azure AD B2C). Consente all'utente di eseguire azioni nella pagina che richiamano un profilo tecnico di convalida al back-end. I controlli di visualizzazione vengono visualizzati nella pagina e fanno riferimento a un profilo tecnico autocertificato.

Prerequisiti

Nella sezione Metadati di un profilo tecnico autocertivo, contentDefinition di riferimento deve avere DataUri impostato la versione del contratto di pagina 2.1.9 o successiva. Ad esempio:

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

Definizione dei controlli di visualizzazione

L'elemento DisplayControl contiene gli attributi seguenti:

Attributo	Richiesto	Descrizione
`Id`	Sì	Identificatore utilizzato per il controllo di visualizzazione. Può essere fatto riferimento.
`UserInterfaceControlType`	Sì	Tipo del controllo di visualizzazione. Attualmente supportato è VerificationControl, controlli TOTP e controlli CAPTCHA.

Controllo di verifica

Il controllo di visualizzazione della verifica verifica verifica le attestazioni, ad esempio un indirizzo di posta elettronica o un numero di telefono, con un codice di verifica inviato all'utente. L'immagine seguente illustra una pagina di iscrizione autocertificata con due controlli di visualizzazione che convalidano un indirizzo di posta elettronica primario e secondario.

Screenshot showing email verification display control

Controlli TOTP

I controlli di visualizzazione TOTP sono un set di controlli di visualizzazione che forniscono l'autenticazione a più fattori TOTP con l'app Microsoft Authenticator. L'immagine seguente illustra una pagina di registrazione TOTP con i tre controlli di visualizzazione.

Screenshot showing TOTP display controls

QrCodeControl

L'elemento DisplayControl contiene gli elementi seguenti:

Elemento	Occorrenze	Descrizione
`InputClaims`	0:1	InputClaims viene usato per prepopopolare il valore delle attestazioni da raccogliere dall'utente. Per altre informazioni, vedere Elemento InputClaims .
`DisplayClaims`	0:1	DisplayClaims viene usato per rappresentare le attestazioni da raccogliere dall'utente. Per altre informazioni, vedere Elemento DisplayClaim .
`OutputClaims`	0:1	OutputClaims viene usato per rappresentare le attestazioni da salvare temporaneamente per questo DisplayControl. Per altre informazioni, vedere Elemento OutputClaims .
`Actions`	0:1	Le azioni vengono usate per elencare i profili tecnici di convalida da richiamare per le azioni utente eseguite nel front-end.

Attestazioni di input

In un controllo di visualizzazione è possibile usare gli elementi InputClaims per prepopopolare il valore delle attestazioni da raccogliere dall'utente nella pagina. Qualsiasi inputClaimsTransformations può essere definito nel profilo tecnico autocertificato, che fa riferimento a questo controllo di visualizzazione.

Nell'esempio seguente viene prepopolato l'indirizzo di posta elettronica da verificare con l'indirizzo già presente.

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

Visualizzare le attestazioni

Ogni tipo di controllo di visualizzazione richiede un set diverso di attestazioni di visualizzazione, attestazioni di output e azioni da eseguire.

Analogamente alle attestazioni di visualizzazione definite in un profilo tecnico autocertificato, le attestazioni di visualizzazione rappresentano le attestazioni da raccogliere dall'utente all'interno del controllo di visualizzazione. L'elemento ClaimType a cui si fa riferimento deve specificare l'elemento UserInputType per un tipo di input utente supportato da Azure AD B2C, ad esempio TextBox o DropdownSingleSelect. Se un valore di attestazione visualizzato è richiesto da un'azione, impostare l'attributo Required su per true forzare l'utente a fornire un valore per tale attestazione di visualizzazione specifica.

Alcune attestazioni di visualizzazione sono necessarie per determinati tipi di controllo di visualizzazione. Ad esempio, VerificationCode è necessario per il controllo di visualizzazione di tipo VerificationControl. Usare l'attributo ControlClaimType per specificare quale DisplayClaim è designato per l'attestazione richiesta. Ad esempio:

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

Attestazioni di output

Le attestazioni di output di un controllo di visualizzazione non vengono inviate al passaggio di orchestrazione successivo. Vengono salvati temporaneamente solo per la sessione di controllo di visualizzazione corrente. Queste attestazioni temporanee possono essere condivise tra le diverse azioni dello stesso controllo di visualizzazione.

Per far scorrere le attestazioni di output al passaggio di orchestrazione successivo, usare OutputClaims del profilo tecnico autocertizionato effettivo, che fa riferimento a questo controllo di visualizzazione.

Visualizzare le azioni del controllo

Le azioni di un controllo di visualizzazione sono procedure che si verificano nel back-end di Azure AD B2C quando un utente esegue una determinata azione sul lato client (il browser). Ad esempio, le convalide da eseguire quando l'utente seleziona un pulsante nella pagina.

Un'azione definisce un elenco di profili tecnici di convalida. Vengono usati per convalidare alcune o tutte le attestazioni di visualizzazione del controllo di visualizzazione. Il profilo tecnico di convalida convalida l'input dell'utente e può restituire un errore all'utente. È possibile usare ContinueOnError, ContinueOnSuccess e Precondizioni nell'azione di controllo di visualizzazione in modo analogo al modo in cui vengono usati nei profili tecnici di convalida in un profilo tecnico autocertivo.

Azioni

L'elemento Actions contiene l'elemento seguente:

Elemento	Occorrenze	Descrizione
`Action`	1:n	Elenco di azioni da eseguire.

Azione

L'elemento Action contiene l'attributo seguente:

Attributo	Richiesto	Descrizione
`Id`	Sì	Tipo di operazione. I valori possibili sono: `SendCode` o `VerifyCode`. Il `SendCode` valore invia un codice all'utente. Questa azione può contenere due profili tecnici di convalida: uno per generare un codice e uno per inviarlo. Il `VerifyCode` valore verifica il codice digitato dall'utente nella casella di testo di input.

L'elemento Action contiene l'elemento seguente:

Elemento	Occorrenze	Descrizione
`ValidationClaimsExchange`	1:1	Identificatori dei profili tecnici usati per convalidare alcune o tutte le attestazioni di visualizzazione del profilo tecnico di riferimento. Tutte le attestazioni di input del profilo tecnico di riferimento devono essere visualizzate nelle attestazioni di visualizzazione del profilo tecnico di riferimento.

ValidationClaimsExchange

L'elemento ValidationClaimsExchange contiene l'elemento seguente:

Elemento	Occorrenze	Descrizione
`ValidationClaimsExchangeTechnicalProfile`	1:n	Profilo tecnico da usare per convalidare alcune o tutte le attestazioni di visualizzazione del profilo tecnico di riferimento.

L'elemento ValidationClaimsExchangeTechnicalProfile contiene l'attributo seguente:

Attributo	Richiesto	Descrizione
`TechnicalProfileReferenceId`	Sì	Identificatore di un profilo tecnico già definito nei criteri o nei criteri padre.

L'elemento ValidationClaimsExchangeTechnicalProfile contiene l'elemento seguente:

Elemento	Occorrenze	Descrizione
`Preconditions`	0:1	Elenco di precondizioni che devono essere soddisfatte per consentire l'esecuzione del profilo tecnico di convalida.

L'elemento Precondizione contiene gli attributi seguenti:

Attributo	Richiesto	Descrizione
`Type`	Sì	Tipo di controllo o query da eseguire per la precondizione. I valori possibili sono: `ClaimsExist` o `ClaimEquals`. `ClaimsExist` specifica che le azioni devono essere eseguite se le attestazioni specificate esistono nel set di attestazioni corrente dell'utente. `ClaimEquals` specifica che le azioni devono essere eseguite se l'attestazione specificata esiste e il relativo valore è uguale al valore specificato.
`ExecuteActionsIf`	Sì	Indica se le azioni incluse nella precondizione devono essere eseguite nel caso in cui il test sia true o false.

L'elemento Precondition contiene gli elementi seguenti:

Elemento	Occorrenze	Descrizione
`Value`	1:n	Dati usati dal controllo. Se il controllo è di tipo `ClaimsExist`, in questo campo viene specificato un valore di ClaimTypeReferenceId per il quale eseguire query. Se il controllo è di tipo `ClaimEquals`, in questo campo viene specificato un valore di ClaimTypeReferenceId per il quale eseguire query, Specificare il valore da archiviare in un altro elemento valore.
`Action`	1:1	Azione da eseguire se il controllo della precondizione all'interno di un passaggio di orchestrazione è true. Il valore dell'azione è impostato su `SkipThisValidationTechnicalProfile`, che specifica che il profilo tecnico di convalida associato non deve essere eseguito.

Nell'esempio seguente viene inviato e verificato l'indirizzo di posta elettronica usando il profilo tecnico SSPR dell'ID Microsoft Entra.

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

Nell'esempio seguente viene inviato un codice tramite posta elettronica o SMS in base alla selezione dell'attestazione mfaType con precondizioni.

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

Riferimenti ai controlli di visualizzazione

Viene fatto riferimento ai controlli di visualizzazione nelle attestazioni di visualizzazione del profilo tecnico autocertificato.

Ad esempio:

<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" />

Passaggi successivi

Per esempi sull'uso del controllo di visualizzazione, vedere: