Información general sobre las directivas personalizadas de Azure AD B2C

Las directivas personalizadas son archivos de configuración que definen el comportamiento del inquilino de Azure Active Directory B2C (Azure AD B2C). Mientras que en el portal de Azure AD B2C se predefinen flujos de usuario para las tareas de identidad más comunes, un desarrollador de identidad puede editar directivas personalizadas para realizar muchas tareas diferentes.

Una directiva personalizada es totalmente configurable y se controla mediante directivas. Una directiva personalizada orquesta la confianza entre entidades en protocolos estándar. Por ejemplo, OpenID Connect, OAuth, SAML y otros no estándar, como intercambios de notificaciones de sistema a sistema basados en la API REST. El marco crea experiencias propias fáciles de usar.

Una directiva personalizada se representa como uno o más archivos con formato XML que se hacen referencia entre sí en una cadena jerárquica. Los elementos XML definen los bloques de creación, la interacción con el usuario y otras entidades, y la lógica de negocios.

Paquete de inicio de directivas personalizadas

El paquete de inicio de directivas predeterminadas de Azure AD B2C viene con varias directivas predefinidas para que pueda empezar a trabajar rápidamente. Cada uno de estos paquetes de inicio contiene el menor número de perfiles técnicos y recorridos del usuario necesarios para lograr los escenarios descritos:

• LocalAccounts: habilita el uso solo de cuentas locales.
• SocialAccounts: habilita el uso solo de cuentas sociales (o federadas).
• SocialAndLocalAccounts: habilita el uso de cuentas locales y sociales. La mayoría de los ejemplos hacen referencia a esta directiva.
• SocialAndLocalAccountsWithMFA: habilita opciones sociales, locales y de autenticación multifactor.

En el repositorio de GitHub de ejemplos de Azure AD B2C, puede encontrar ejemplos de varios recorridos y escenarios del usuario de CIAM personalizados de Azure AD B2C. Por ejemplo, mejoras de directivas de cuentas locales, mejoras de directivas de cuentas sociales, mejoras de MFA, mejoras de la interfaz de usuario, mejoras genéricas, migración de aplicaciones, migración de usuarios, acceso condicional, prueba web y CI/CD.

Descripción de los conceptos básicos

Notificaciones

Una notificación proporciona un almacenamiento temporal de datos durante la ejecución de una directiva de Azure AD B2C. Las notificaciones son más similares a las variables en un lenguaje de programación. Puede almacenar información sobre el usuario, como el nombre, el apellido o cualquier otra notificación obtenida del usuario u otros sistemas (intercambios de notificaciones). El esquema de notificaciones es el lugar en el que se declaran las notificaciones.

Al ejecutarse la directiva, Azure AD B2C envía y recibe notificaciones de entidades internas y externas y, a continuación, envía un subconjunto de estas notificaciones a su aplicación de usuario de confianza como parte del token. Las notificaciones se utilizan de las siguientes maneras:

• Una notificación se guarda o se actualiza en el objeto de usuario de directorio.
• Se recibe una notificación de un proveedor de identidades externo.
• Las notificaciones se envían o reciben mediante un servicio de la API de REST personalizado.
• Los datos se recopilan como notificaciones del usuario durante los flujos de perfil de edición o registro.

Manipulación de las notificaciones

Las transformaciones de notificaciones son funciones predefinidas que se pueden usar para convertir una notificación especificada en otra, evaluar una notificación o establecer un valor de notificación. Por ejemplo, agregar un elemento a una colección de cadenas, cambiar las mayúsculas y minúsculas de una cadena o evaluar una notificación de fecha y hora. Una transformación de notificaciones especifica un método de transformación, que también está predefinido.

Personalización y localización de la interfaz de usuario

Para recopilar información de los usuarios presentando una página en su explorador web, use el perfil técnico autoafirmado. Puede editar el perfil técnico autoafirmado para agregar notificaciones y personalizar la entrada de usuario.

Para personalizar la interfaz de usuario para su perfil técnico autoafirmado, especifique una dirección URL en el elemento definición de contenido con contenido HTML personalizado. En el perfil técnico autoafirmado, apunte a este identificador de definición de contenido.

Para personalizar cadenas específicas del idioma, use el elemento Localization. Una definición de contenido puede contener una referencia Localization que especifique una lista de los recursos localizados que se van a cargar. Azure AD B2C combina elementos de la interfaz de usuario con el contenido HTML cargado desde la URL y, después, muestra la página al usuario.

Información general de la directiva del usuario de confianza

Una aplicación de usuario de confianza, que en el protocolo SAML se conoce como un proveedor de servicios, llama a la directiva del usuario de confianza para ejecutar un recorrido específico. La directiva del usuario de confianza especifica el recorrido del usuario que se va a ejecutar, así como la lista de notificaciones que incluye el token.

Todas las aplicaciones de usuario de confianza que usen la misma directiva, recibirán las mismas notificaciones de token y el usuario realizará el mismo recorrido del usuario.

Recorridos de usuario

