Definire un profilo tecnico di Microsoft Entra in un criterio personalizzato di Azure Active Directory B2C

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.

Azure Active Directory B2C (Azure AD B2C) fornisce supporto per la gestione degli utenti di Microsoft Entra. Questo articolo descrive le specifiche di un profilo tecnico per l'interazione con un provider di attestazioni che supporta questo protocollo standardizzato.

Protocollo

L'attributo Nome dell'elemento Protocollo deve essere impostato su Proprietary. L'attributo gestore deve contenere il nome completo dell'assembly del gestore di protocollo Web.TPEngine.Providers.AzureActiveDirectoryProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

I profili tecnici Microsoft Entra seguenti del pacchetto di avvio dei criteri personalizzati includono il profilo tecnico AAD-Common . I profili tecnici Microsoft Entra non specificano il protocollo perché il protocollo è configurato nel profilo tecnico AAD-Common :

AAD-UserReadUsingAlternativeSecurityId e AAD-UserReadUsingAlternativeSecurityId-NoError - Cercare un account social nella directory.
AAD-UserWriteUsingAlternativeSecurityId - Creare un nuovo account social.
AAD-UserReadUsingEmailAddress - Cercare un account locale nella directory.
AAD-UserWriteUsingLogonEmail - Creare un nuovo account locale.
AAD-UserWritePasswordUsingObjectId - Aggiornare una password di un account locale.
AAD-UserWriteProfileUsingObjectId - Aggiornare un profilo utente di un account locale o social.
AAD-UserReadUsingObjectId - Leggere un profilo utente di un account locale o social.
AAD-UserWritePhoneNumberUsingObjectId - Scrivere il numero di telefono di autenticazione a più fattori di un account locale o social

Nell'esempio seguente viene illustrato un profilo tecnico AAD-Common:

<TechnicalProfile Id="AAD-Common">
  <DisplayName>Azure Active Directory</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureActiveDirectoryProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />

  <CryptographicKeys>
    <Key Id="issuer_secret" StorageReferenceId="B2C_1A_TokenSigningKeyContainer" />
  </CryptographicKeys>

  <!-- We need this here to suppress the SelfAsserted provider from invoking SSO on validation profiles. -->
  <IncludeInSso>false</IncludeInSso>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

InputClaims

L'elemento InputClaims contiene un'attestazione, usata per cercare un account nella directory o crearne una nuova. Nella raccolta di attestazioni di input deve essere presente esattamente un elemento InputClaim per tutti i profili tecnici di Microsoft Entra. Potrebbe essere necessario eseguire il mapping del nome dell'attestazione definita nel criterio al nome definito in Microsoft Entra ID.

Per leggere, aggiornare o eliminare un account utente esistente, l'attestazione di input è una chiave che identifica in modo univoco l'account nella directory Microsoft Entra. Ad esempio, objectId, userPrincipalName, signInNames.emailAddress, signInNames.userName o alternativeSecurityId.

Per creare un nuovo account utente, l'attestazione di input è una chiave che identifica in modo univoco un account locale o federato. Ad esempio, account locale: signInNames.emailAddress o signInNames.userName. Per un account federato: alternativeSecurityId.

L'elemento InputClaimsTransformations può contenere una raccolta di elementi di trasformazione delle attestazioni di input usati per modificare l'attestazione di input o generarne una nuova.

OutputClaims

L'elemento OutputClaims contiene un elenco di attestazioni restituite dal profilo tecnico Microsoft Entra. Potrebbe essere necessario eseguire il mapping del nome dell'attestazione definita nel criterio al nome definito in Microsoft Entra ID. È anche possibile includere attestazioni che non vengono restituite dall'ID Entra di Microsoft, purché si imposti l'attributo DefaultValue .

L'elemento OutputClaimsTransformations può contenere una raccolta di elementi OutputClaimsTransformation che vengono usati per modificare le attestazioni di output o per generarne di nuove.

Ad esempio, il profilo tecnico AAD-UserWriteUsingLogonEmail crea un account locale e restituisce le attestazioni seguenti:

objectId, ovvero l'identificatore del nuovo account
newUser, che indica se l'utente è nuovo
authenticationSource, che imposta l'autenticazione a localAccountAuthentication
userPrincipalName, ovvero il nome dell'entità utente del nuovo account
signInNames.emailAddress, ovvero il nome di accesso dell'account, simile all'attestazione input del messaggio di posta elettronica

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="objectId" />
  <OutputClaim ClaimTypeReferenceId="newUser" PartnerClaimType="newClaimsPrincipalCreated" />
  <OutputClaim ClaimTypeReferenceId="authenticationSource" DefaultValue="localAccountAuthentication" />
  <OutputClaim ClaimTypeReferenceId="userPrincipalName" />
  <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" />
