Definire attributi personalizzati in Azure Active Directory B2C

  • Articolo

Prima di iniziare, usare il selettore Scegli un tipo di criterio per scegliere il tipo di criterio che si sta configurando. Azure Active Directory B2C offre due metodi per definire il modo in cui gli utenti interagiscono con le applicazioni: tramite flussi utente predefiniti o tramite criteri personalizzati completamente configurabili. I passaggi necessari in questo articolo sono diversi per ogni metodo.

Nell'articolo Aggiungere attestazioni e personalizzare l'input utente usando criteri personalizzati si apprenderà come usare gli attributi predefiniti del profilo utente. In questo articolo viene abilitato un attributo personalizzato nella directory di Azure Active Directory B2C (Azure AD B2C). Successivamente, è possibile usare il nuovo attributo come attestazione personalizzata nei flussi utente o nei criteri personalizzati contemporaneamente.

La directory di Azure AD B2C include un set predefinito di attributi. Tuttavia, spesso è necessario creare attributi personalizzati per gestire lo scenario specifico, ad esempio quando:

  • Un'applicazione rivolta al cliente deve rendere persistente un attributo loyaltyId .
  • Un provider di identità ha un identificatore utente univoco, uniqueUserGUID, che deve essere salvato in modo permanente.
  • Un percorso utente personalizzato deve rendere persistente lo stato dell'utente, migrationStatus, per consentire l'uso di altre logiche.

I termini proprietà di estensione, attributo personalizzato e attestazione personalizzata fanno riferimento allo stesso concetto nel contesto di questo articolo. Il nome varia in base al contesto, ad esempio applicazione, oggetto o criteri.

Azure AD B2C consente di estendere il set di attributi archiviati in ogni account utente. Questi attributi possono anche essere scritti e letti usando l'API Microsoft Graph.

Prerequisiti

Creare un attributo personalizzato

  1. Accedere al portale di Azure come amministratore globale del tenant di Azure AD B2C.
  2. Se si ha accesso a più tenant, selezionare l'icona Impostazioni nel menu in alto per passare al tenant di Azure AD B2C dal menu Directory e sottoscrizioni.
  3. Scegliere Tutti i servizi nell'angolo in alto a sinistra del portale di Azure, cercare Azure AD B2C e selezionarlo.
  4. Selezionare Attributi utente, quindi selezionare Aggiungi.
  5. Fornire un Nome per l'attributo personalizzato (ad esempio, "ShoeSize")
  6. Scegliere un Tipo di dati. Sono disponibili solo Stringa, Booleano e Int.
  7. Facoltativamente, immettere una Descrizione esclusivamente a scopo informativo.
  8. Seleziona Crea.

L'attributo personalizzato è ora disponibile nell'elenco degli Attributi utentee per l'uso nei flussi utente. Un attributo personalizzato viene creato solo la prima volta che viene usato in qualsiasi flusso utente e non quando lo si aggiunge all'elenco di attributi utente.

Usare un attributo personalizzato nel flusso utente

  1. Nel tenant di Azure AD B2C selezionare Flussi utente.
  2. Fare clic sul criterio, ad esempio "B2C_1_SignupSignin", per aprirlo.
  3. Fare clic su Attributi utente e selezionare l'attributo personalizzato (ad esempio, "ShoeSize"). Seleziona Salva.
  4. Fare clic su Attestazioni dell'applicazione e selezionare l'attributo personalizzato.
  5. Seleziona Salva.

Dopo aver creato un nuovo utente usando il flusso utente, è possibile usare la funzionalità Esegui flusso utente nel flusso utente per verificare l'esperienza del cliente. Ora si dovrebbe vedere ShoeSize nell'elenco di attributi che vengono raccolti durante il percorso dell'utente e nel token inviato all'applicazione.

App delle estensioni di Azure AD B2C

Gli attributi di estensione possono essere registrati solo in un oggetto applicazione, anche se potrebbero contenere dati per un utente. L'attributo di estensione è associato all'applicazione denominata b2c-extensions-app. Non modificare questa applicazione, perché viene usata da Azure AD B2C per l'archiviazione dei dati utente. È possibile trovare questa applicazione in Azure AD B2C, registrazioni di app.