Recorridos del usuario le permite definir la lógica de negocios con la ruta de acceso que sigue el usuario para obtener acceso a la aplicación. Se conduce al usuario por el recorrido del usuario para recuperar las notificaciones que se van a presentar a la aplicación. Un recorrido del usuario se genera a partir de una secuencia de pasos de orquestación. Un usuario debe llegar al último paso para adquirir un token.

En las siguientes instrucciones se explica cómo agregar pasos de orquestación a la directiva del paquete de inicio de la cuenta local y social. Este es un ejemplo de una llamada API REST que se ha agregado.

Estados de orquestación

El paso de orquestación hace referencia a un método que implementa su propósito o funcionalidad. Este método se denomina perfil técnico. Cuando el recorrido del usuario necesita una bifurcación para representar mejor la lógica de negocios, el paso de orquestación hace referencia a un subrecorrido. Un subrecorrido contiene su propio conjunto de pasos de orquestación.

Un usuario debe alcanzar el último paso de orquestación en el recorrido del usuario para adquirir un token. Sin embargo, es posible que los usuarios no necesiten seguir todos los pasos de orquestación. Los pasos de orquestación se pueden ejecutar de forma condicional en función de las condiciones previas definidas en el paso de orquestación.

Una vez que se completa un paso de orquestación, Azure AD B2C almacena las notificaciones generadas en el contenedor de notificaciones. Cualquier otro paso de orquestación puede usar las notificaciones del contenedor de notificaciones en el recorrido del usuario.

En el diagrama siguiente se muestra cómo los pasos de orquestación del recorrido del usuario pueden tener acceso al contenedor de notificaciones.

Perfil técnico

Un perfil técnico proporciona una interfaz para comunicarse con distintos tipos de entidades. Un recorrido del usuario combina la llamada a perfiles técnicos a través de los pasos de orquestación para definir la lógica de negocios.

Todos los tipos de perfiles técnicos comparten el mismo concepto. Puede enviar notificaciones de entrada, ejecutar la transformación de notificaciones y comunicarse con la entidad configurada. Una vez finalizado el proceso, el perfil técnico devuelve las notificaciones de salida al contenedor de notificaciones. Para obtener más información, vea la introducción a los perfiles técnicos.

Perfil técnico de validación

Cuando un usuario interactúa con la interfaz de usuario, es posible que desee validar los datos que se recopilan. Para interactuar con el usuario, debe usarse un perfil técnico autoafirmado.

Para validar la entrada de usuario, se llama a un perfil técnico de validación desde el perfil técnico autoafirmado. Un perfil técnico de validación es un método para llamar a cualquier perfil técnico no interactivo. En este caso, el perfil técnico puede devolver notificaciones de salida o un mensaje de error. El mensaje de error se representa para el usuario en la pantalla, lo que le permite volver a intentarlo.

En el siguiente diagrama se muestra cómo Azure AD B2C usa un perfil técnico de validación para validar las credenciales de usuario.

Modelo de herencia

Cada paquete de inicio incluye los siguientes archivos:

• Un archivo de base que contiene la mayoría de las definiciones. Para facilitar la solución de problemas y el mantenimiento a largo plazo de las directivas, intente minimizar el número de cambios realizados en este archivo.
• Un archivo de localización que contiene las cadenas de localización. Este archivo de directiva se basa en el archivo de base. Use este archivo para adaptarse a distintos idiomas para satisfacer las necesidades de los clientes.
• Un archivo de extensiones que contiene los cambios de configuración únicos del inquilino. Este archivo de directiva se basa en el archivo de localización. Use este archivo para agregar nuevas funciones o reemplazar funciones existentes. Por ejemplo, puede usar este archivo para federar con nuevos proveedores de identidades.
• Un archivo de usuario de confianza que es el único archivo centrado en tareas que invoca directamente la aplicación de usuario de confianza, como aplicaciones de escritorio, móviles o web. Cada tarea única (como un registro, un inicio de sesión o una edición de perfil) necesita su propio archivo de directiva de usuario de confianza. Este archivo de directiva se basa en el archivo de extensiones.

Este es el modelo de herencia:

• La directiva secundaria de cualquier nivel puede heredar de la directiva principal y extenderse mediante la adición de nuevos elementos.
• En escenarios más complejos, puede agregar más niveles de herencia (hasta 10 en total).
• Puede agregar más directivas del usuario de confianza. Por ejemplo, elimine mi cuenta, cambie un número de teléfono, una directiva del usuario de confianza de SAML y mucho más.

En el diagrama siguiente, se muestra la relación entre los archivos de directiva y las aplicaciones de usuario de confianza.

Guía y procedimientos recomendados

Procedimientos recomendados

En una directiva personalizada de Azure AD B2C puede integrar su propia lógica de negocios a fin de compilar las experiencias de usuario que requiere y extender la funcionalidad del servicio. Tenemos un conjunto de procedimientos recomendados y recomendaciones para comenzar.