</OutputClaims>

PersistedClaims

L'elemento PersistedClaims contiene tutti i valori che devono essere salvati in modo permanente da Microsoft Entra ID con possibili informazioni di mapping tra un tipo di attestazione già definito nella sezione ClaimsSchema nei criteri e nel nome dell'attributo Microsoft Entra.

Il profilo tecnico AAD-UserWriteUsingLogonEmail che crea un nuovo account locale, rende persistenti le attestazioni seguenti:

  <PersistedClaims>
    <!-- Required claims -->
    <PersistedClaim ClaimTypeReferenceId="email" PartnerClaimType="signInNames.emailAddress" />
    <PersistedClaim ClaimTypeReferenceId="newPassword" PartnerClaimType="password"/>
    <PersistedClaim ClaimTypeReferenceId="displayName" DefaultValue="unknown" />
    <PersistedClaim ClaimTypeReferenceId="passwordPolicies" DefaultValue="DisablePasswordExpiration" />

    <!-- Optional claims. -->
    <PersistedClaim ClaimTypeReferenceId="givenName" />
    <PersistedClaim ClaimTypeReferenceId="surname" />
  </PersistedClaims>

Il nome dell'attestazione è il nome dell'attributo Microsoft Entra, a meno che non venga specificato l'attributo PartnerClaimType, che contiene il nome dell'attributo Microsoft Entra.

Requisiti di un'operazione

Nel contenitore delle attestazioni deve essere presente esattamente un elemento InputClaim per tutti i profili tecnici di Microsoft Entra.
L'articolo sugli attributi del profilo utente descrive gli attributi del profilo utente di Azure AD B2C supportati che è possibile usare nelle attestazioni di input, nelle attestazioni di output e nelle attestazioni persistenti.
Se l'operazione è Write oppure DeleteClaims, allora deve essere visualizzata anche in un elemento PersistedClaims.
Il valore dell'attestazione userPrincipalName deve essere nel formato user@tenant.onmicrosoft.com.
L'attestazione displayName è obbligatoria e non può essere una stringa vuota.

Operazioni sul profilo tecnico Di Microsoft Entra

Lettura

L'operazione di lettura legge i dati su un singolo account utente. Il profilo tecnico seguente legge i dati su un account utente usando l'objectId dell'utente:

<TechnicalProfile Id="AAD-UserReadUsingObjectId">
  <Metadata>
    <Item Key="Operation">Read</Item>
    <Item Key="RaiseErrorIfClaimsPrincipalDoesNotExist">true</Item>
  </Metadata>
  <IncludeInSso>false</IncludeInSso>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" Required="true" />
  </InputClaims>
  <OutputClaims>

    <!-- Required claims -->
    <OutputClaim ClaimTypeReferenceId="strongAuthenticationPhoneNumber" />

    <!-- Optional claims -->
    <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" />
    <OutputClaim ClaimTypeReferenceId="displayName" />
    <OutputClaim ClaimTypeReferenceId="otherMails" />
    <OutputClaim ClaimTypeReferenceId="givenName" />
    <OutputClaim ClaimTypeReferenceId="surname" />
  </OutputClaims>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

Scrivere

L'operazione di scrittura crea o aggiorna un singolo account utente. Il profilo tecnico seguente crea nuovi account social:

<TechnicalProfile Id="AAD-UserWriteUsingAlternativeSecurityId">
  <Metadata>
    <Item Key="Operation">Write</Item>
    <Item Key="RaiseErrorIfClaimsPrincipalAlreadyExists">true</Item>
    <Item Key="UserMessageIfClaimsPrincipalAlreadyExists">You are already registered, please press the back button and sign in instead.</Item>
  </Metadata>
  <IncludeInSso>false</IncludeInSso>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="CreateOtherMailsFromEmail" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="AlternativeSecurityId" PartnerClaimType="alternativeSecurityId" Required="true" />
  </InputClaims>
  <PersistedClaims>
    <!-- Required claims -->
    <PersistedClaim ClaimTypeReferenceId="alternativeSecurityId" />
    <PersistedClaim ClaimTypeReferenceId="userPrincipalName" />
    <PersistedClaim ClaimTypeReferenceId="mailNickName" DefaultValue="unknown" />
    <PersistedClaim ClaimTypeReferenceId="displayName" DefaultValue="unknown" />

    <!-- Optional claims -->
    <PersistedClaim ClaimTypeReferenceId="otherMails" />
    <PersistedClaim ClaimTypeReferenceId="givenName" />
    <PersistedClaim ClaimTypeReferenceId="surname" />
  </PersistedClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="objectId" />
    <OutputClaim ClaimTypeReferenceId="newUser" PartnerClaimType="newClaimsPrincipalCreated" />
    <OutputClaim ClaimTypeReferenceId="otherMails" />
  </OutputClaims>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-AAD" />
