ContentDefinitions

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.

È possibile personalizzare l'aspetto di qualsiasi profilo tecnico autocertificato. Azure Active Directory B2C (Azure AD B2C) esegue il codice nel browser del cliente e usa un approccio moderno denominato Condivisione risorse tra le origini (CORS).

Per personalizzare l'interfaccia utente, si specifica un URL nell'elemento ContentDefinition con contenuto HTML personalizzato. Nel profilo tecnico autocertificato oppure OrchestrationStep, si punta a tale identificatore di definizione del contenuto. La definizione del contenuto può contenere un elemento LocalizedResourcesReferences che specifica un elenco di risorse localizzate da caricare. Azure AD B2C unisce elementi dell'interfaccia utente con il contenuto HTML caricato dall'URL e quindi mostra la pagina all'utente.

L'elemento ContentDefinitions include gli URL per i template HTML5 che possono essere usati in un percorso utente. L'URI della pagina HTML5 viene usato per un passaggio dell'interfaccia utente specificato. Ad esempio, le pagine di accesso o iscrizione, reimpostazione della password o di errore. Nei criteri di estensione è possibile modificare l'aspetto eseguendo l'override del LoadUri per il file HTML5. È possibile creare nuove definizioni del contenuto in base alle esigenze. Questo elemento può contenere un riferimento alle risorse localizzate, all'identificatore della localizzazione specificato nell'elemento Localizzazione.

L'esempio seguente mostra l'identificatore di definizione del contenuto e la definizione di risorse localizzate:

<ContentDefinition Id="api.localaccountsignup">
  <LoadUri>~/tenant/default/selfAsserted.cshtml</LoadUri>
  <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
  <DataUri>urn:com:microsoft:aad:b2c:elements:selfasserted:1.1.0</DataUri>
  <Metadata>
    <Item Key="DisplayName">Local account sign up page</Item>
  </Metadata>
  <LocalizedResourcesReferences MergeBehavior="Prepend">
    <LocalizedResourcesReference Language="en" LocalizedResourcesReferenceId="api.localaccountsignup.en" />
    <LocalizedResourcesReference Language="es" LocalizedResourcesReferenceId="api.localaccountsignup.es" />
    ...

I metadati del profilo tecnico autocertificato LocalAccountSignUpWithLogonEmail contengono l'identificatore di definizione del contenuto ContentDefinitionReferenceId impostato su api.localaccountsignup

<TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
  <DisplayName>Email signup</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ContentDefinitionReferenceId">api.localaccountsignup</Item>
    ...
  </Metadata>
  ...

ContentDefinition

L'elemento ContentDefinition contiene gli attributi seguenti:

Attributo	Obbligatoria	Descrizione
ID	Sì	Un identificatore per una definizione del contenuto. Il valore è quello specificato nella sezione ID di definizione del contenuto più avanti in questa pagina.

L'elemento ContentDefinition contiene gli elementi seguenti:

Elemento	Occorrenze	Descrizione
LoadUri	1:1	Una stringa che contiene l'URL della pagina HTML5 per la definizione del contenuto.
RecoveryUri	1:1	Una stringa che contiene l'URL della pagina HTML per la visualizzazione di un errore relativo alla definizione del contenuto. Attualmente non usato, il valore deve essere `~/common/default_page_error.html`.
DataUri	1:1	Una stringa che contiene l'URL relativo di un file HTML che fornisce l'esperienza utente da richiamare per il passaggio.
Metadati	0:1	Una raccolta di coppie chiave/valore che contiene i metadati usati per la definizione del contenuto.
LocalizedResourcesReferences	0:1	Una raccolta di riferimenti di risorse localizzate. Usare questo elemento per personalizzare la localizzazione di un'interfaccia utente e di un attributo delle attestazioni.

LoadUri