• Cree la lógica en la directiva de extensión o la directiva del usuario de confianza. Puede agregar nuevos elementos, lo que invalida la directiva base haciendo referencia al mismo identificador. Este enfoque le permite escalar horizontalmente el proyecto mientras se facilita la actualización de la directiva base posteriormente si Microsoft lanza nuevos paquetes de inicio.
• En la directiva base, recomendamos encarecidamente evitar realizar cualquier tipo de cambio. En caso necesario, realice comentarios donde se hayan hecho los cambios.
• Al invalidar un elemento, como los metadatos del perfil técnico, evite copiar todo el perfil técnico de la directiva base. En su lugar, copie solo la sección necesaria del elemento. Consulte Deshabilitación de la comprobación de correo electrónico para ver un ejemplo de cómo hacer el cambio.
• Para reducir la duplicación de perfiles técnicos, donde se comparte la funcionalidad básica, use la inclusión del perfil técnico.
• Evite escribir en el directorio de Microsoft Entra durante el inicio de sesión, lo que puede provocar problemas de limitación.
• Si la directiva tiene dependencias externas, como API REST, asegúrese de que tengan alta disponibilidad.
• Para lograr una mejor experiencia de usuario, asegúrese de que las plantillas HTML personalizadas se implementan globalmente con la entrega de contenido en línea. Azure Content Delivery Network (CDN) permite reducir los tiempos de carga, ahorrar ancho de banda y mejorar la velocidad de respuesta.
• Si quiere realizar un cambio en un recorrido, copie todo el recorrido del usuario de la directiva base en la directiva de extensión. Proporcione un identificador de recorrido único al recorrido del usuario que ha copiado. A continuación, en la directiva del usuario de confianza, cambie el elemento del recorrido del usuario predeterminado para apuntar al nuevo recorrido del usuario.

Solución de problemas

Al llevar a cabo el desarrollo con las directivas de Azure AD B2C, es posible que se produzcan errores o excepciones al ejecutar el recorrido del usuario. Se pueden investigar mediante Application Insights.

• Integre Application Insights con Azure AD B2C para diagnosticar excepciones.
• La extensión Azure AD B2C para Visual Studio Code puede ayudar a acceder y visualizar los registros en función de una hora y un nombre de directiva.
• El error más común al configurar directivas personalizadas es el formato incorrecto del código XML. Use la validación del esquema XML para identificar los errores antes de cargar el archivo XML.

Integración continua

Mediante el uso de una canalización de integración y entrega continuas (CI/CD) configurada en Azure Pipelines, puede incluir las directivas personalizadas de Azure AD B2C en la entrega de software y la automatización del control de código. A medida que se implementan en diferentes entornos de Azure AD B2C, por ejemplo, en desarrollo, prueba y producción, se recomienda quitar los procesos manuales y realizar pruebas automatizadas con Azure Pipelines.

Preparación del entorno

Empiece a trabajar con la directiva personalizada de Azure AD B2C:

1. Creación de un inquilino de Azure AD B2C
2. Registro de una aplicación web mediante Azure Portal para poder probar la directiva.
3. Incorporación de las claves de directiva y Registro de las aplicaciones de Identity Experience Framework.
4. Obtenga el paquete de inicio de directivas de Azure AD B2C y cárguelo en el inquilino.
5. Después de cargar el paquete de inicio, realice una prueba de la directiva de registro o de inicio de sesión.
6. Le recomendamos que descargue e instale Visual Studio Code (VS Code). Visual Studio Code es un editor de código fuente ligero pero eficaz que se ejecuta en el escritorio y está disponible para Windows, macOS y Linux. Con VS Code puede desplazarse rápidamente por los archivos XML de directivas personalizadas de Azure AD B2C y editarlos si instala la extensión Azure AD B2C para VS Code

Pasos siguientes

Después de configurar y probar la directiva de Azure AD B2C, puede empezar a personalizar la directiva. Consulte los artículos siguientes para obtener información sobre cómo:

• Agregar notificaciones y personalizar la entrada de usuario mediante directivas personalizadas. Aprenda a definir una notificación y agregue una a la interfaz de usuario mediante la personalización de algunos de los perfiles técnicos del paquete de inicio.
• Personalizar la interfaz de usuario de la aplicación mediante una directiva personalizada. Aprenda a crear su propio contenido HTML y personalice la definición de contenido.
• Encontrar la interfaz de usuario de la aplicación mediante una directiva personalizada. Aprenda a configurar la lista de idiomas admitidos y proporcione etiquetas específicas del idioma agregando el elemento de recursos localizado.
• Durante el desarrollo y las pruebas de la directiva puede deshabilitar la comprobación del correo electrónico. Aprenda a sobrescribir los metadatos de un perfil técnico.
• Configurar el inicio de sesión con una cuenta de Google mediante directivas personalizadas. Aprenda a crear un nuevo proveedor de notificaciones con el perfil técnico de OAuth2. A continuación, personalice el recorrido del usuario para incluir la opción de inicio de sesión de Google.
• Para diagnosticar problemas con las directivas personalizadas, puede recopilar registros de Azure Active Directory B2C con Application Insights. Aprenda a agregar nuevos perfiles técnicos y configure la directiva del usuario de confianza.
• Si desea comprender cómo se compila la directiva personalizada desde cero, aprenda a Crear y ejecutar sus propias directivas personalizadas en la serie de guías paso a paso de Azure Active Directory B2C.