Definición de un perfil técnico de Microsoft Entra en una directiva personalizada de Azure Active Directory B2C

Artículo
01/11/2024

Nota:

En Azure Active Directory B2C, las directivas personalizadas se han diseñado principalmente para abordar escenarios complejos. Para la mayoría de los escenarios, se recomienda usar flujos de usuario integrados. Si no lo ha hecho, obtenga información sobre el paquete de inicio de directivas personalizadas en Introducción a las directivas personalizadas en Active Directory B2C.

Azure Active Directory B2C (Azure AD B2C) proporciona compatibilidad con la administración de usuarios de Microsoft Entra. En este artículo se describen los detalles para que un perfil técnico interactúe con un proveedor de notificaciones que admita este protocolo estandarizado.

Protocolo

El atributo Name del elemento Protocol tiene que establecerse en Proprietary. El atributo handler debe contener el nombre completo del ensamblado de controlador de protocolo Web.TPEngine.Providers.AzureActiveDirectoryProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

Siguiendo el paquete de inicio de directivas personalizadas, los perfiles técnicos de Microsoft Entra incluyen el perfil técnico AAD-Common. Los perfiles técnicos de Microsoft Entra no especifican el protocolo porque está configurado en el perfil técnico AAD-Common:

AAD-UserReadUsingAlternativeSecurityId y AAD-UserReadUsingAlternativeSecurityId-NoError: buscar una cuenta de redes sociales en el directorio.
AAD-UserWriteUsingAlternativeSecurityId: crear una cuenta de redes sociales.
AAD-UserReadUsingEmailAddress: buscar una cuenta local en el directorio.
AAD-UserWriteUsingLogonEmail: crear una cuenta local.
AAD-UserWritePasswordUsingObjectId: actualizar una contraseña de una cuenta local.
AAD-UserWriteProfileUsingObjectId: actualizar un perfil de usuario de una cuenta local o social.
AAD-UserReadUsingObjectId: leer un perfil de usuario de una cuenta local o social.
AAD-UserWritePhoneNumberUsingObjectId: escribir el número de teléfono de MFA de una cuenta local o social

En el ejemplo siguiente se muestra el perfil técnico 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

El elemento InputClaims contiene una notificación, que se usa para buscar una cuenta en el directorio o crear una nueva. Debe haber exactamente un elemento InputClaim en la colección de notificaciones de entrada para todos los perfiles técnicos de Microsoft Entra. Es posible que tenga que asignar el nombre de la notificación definida en la directiva al nombre definido en Microsoft Entra ID.

Para leer, actualizar o eliminar una cuenta de usuario existente, la notificación de entrada es una clave que identifica de forma única la cuenta en el directorio de Microsoft Entra. Por ejemplo, objectId, userPrincipalName, signInNames.emailAddress, signInNames.userName o alternativeSecurityId.

Para crear una nueva cuenta de usuario, la notificación de entrada es una clave que identifica de forma única una cuenta local o federada. Por ejemplo, cuenta local: signInNames.emailAddress o signInNames.userName. En el caso de una cuenta federada: alternativeSecurityId.

El elemento InputClaimsTransformations puede contener una colección de elementos de transformación de notificaciones de entrada que se usan para modificar las notificaciones de entrada o generar otras nuevas.

OutputClaims

El elemento OutputClaims contiene una lista de las notificaciones devueltas por el perfil técnico de Microsoft Entra. Es posible que tenga que asignar el nombre de la notificación definida en la directiva al nombre definido en Microsoft Entra ID. También puede incluir las notificaciones que Microsoft Entra no devuelve, siempre que establezca el atributo DefaultValue.

El elemento OutputClaimsTransformations puede contener una colección de elementos OutputClaimsTransformation que se usan para modificar las notificaciones de salida o para generar nuevas.

Por ejemplo, el perfil técnico AAD-UserWriteUsingLogonEmail crea una cuenta local y devuelve las notificaciones siguientes:

objectId, que es el identificador de la cuenta nueva
newUser, que indica si el usuario es nuevo
authenticationSource, que establece la autenticación en localAccountAuthentication
userPrincipalName, que es el nombre principal de usuario de la cuenta nueva
signInNames.emailAddress, que es el nombre de inicio de sesión de la cuenta, similar a la notificación de entrada email

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