L'elemento LoadUri viene usato per specificare l'URL della pagina HTML5 per la definizione del contenuto. I pacchetti di avvio dei criteri personalizzati di Azure AD B2C sono dotati di definizioni di contenuto che usano pagine HTML di Azure AD B2C. LoadUri inizia con ~, che è un percorso relativo al tenant di Azure AD B2C.

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>~/tenant/templates/AzureBlue/unified.cshtml</LoadUri>
  ...
</ContentDefinition>

È possibile personalizzare l'interfaccia utente con i modelli HTML. Quando si usano modelli HTML, specificare un URL assoluto. L'esempio seguente illustra una definizione di contenuto con un modello HTML:

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>https://your-storage-account.blob.core.windows.net/your-container/customize-ui.html</LoadUri>
  ...
</ContentDefinition>

DataUri

L'elemento DataUri viene usato per specificare l'identificatore della pagina. Azure AD B2C usa l'identificatore di pagina per caricare e avviare gli elementi dell'interfaccia utente e JavaScript lato client. Il formato del valore è urn:com:microsoft:aad:b2c:elements:page-name:version. Nella tabella seguente sono elencati gli identificatori di pagina che è possibile usare.

Identificatore di pagina	Descrizione
`globalexception`	Viene visualizzata una pagina di errore quando viene rilevata un'eccezione o un errore.
`providerselection`, `idpselection`	Elenca i provider di identità tra cui gli utenti possono scegliere durante la procedura di accesso.
`unifiedssp`	Viene visualizzato un modulo per eseguire l'accesso con un account locale basato su un indirizzo di posta elettronica o un nome utente. Questo valore fornisce anche il collegamento "Mantieni la funzionalità di accesso" e "Dimenticata la password?"
`unifiedssd`	Visualizza un modulo per l'accesso con un account locale basato su un indirizzo di posta elettronica o un nome utente. Questo identificatore di pagina è deprecato. Usare invece l'identificatore di `unifiedssp` pagina.
`multifactor`	Vengono verificati numeri di telefono usando SMS o chiamata vocale durante la procedura di iscrizione o di accesso.
`selfasserted`	Visualizza un modulo per raccogliere dati da un utente. Ad esempio, consente agli utenti di creare o aggiornare il proprio profilo.

Selezionare un layout di pagina

È possibile abilitare il codice lato client JavaScript inserendo contract tra elements e il tipo di pagina. Ad esempio, urn:com:microsoft:aad:b2c:elements:contract:page-name:version.

La parte della versione di DataUri specifica il pacchetto di contenuto contenente HTML, CSS e JavaScript per gli elementi dell'interfaccia utente nei criteri. Se si intende abilitare il codice lato client JavaScript, gli elementi su cui si basa JavaScript devono essere non modificabili. Se non sono modificabili, eventuali modifiche potrebbero causare comportamenti imprevisti nelle pagine utente. Per evitare questi problemi, applicare l'uso di un layout di pagina e specificare una versione del layout di pagina. In questo modo si garantisce che tutte le definizioni di contenuto basate su JavaScript in siano non modificabili. Anche se non si intende abilitare JavaScript, è comunque necessario specificare la versione del layout di pagina per le pagine.

Nell'esempio seguente viene illustrato l'oggetto DataUri della selfasserted versione 1.2.0:

<!-- 
<BuildingBlocks> 
  <ContentDefinitions>-->
    <ContentDefinition Id="api.localaccountpasswordreset">
      <LoadUri>~/tenant/templates/AzureBlue/selfAsserted.cshtml</LoadUri>
      <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:1.2.0</DataUri>
      <Metadata>
        <Item Key="DisplayName">Local account change password page</Item>
      </Metadata>
    </ContentDefinition>
  <!-- 
  </ContentDefinitions> 
</BuildingBlocks> -->

Migrazione al layout di pagina

Per eseguire la migrazione dal valore DataUri precedente (senza contratto di pagina) alla versione del layout di pagina, aggiungere la parola contract seguita da una versione della pagina. Usare la tabella seguente per eseguire la migrazione dal valore DataUri precedente alla versione del layout di pagina.