</TechnicalProfile>

DeleteClaims

L'operazione DeleteClaims elimina le informazioni da un elenco specificato di attestazioni. Il profilo tecnico seguente elimina le attestazioni:

<TechnicalProfile Id="AAD-DeleteClaimsUsingObjectId">
  <Metadata>
    <Item Key="Operation">DeleteClaims</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" Required="true" />
  </InputClaims>
  <PersistedClaims>
    <PersistedClaim ClaimTypeReferenceId="objectId" />
    <PersistedClaim ClaimTypeReferenceId="Verified.strongAuthenticationPhoneNumber" PartnerClaimType="strongAuthenticationPhoneNumber" />
  </PersistedClaims>
  <OutputClaims />
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

DeleteClaimsPrincipal

L'operazione DeleteClaimsPrincipal elimina un singolo account utente dalla directory. Il profilo tecnico seguente elimina un account utente dalla directory usando il nome dell'entità utente:

<TechnicalProfile Id="AAD-DeleteUserUsingObjectId">
  <Metadata>
    <Item Key="Operation">DeleteClaimsPrincipal</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" Required="true" />
  </InputClaims>
  <OutputClaims/>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

Il profilo tecnico seguente elimina un account utente social mediante alternativeSecurityId:

<TechnicalProfile Id="AAD-DeleteUserUsingAlternativeSecurityId">
  <Metadata>
    <Item Key="Operation">DeleteClaimsPrincipal</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="alternativeSecurityId" Required="true" />
  </InputClaims>
  <OutputClaims/>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

Metadati UFX

Attributo	Richiesto	Descrizione
Operazione	Sì	L'operazione da eseguire. I valori possibili sono: `Read`, `Write`, `DeleteClaims` o `DeleteClaimsPrincipal`.
RaiseErrorIfClaimsPrincipalDoesNotExist	No	Genera un errore se l'oggetto utente non esiste nella directory. I valori possibili sono: `true` o `false`.
RaiseErrorIfClaimsPrincipalAlreadyExists	No	Genera un errore se l'oggetto utente esiste già. I valori possibili sono: `true` o `false`. Questi metadati sono applicabili solo per l'operazione di scrittura.
ApplicationObjectId	No	L'identificatore di oggetto dell'applicazione per gli attributi di estensione. Valore: ObjectID di un'applicazione. Per altre informazioni, vedere Usare attributi personalizzati.
ClientId	No	L'identificatore client per l'accesso ai tenant come terza parte. Per altre informazioni, vedere Usare gli attributi personalizzati in un criterio di modifica del profilo personalizzato
IncludeClaimResolvingInClaimsHandling	No	Per le attestazioni di input e output, specifica se la risoluzione delle attestazioni è inclusa nel profilo tecnico. Valori possibili: `true` o `false` (impostazione predefinita). Se si vuole usare un resolver di attestazioni nel profilo tecnico, impostarlo su `true`.

Elementi dell'interfaccia utente

È possibile usare le impostazioni seguenti per configurare il messaggio di errore visualizzato in caso di errore. I metadati devono essere configurati nel profilo tecnico autocertificato . I messaggi di errore possono essere localizzati.

Attributo	Richiesto	Descrizione
UserMessageIfClaimsPrincipalAlreadyExists	No	Se deve essere generato un errore (vedere la descrizione dell'attributo RaiseErrorIfClaimsPrincipalAlreadyExists) specificare il messaggio da visualizzare all'utente se l'oggetto utente esiste già.
UserMessageIfClaimsPrincipalDoesNotExist	No	Se deve essere generato un errore (vedere la descrizione dell'attributo RaiseErrorIfClaimsPrincipalDoesNotExist), specificare il messaggio da visualizzare all'utente se l'oggetto utente non esiste.

Passaggi successivi

Vedere l'articolo seguente, ad esempio per l'uso del profilo tecnico Microsoft Entra:

Aggiungere attestazioni e personalizzare l'input utente usando criteri personalizzati in Azure Active Directory B2C