PersistedClaims

El elemento PersistedClaims contiene todos los valores que Microsoft Entra ID debe conservar con la información de asignaciones posibles entre un tipo de notificación ya definido en la sección ClaimsSchema de la directiva y el nombre de atributo de Microsoft Entra.

El perfil técnico AAD-UserWriteUsingLogonEmail crea una cuenta local y conserva las notificaciones siguientes:

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

El nombre de la notificación es el del atributo de Microsoft Entra, a menos que se especifique el atributo PartnerClaimType, que contiene el nombre de atributo de Microsoft Entra.

Requisitos de una operación

Debe haber exactamente un elemento InputClaim en el contenedor de notificaciones para todos los perfiles técnicos de Microsoft Entra.
En el artículo sobre los atributos de perfil de usuario se describen los atributos del perfil de usuario de Azure AD B2C admitidos que puede usar en las notificaciones de entrada, las de salida y las persistentes.
Si la operación es Write o DeleteClaims, también debe aparecer en un elemento PersistedClaims.
El valor de la notificación userPrincipalName debe tener el formato user@tenant.onmicrosoft.com.
La notificación displayName es necesaria y no puede ser una cadena vacía.

Operaciones del perfil técnico de Microsoft Entra

Lectura

La operación Read lee los datos sobre una sola cuenta de usuario. El perfil técnico siguiente lee los datos sobre una cuenta de usuario mediante el valor objectId del usuario:

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

Escritura

La operación Write crea o actualiza una sola cuenta de usuario. El perfil técnico siguiente crea la cuenta de red 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

La operación DeleteClaims borra la información de una lista de notificaciones proporcionada. El perfil técnico siguiente elimina notificaciones:

<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

La operación DeleteClaimsPrincipal elimina una sola cuenta de usuario del directorio. El perfil técnico siguiente elimina una cuenta de usuario del directorio mediante el nombre principal de usuario:

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

El perfil técnico siguiente elimina una cuenta de usuario de red 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>

Metadatos

Atributo	Obligatorio	Descripción
Operación	Sí	La operación que se va a realizar. Valores posibles: `Read`, `Write`, `DeleteClaims` o `DeleteClaimsPrincipal`.
RaiseErrorIfClaimsPrincipalDoesNotExist	No	Genera un error si el objeto de usuario no existe en el directorio. Valores posibles: `true` o `false`.
RaiseErrorIfClaimsPrincipalAlreadyExists	No	Genera un error si el objeto de usuario ya existe. Valores posibles: `true` o `false`. Estos metadatos solo son aplicables a la operación de escritura.
ApplicationObjectId	No	El identificador de objeto de aplicación para los atributos de extensión. Valor: ObjectId de una aplicación. Para más información, consulte Atributos personalizados.
ClientId	No	El identificador de cliente para acceder al inquilino como un tercero. Para más información, vea Uso de los atributos personalizados en una directiva de edición de perfil personalizada.
IncludeClaimResolvingInClaimsHandling	No	En el caso de las notificaciones de entrada y salida, especifica si se incluye la resolución de notificaciones en el perfil técnico. Valores posibles: `true` o `false` (valor predeterminado). Si desea utilizar un solucionador de notificaciones en el perfil técnico, establézcalo en `true`.

Elementos de interfaz de usuario

La configuración siguiente se puede usar para establecer el mensaje de error que se muestra cuando se produce un error. Los metadatos se deben configurar en el perfil técnico autoafirmado. Los mensajes de error se pueden localizar.

Atributo	Obligatorio	Descripción
UserMessageIfClaimsPrincipalAlreadyExists	No	Si se va a generar un error (vea la descripción del atributo RaiseErrorIfClaimsPrincipalAlreadyExists), especifique el mensaje para mostrar al usuario si el objeto de usuario ya existe.
UserMessageIfClaimsPrincipalDoesNotExist	No	Si se va a generar un error (vea la descripción del atributo RaiseErrorIfClaimsPrincipalDoesNotExist), especifique el mensaje para mostrar al usuario si el objeto de usuario no existe.

Pasos siguientes

Consulte el siguiente artículo para obtener un ejemplo de uso de un perfil técnico de Microsoft Entra:

Adición de notificaciones y personalización de la entrada del usuario mediante directivas personalizadas en Azure Active Directory B2C