Valore di DataUri precedente	Nuovo valore di DataUri
`urn:com:microsoft:aad:b2c:elements:globalexception:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:globalexception:1.2.1`
`urn:com:microsoft:aad:b2c:elements:globalexception:1.1.0`	`urn:com:microsoft:aad:b2c:elements:contract:globalexception:1.2.1`
`urn:com:microsoft:aad:b2c:elements:idpselection:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:providerselection:1.2.1`
`urn:com:microsoft:aad:b2c:elements:selfasserted:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.7`
`urn:com:microsoft:aad:b2c:elements:selfasserted:1.1.0`	`urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.7`
`urn:com:microsoft:aad:b2c:elements:unifiedssd:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:unifiedssd:1.2.1`
`urn:com:microsoft:aad:b2c:elements:unifiedssp:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:unifiedssp:2.1.5`
`urn:com:microsoft:aad:b2c:elements:unifiedssp:1.1.0`	`urn:com:microsoft:aad:b2c:elements:contract:unifiedssp:2.1.5`
`urn:com:microsoft:aad:b2c:elements:multifactor:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:multifactor:1.2.5`
`urn:com:microsoft:aad:b2c:elements:multifactor:1.1.0`	`urn:com:microsoft:aad:b2c:elements:contract:multifactor:1.2.5`

L'esempio seguente mostra gli identificatori di definizione del contenuto e l'URI di dati corrispondente con la versione più recente della pagina:

<!-- 
<BuildingBlocks> -->
  <ContentDefinitions>
    <ContentDefinition Id="api.error">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:globalexception:1.2.1</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.idpselections">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:providerselection:1.2.1</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.idpselections.signup">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:providerselection:1.2.1</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.signuporsignin">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:unifiedssp:2.1.7</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.selfasserted">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.14</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.selfasserted.profileupdate">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.14</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.localaccountsignup">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.14</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.localaccountpasswordreset">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.14</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.phonefactor">
      <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:multifactor:1.2.5</DataUri>
    </ContentDefinition>
  </ContentDefinitions>
<!-- 
</BuildingBlocks> -->

Metadati

L'elemento Metadata contiene gli elementi seguenti:

Elemento	Occorrenze	Descrizione
Elemento	0:n	Metadati correlati alla definizione del contenuto.

L'elemento Elemento di Metadati contiene gli attributi seguenti:

Attributo	Obbligatoria	Descrizione
Chiave	Sì	Chiave dei metadati.

Chiavi di metadati

La definizione del contenuto supporta gli elementi di metadati seguenti:

Chiave	Obbligatoria	Descrizione
DisplayName	No	Stringa contenente il nome della definizione del contenuto.

LocalizedResourcesReferences

L'elemento LocalizedResources contiene gli elementi seguenti:

Elemento	Occorrenze	Descrizione
LocalizedResourcesReference	1:n	Un elenco di riferimenti di risorse localizzate per la definizione del contenuto.

L'elemento LocalizedResourcesReference contiene gli attributi seguenti:

Attributo	Obbligatoria	Descrizione
Linguaggio	Sì	Una stringa che contiene una lingua supportata per i criteri per RFC 5646 - Tag per identificare le lingue.
LocalizedResourcesReferenceId	Sì	L'identificatore dell'elemento LocalizedResources.

Nell'esempio seguente viene illustrata una definizione del contenuto di iscrizione o accesso con un riferimento alla localizzazione per inglese, francese e spagnolo:

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>~/tenant/default/unified.cshtml</LoadUri>
  <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
  <DataUri>urn:com:microsoft:aad:b2c:elements:unifiedssp:1.0.0</DataUri>
  <Metadata>
    <Item Key="DisplayName">Signin and Signup</Item>
  </Metadata>
  <LocalizedResourcesReferences MergeBehavior="Prepend">
    <LocalizedResourcesReference Language="en" LocalizedResourcesReferenceId="api.signuporsignin.en" />
    <LocalizedResourcesReference Language="fr" LocalizedResourcesReferenceId="api.signuporsignin.rf" />
    <LocalizedResourcesReference Language="es" LocalizedResourcesReferenceId="api.signuporsignin.es" />