Ottenere l'ID applicazione dell'app per le estensioni

  1. Accedi al portale di Azure.
  2. Se si ha accesso a più tenant, selezionare l'icona Impostazioni nel menu in alto per passare al tenant di Azure AD B2C dal menu Directory e sottoscrizioni.
  3. Nel menu a sinistra selezionare Azure AD B2C. In alternativa, selezionare Tutti i servizi e quindi cercare e selezionare Azure AD B2C.
  4. Selezionare Registrazioni app e quindi Tutte le applicazioni.
  5. Selezionare l'applicazione b2c-extensions-app. Do not modify. Used by AADB2C for storing user data..
  6. Copia l'ID applicazione. Esempio: 11111111-1111-1111-1111-111111111111.

Ottenere le proprietà dell'applicazione dell'app extensions

  1. Accedi al portale di Azure.
  2. Se si ha accesso a più tenant, selezionare l'icona Impostazioni nel menu in alto per passare al tenant di Azure AD B2C dal menu Directory e sottoscrizioni.
  3. Nel menu a sinistra selezionare Azure AD B2C. In alternativa, selezionare Tutti i servizi e quindi cercare e selezionare Azure AD B2C.
  4. Selezionare Registrazioni app e quindi Tutte le applicazioni.
  5. Selezionare b2c-extensions-app. Non modificare. Usato da AADB2C per l'archiviazione dei dati utente. Applicazione.
  6. Copiare gli identificatori seguenti negli Appunti e salvarli:
    • ID applicazione. Esempio: 11111111-1111-1111-1111-111111111111.
    • ID oggetto. Esempio: 22222222-2222-2222-2222-222222222222.

Modificare i criteri personalizzati

Per abilitare gli attributi personalizzati nei criteri, specificare l'ID applicazione e l'ID oggetto applicazione nei metadati del profilo tecnico comune di AAD. Il profilo tecnico AAD-Common* si trova nel profilo tecnico Microsoft Entra ID di base e fornisce supporto per la gestione degli utenti di Microsoft Entra. Altri profili tecnici di Microsoft Entra ID includono AAD-Common per l'uso della configurazione. Eseguire l'override del profilo tecnico AAD-Common nel file di estensione.

  1. Aprire il file delle estensioni del criterio, Ad esempio, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.

  2. Trovare l'elemento ClaimsProviders. Aggiungere un nuovo ClaimsProvider all'elemento ClaimsProviders.

  3. Inserire l'ID applicazione registrato in precedenza, tra gli elementi di apertura <Item Key="ClientId"> e chiusura</Item>.

  4. Inserire l'OBJECTID dell'applicazione registrato in precedenza, tra gli elementi di apertura <Item Key="ApplicationObjectId"> e chiusura</Item>.

    <!-- 
<ClaimsProviders> -->
  <ClaimsProvider>
    <DisplayName>Azure Active Directory</DisplayName>
    <TechnicalProfiles>
      <TechnicalProfile Id="AAD-Common">
        <Metadata>
          <!--Insert b2c-extensions-app application ID here, for example: 11111111-1111-1111-1111-111111111111-->  
          <Item Key="ClientId"></Item>
          <!--Insert b2c-extensions-app application ObjectId here, for example: 22222222-2222-2222-2222-222222222222-->
          <Item Key="ApplicationObjectId"></Item>
        </Metadata>
      </TechnicalProfile>
    </TechnicalProfiles> 
  </ClaimsProvider>
<!-- 
</ClaimsProviders> -->

Caricare i criteri personalizzati

  1. Accedi al portale di Azure.
  2. Se si ha accesso a più tenant, selezionare l'icona Impostazioni nel menu in alto per passare al tenant di Azure AD B2C dal menu Directory e sottoscrizioni.
  3. Scegliere Tutti i servizi nell'angolo in alto a sinistra nel portale di Azure e quindi cercare e selezionare Registrazioni per l'app.
  4. Fare clic su Framework dell'esperienza di gestione delle identità.
  5. Selezionare Carica criteri personalizzati e quindi caricare i file dei criteri TrustFrameworkExtensions.xml modificati.

Nota

La prima volta che il profilo tecnico Microsoft Entra ID rende persistente l'attestazione nella directory, verifica se l'attributo personalizzato esiste. In caso contrario, crea l'attributo personalizzato.

Creare un attributo personalizzato tramite portale di Azure

Gli stessi attributi di estensione vengono condivisi tra criteri predefiniti e personalizzati. Quando si aggiungono attributi personalizzati tramite l'esperienza del portale, questi attributi vengono registrati usando l'app b2c-extensions-app esistente in ogni tenant B2C.

È possibile creare questi attributi usando l'interfaccia utente del portale prima o dopo l'uso nei criteri personalizzati. Quando si crea un attributo loyaltyId nel portale, è necessario farvi riferimento come indicato di seguito:

Name Campo di utilizzo
extension_loyaltyId Criteri personalizzati
extension_<b2c-extensions-app-guid>_loyaltyId API di Microsoft Graph

Nota

Quando si usa un attributo personalizzato nei criteri personalizzati, è necessario anteporre l'ID del tipo di attestazione con extension_ per consentire la corretta esecuzione del mapping dei dati all'interno della directory di Azure AD B2C.

L'esempio seguente illustra l'uso di attributi personalizzati in una definizione di attestazione di criteri personalizzata di Azure AD B2C.

<BuildingBlocks>
  <ClaimsSchema>
    <ClaimType Id="extension_loyaltyId">
      <DisplayName>Loyalty Identification</DisplayName>
      <DataType>string</DataType>
      <UserHelpText>Your loyalty number from your membership card</UserHelpText>
      <UserInputType>TextBox</UserInputType>
    </ClaimType>
  </ClaimsSchema>
</BuildingBlocks>

L'esempio seguente illustra l'uso di un attributo personalizzato nei criteri personalizzati di Azure AD B2C in un profilo tecnico, input, output e attestazioni persistenti.

<InputClaims>
  <InputClaim ClaimTypeReferenceId="extension_loyaltyId"  />
</InputClaims>
<PersistedClaims>
  <PersistedClaim ClaimTypeReferenceId="extension_loyaltyId" />
</PersistedClaims>
<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="extension_loyaltyId" />
</OutputClaims>

Gestire gli attributi di estensione tramite Microsoft Graph

È possibile usare Microsoft Graph per creare e gestire gli attributi personalizzati e quindi impostare i valori per un utente. Gli attributi di estensione sono detti anche estensioni directory o Microsoft Entra.

Gli attributi personalizzati (estensioni di directory) nell'API Microsoft Graph vengono denominati usando la convenzione extension_{appId-without-hyphens}_{extensionProperty-name} in cui {appId-without-hyphens} è la versione rimossa dell'appId (denominato ID client nel portale di Azure AD B2C) per con b2c-extensions-app solo caratteri 0-9 e A-Z. Ad esempio, se l'appId dell'applicazione b2c-extensions-app è 25883231-668a-43a7-80b2-5685c3f874bc e il nome dell'attributo è loyaltyId, l'attributo personalizzato è denominato extension_25883231668a43a780b25685c3f874bc_loyaltyId.

Informazioni su come gestire gli attributi dell'estensione nel tenant di Azure AD B2C usando l'API Microsoft Graph.

Rimuovere l'attributo di estensione

A differenza degli attributi predefiniti, è possibile rimuovere attributi personalizzati. È anche possibile rimuovere i valori degli attributi di estensione.

Importante

Prima di rimuovere l'attributo personalizzato, per ogni account nella directory impostare il valore dell'attributo di estensione su null. In questo modo, si rimuovono in modo esplicito i valori dell'attributo di estensione. Continuare quindi a rimuovere l'attributo di estensione stesso. È possibile eseguire query sugli attributi personalizzati usando l'API Microsoft Graph.

Usare la procedura seguente per rimuovere un attributo personalizzato da un flusso utente nel tenant:

  1. Accedere al portale di Azure come amministratore globale del tenant di Azure AD B2C.
  2. Assicurarsi di usare la directory che contiene il tenant di Azure AD B2C:
    1. Selezionare l'icona Directory e sottoscrizioni nella barra degli strumenti del portale.
    2. Nelle impostazioni del portale | Pagina Directory e sottoscrizioni , trovare la directory di Azure AD B2C nell'elenco Nome directory e quindi selezionare Cambia
  3. Scegliere Tutti i servizi nell'angolo in alto a sinistra del portale di Azure, cercare Azure AD B2C e selezionarlo.
  4. Selezionare Attributi utente e quindi selezionare l'attributo da eliminare.
  5. Selezionare Elimina e quindi scegliere Sì per confermare.

Usare l'API Microsoft Graph per gestire gli attributi personalizzati.

Passaggi successivi

Informazioni su come aggiungere attestazioni e personalizzare l'input utente usando criteri personalizzati. Questo esempio usa un'attestazione predefinita 'city'. Per usare un attributo personalizzato, sostituire 'city' con gli attributi personalizzati.