</LocalizedResourcesReferences>
</ContentDefinition>

Per informazioni su come aggiungere il supporto di localizzazione per le definizioni del contenuto, vedere Localizzazione.

ID definizione del contenuto

L'attributo ID dell'elemento ContentDefinition specifica il tipo di pagina correlato alla definizione del contenuto. L'elemento definisce il contesto a cui un modello personalizzato HTML5/CSS viene applicato. La tabella seguente descrive il set degli ID definizione del contenuto riconosciuti dal framework di gestione dell'identità e i tipi di pagina correlati. È possibile creare le definizioni del contenuto con un ID arbitrario.

ID	Modello predefinito	Descrizione
api.error	exception.cshtml	Pagina di errore: Viene visualizzata una pagina di errore quando viene rilevata un'eccezione o un errore.
api.idpselections	idpSelector.cshtml	Pagina di selezione del provider di identità - Elenca i provider di identità tra cui gli utenti possono scegliere durante l'iscrizione. Si tratta in genere di provider di identità aziendali, provider di identità basati su social network, ad esempio Facebook e Google+, o account locali.
api.idpselections.signup	idpSelector.cshtml	Pagina di selezione del provider di identità: Elenca i provider di identità tra cui gli utenti possono scegliere durante l'iscrizione. Si tratta in genere di provider di identità aziendali, provider di identità basati su social network, ad esempio Facebook e Google+, o account locali.
api.localaccountpasswordreset	selfasserted.cshtml	Pagina di password dimenticata: mostra un modulo che gli utenti devono completare per avviare la reimpostazione della password.
api.localaccountsignin	selfasserted.cshtml	Pagina di accesso all'account locale: mostra un modulo per l'accesso con un account locale basato su un indirizzo e-mail o un nome utente. Il modulo può contenere una casella di input di testo e una casella di immissione della password.
api.localaccountsignup	selfasserted.cshtml	Pagina d'iscrizione all'account locale:mostra un modulo per l'iscrizione con un account locale basato su un indirizzo e-mail o un nome utente. Il modulo può contenere diversi controlli di input, ad esempio una casella per l'immissione di testo e una per l'immissione della password, un pulsante di opzione, caselle a discesa a selezione singola e caselle di controllo con selezione multipla.
api.phonefactor	multifactor-1.0.0.cshtml	Pagina di autenticazione a più fattori: vengono verificati numeri di telefono usando SMS o vocali, durante l'iscrizione o l'accesso.
api.selfasserted	selfasserted.cshtml	Pagina di iscrizione a un account social: mostra un modulo che gli utenti devono completare quando effettuano l'iscrizione usando un account esistente da un provider di identità social. Questa pagina è simile alla pagina di iscrizione dell'account di social network descritta in precedenza, ad eccezione dei campi di immissione della password.
api.selfasserted.profileupdate	updateprofile.cshtml	Pagina di aggiornamento profilo: mostra un modulo a cui gli utenti possono accedere per aggiornare il profilo. Questa pagina è simile alla pagina di iscrizione dell'account di social network, ad eccezione dei campi di immissione della password.
api.signuporsignin	unified.cshtml	Pagina unificata per l'iscrizione o accesso: viene gestito il processo di iscrizione e accesso dell'utente. Gli utenti possono usare provider di identità aziendali, provider di identità basati su social network, ad esempio Facebook o Google +, o account locali.

Passaggi successivi

Per un esempio di personalizzazione dell'interfaccia utente usando le definizioni di contenuto, vedere:

Personalizzare l'interfaccia utente dell'applicazione usando criteri personalizzati