Varios dominios personalizados

Aprenda a configurar y administrar varios dominios personalizados dentro de un mismo inquilino de Auth0 para implementaciones multimarca y multirregión.

Dentro de Auth0, un dominio personalizado le permite unificar la experiencia de inicio de sesión con su propia marca y sus productos. La función de múltiples dominios personalizados le permite configurar varios dominios personalizados dentro de un único inquilino de Auth0. Esta función está disponible para clientes Enterprise tanto en implementaciones de Public Cloud como de Private Cloud.

​

Requisitos previos

Antes de comenzar con MCD, revise los siguientes requisitos:

• Su inquilino debe tener un plan Enterprise (implementaciones de Public Cloud o Private Cloud). Para obtener más información, consulte Manage Subscriptions.
• Su plan Enterprise incluye una asignación base de hasta 20 dominios personalizados por inquilino.
• Los dominios personalizados adicionales que superen la asignación base están disponibles mediante un SKU complementario. Póngase en contacto con el equipo de ventas de Auth0 para obtener más información.
• Debe poder demostrar la titularidad de los dominios personalizados configurados.

​

Configurar varios dominios personalizados

Puede agregar y administrar varios dominios personalizados para su inquilino con Auth0 Dashboard o con la Management API.

Auth0 Dashboard

Para crear un dominio personalizado en el Auth0 Dashboard:

1. Vaya a Auth0 Dashboard > Branding > Custom Domains.

2. Seleccione +Add custom domain.

3. En el formulario de configuración, proporcione la siguiente información:

   • Dominio: Un nombre de dominio completo de su propiedad. Por ejemplo: my.custom-domain.com.
   • Tipo de certificado: Elija Auth0-managed certificates o Self-managed certificates.
   • Metadatos (clave/valor): Añada metadatos opcionales como region, client_name o client_id para ayudar a organizar y filtrar sus dominios.

4. Una vez que haya configurado los detalles del dominio personalizado, seleccione Save.

El dominio recién añadido se mostrará como pending hasta que se complete la verificación.

​

Ver y administrar dominios

La página Custom Domains muestra todos los dominios configurados. Puede hacer lo siguiente:

• Buscar: Buscar dominios por nombre mediante el cuadro de búsqueda
• Filtrar: Filtrar dominios por estado de verificación, tipo de certificado o valores de metadatos
• Ordenar: Ordenar dominios por nombre, fecha de creación o estado de verificación
• Ver detalles: Haga clic en cualquier dominio para ver la configuración detallada, el estado de verificación y la información del certificado
• Establecer como predeterminado: Designar un dominio como el dominio predeterminado de su inquilino

Estas funciones le ayudan a administrar de forma eficiente un gran número de dominios personalizados en su inquilino.

Management API

Para crear un dominio personalizado con la Management API, necesitas una aplicación machine-to-machine (M2M) autorizada para usar la Management API. Para más información, consulta Tokens de acceso de la Management API.

1. Vaya a Dashboard > Applications > Applications y seleccione Crear aplicación.

2. Introduzca un nombre descriptivo para su aplicación y elija Machine to Machine Applications. A continuación, seleccione Create.

3. Cambie a la vista de APIs y luego active el interruptor de Auth0 Management API.

4. Expanda la fila para configurar los permisos de la API. Para MCD, debe seleccionar lo siguiente:

   • read:custom_domains
   • create:custom_domains
   • update:custom_domains
   • delete:custom_domains

5. Selecciona Update.

6. Vaya a la pestaña Configuración para recopilar su ID de cliente, Secreto del cliente y dominio.

7. Consulte Obtener tokens de acceso de Management API para obtener y almacenar su token de acceso.

​

Crear un dominio personalizado

Puede crear un nuevo dominio personalizado enviando una solicitud POST al endpoint /api/v2/custom-domains. Consulte el siguiente ejemplo para crear un nuevo dominio personalizado mediante el explorador de la Management API, usando las credenciales obtenidas anteriormente:

Si la operación se realiza correctamente, verás la siguiente respuesta con los detalles de tu nuevo dominio personalizado, incluido su estado de verificación. El status se devuelve inicialmente como pending.

{
    "custom_domain_id": "cd_abc123def456",
    "domain": "your.example-custom-domain.com",
    "primary": false,
    "status": "pending",
    "type": "auth0_managed_certs",
    "verification": {
        "methods": [
            {
                "name": "CNAME",
                "record": "yourtenant.auth0.com",
                "domain": "your.example-custom-domain.com"
            }
        ]
    },
    "tls_policy": "recommended",
    "domain_metadata": {
        "environment": "development"
    }
}

​

Características de MCD

MCD ofrece numerosas características y funcionalidades clave para administrar con mayor eficacia su implementación de Auth0 y mejorar la experiencia del usuario. Usted es responsable de adquirir y registrar los dominios personalizados que desee con un registrador de nombres de dominio.

La Auth0 Management API proporciona compatibilidad integral con las operaciones de crear, leer, actualizar, eliminar y verificar estos dominios personalizados, lo que le brinda un control programático total sobre su ciclo de vida.

MCD es compatible con los siguientes SDK de Management API de Auth0: Node.js, Go, Python, Java y .NET. Los SDK de autenticación funcionan automáticamente con dominios personalizados cuando se configuran en su aplicación.

​

Dominio predeterminado

Cuando hay varios dominios personalizados configurados, puedes designar uno como dominio predeterminado. El dominio predeterminado se utiliza cuando se necesita información del dominio para los endpoints de Auth0 Management API, pero no se especifica explícitamente un dominio personalizado mediante el encabezado auth0-custom-domain. Esta información se usa para personalizar las notificaciones por correo electrónico (por ejemplo, el restablecimiento de contraseña y la verificación del correo electrónico) con datos específicos del dominio.

Para establecer un dominio predeterminado:

1. Ve a Auth0 Dashboard > Branding > Custom Domains
2. Busca en la lista el dominio que quieres establecer como predeterminado
3. Haz clic en el botón Set as Default de ese dominio

También puedes establecer el dominio predeterminado con la Management API actualizando la configuración de un dominio personalizado. Una vez configurado, el dominio predeterminado se usará automáticamente para personalizar las comunicaciones por correo electrónico, a menos que se proporcione un dominio específico mediante el encabezado auth0-custom-domain.

El dominio predeterminado hace que el encabezado auth0-custom-domain sea opcional para los endpoints de Management API que desencadenan notificaciones. Si no especificas un dominio personalizado al llamar a estos endpoints, Auth0 usará automáticamente el dominio predeterminado para las personalizaciones de correo electrónico.

​

Verificación del dominio

El método para verificar la propiedad del nombre de dominio depende del tipo de gestión que haya elegido:

Tipo de dominio	Método de verificación	Detalles
Auth0-Managed	Registro DNS CNAME	Configure este registro para confirmar la propiedad del dominio y activarlo.
Self-Managed	Registro DNS TXT	Los detalles específicos del registro TXT se proporcionan en la respuesta de la API Create.

Una vez que Auth0 haya verificado su dominio personalizado, puede usarlo de inmediato para configurar las funcionalidades de Auth0 para sus usuarios. Para obtener más información, consulte Configure Features to Use Custom Domains.

​

Metadatos para una administración mejorada

Puede provisionar hasta 10 campos de metadatos por dominio personalizado para facilitar la organización y la personalización futura. En próximas versiones, estos campos de metadatos permitirán una personalización avanzada de las plantillas de correo electrónico, Universal Login y la lógica de autenticación.

​

Personaliza las plantillas de correo electrónico

Aprovecha la información de tu dominio personalizado para personalizar tus plantillas de correo electrónico y reforzar tu marca, lo que garantiza una experiencia de usuario coherente. Para ello, MCD proporciona la variable custom_domain.domain, que puedes usar en la sintaxis Liquid.

Por ejemplo, puedes establecer la Dirección del remitente de tu plantilla de correo electrónico como support@{{ custom_domain.domain }}, que se mostraría como [e-mail]. Esta variable está disponible en los campos Dirección del remitente, Asunto y Mensaje mediante la sintaxis Liquid. Para obtener más información, consulta Personalizar las plantillas de correo electrónico.

​

Personalice la gestión del correo electrónico con la Management API

Si configuró Multiple Custom Domains y habilitó Use Custom Domains in Emails, el encabezado HTTP auth0-custom-domain está disponible al usar la Management API de Auth0. El encabezado se pasa como valor del domain object en las plantillas de correo electrónico.

Los siguientes endpoints de la Management API aceptan el encabezado HTTP auth0-custom-domain:

• Enviar un correo de verificación de dirección de correo electrónico
• Crear un ticket de verificación de correo electrónico
• Crear invitaciones para una organización
• Crear un usuario
• Crear un ticket de inscripción en autenticación multifactor
• Crear un ticket de cambio de contraseña
• Actualizar un usuario

Por ejemplo: para crear un ticket de cambio de contraseña con el SDK de Auth0 para Node.js.

import { ManagementClient, CustomDomainHeader } from "auth0";

// Nivel de cliente: se aplica automáticamente a los endpoints en lista blanca
const auth0 = new ManagementClient({
    domain: '{yourDomain}',
    clientId: '{yourClientId}',
    clientSecret: '{yourClientSecret}',
    withCustomDomainHeader: 'my-custom-domain.com',});

(async () => {
    try {
        const ticket = await auth0.tickets.changePassword({
            user_id: 'auth0|abc123',
            result_url: 'https://example.com/success'
        });
        console.log('Password change ticket created:', ticket.data.ticket);
    } catch (err) {
        console.error('Error creating password change ticket:', err);
    }
})();

// Alternativamente, usar la anulación por solicitud
const reqOptions = {
    ...CustomDomainHeader('my-custom-domain.com'),
};
const ticket = await auth0.tickets.changePassword(
    { user_id: 'auth0|abc123', result_url: 'https://example.com/success' },
    reqOptions
);

Respuesta de ejemplo: el dominio personalizado se envía en el encabezado utilizado para generar la URL del ticket.

{
    "ticket": "https://my-custom-domain.com/u/reset-verify?ticket=abc123"
}

Mensajes de respuesta

Cuando incluyes el encabezado HTTP auth0-custom-domain, son posibles los siguientes tipos de respuesta adicionales:

Código de estado HTTP	Mensaje
409	El inquilino tiene varios dominios personalizados verificados.
400	El dominio personalizado no existe en el inquilino.
400	El encabezado HTTP auth0-custom-domain tiene un formato no válido.

Si habilitas MCD y usas el Auth0 Dashboard para configurar plantillas de correo electrónico, la función Try se ejecutará con tu dominio personalizado predeterminado en lugar del dominio estándar de Auth0.

​

Marcadores de posición de URL de la aplicación

Puede usar los metadatos de dominios personalizados como marcadores de posición dinámicos en las URL de la aplicación, como las URL de callback, las URL de cierre de sesión y el URI de inicio de sesión de la aplicación (initiate_login_uri). Esto permite que cada dominio personalizado se resuelva en una URL de aplicación distinta en tiempo de ejecución. Para obtener más información, consulte Marcadores de posición de URL de dominios personalizados.

​

Múltiples dominios personalizados con Actions

Las Actions de Auth0 le permiten crear lógica personalizada para gestionar distintas transacciones en función del dominio personalizado.

Por ejemplo, podría crear una Action que dirija a un usuario a una Organización asociada o aplicar una política de control de acceso específica.

Para ello, las Actions de post-login incluyen el objeto event.custom_domain, que proporciona el dominio personalizado que se está utilizando para el flujo de autenticación.

​

Caso de uso: Restringir el acceso de un usuario a una Organización según el dominio personalizado

Almacene una lista de dominios permitidos y otra de dominios denegados (por ejemplo, allow_domains y deny_domains) en los metadatos de su Organización.

Cree una Action que:

1. Obtenga el dominio del usuario a través de la propiedad event.custom_domain?.domain
2. Compare ese dominio con ambas listas
3. Permita o deniegue el acceso del usuario según corresponda

exports.onExecutePostLogin = async (event, api) => {
    const customDomain = event?.custom_domain?.domain;
    
    console.log(`org ${event?.organization?.name} accessed from domain ${customDomain || event?.request?.hostname}`);

    if (event?.organization?.metadata?.deny_domains && event?.organization?.metadata?.allow_domains) {
        console.warn(`[WARNING] configuration issue. org ${event?.organization?.name} has both deny_domains and allow_domains`);
    }

    // Verificar solo deny (A) o allow (B), no ambos
    // (A) verifica la deny_list de la org
    const isDomainDenied = () =>
        (event?.organization?.metadata?.deny_domains ? event?.organization?.metadata?.deny_domains.split(',').map(d => d.trim()).includes(customDomain) : false);
        
    if (isDomainDenied()) {
        return api.access.deny(`access to org ${event?.organization?.name} not allowed on domain ${customDomain}`);
    }

    // (B) verifica la allow_list de la org
    const isDomainAllowed = () =>
        (event?.organization?.metadata?.allow_domains ? event?.organization?.metadata?.allow_domains.split(',').map(d => d.trim()).includes(customDomain) : false);
        
    if (!isDomainAllowed()) {
        return api.access.deny(`access to org ${event?.organization?.name} not allowed on domain ${customDomain}`);
    }
};

MCD proporciona acceso a los metadatos del dominio personalizado en Actions mediante el objeto event.custom_domain. Puede usar esta información, junto con los metadatos del dominio personalizado configurados en su inquilino, para implementar lógica específica del dominio en sus Actions.

​

Atributos de dominios personalizados

MCD proporciona los siguientes atributos relacionados con la verificación de dominios personalizados y la gestión de certificados SSL/TLS. Estos atributos ofrecen información detallada sobre el aprovisionamiento y el estado operativo de los dominios personalizados.

​

Atributos actualizados

Atributo	Descripción
status	Se ha agregado un nuevo valor de enumeración, failed, al atributo status. Este valor indica que el proceso de verificación del dominio personalizado ha encontrado un error y no se ha completado correctamente. Se añade a los valores compatibles existentes pending y ready.

​

Nuevos atributos

Los siguientes atributos solo se admiten para dominios administrados por Auth0:

Atributo	Descripción
verification.status	Estado del proceso de verificación del registro DNS. Los valores posibles son: verified, pending y failed.
verification.error_msg	Si verification.status indica un error, este atributo de cadena contendrá un mensaje de error legible que proporcionará contexto sobre el error de verificación.
verification.last_verified_at	Este atributo de marca de tiempo registra la fecha y hora de la última verificación correcta del dominio personalizado. El formato de esta marca de tiempo seguirá la norma ISO 8601.
certificate	Este objeto encapsula información relacionada con el certificado SSL/TLS asociado al dominio personalizado.
certificate.status	Este atributo indica el estado actual de aprovisionamiento del certificado SSL/TLS. Los valores posibles incluyen estados como provisioning, provisioned, provisioning_failed y renewing_failed.
certificate.error_msg	Si certificate.status es provisioning_failed o renewing_failed, este atributo de cadena proporcionará un mensaje de error claro que detallará el motivo del error.
certificate.certificate_authority	Este atributo de cadena especifica la autoridad de certificación que emitió el certificado SSL/TLS para el dominio personalizado.
certificate.renews_before	Para los dominios personalizados administrados por Auth0, este nuevo atributo de marca de tiempo indica la fecha y hora antes de la cual debe renovarse el certificado SSL/TLS. El formato de esta marca de tiempo seguirá la norma ISO 8601.

​

Limitaciones

Las siguientes limitaciones se aplican a Multiple Custom Domains:

• WebAuthn/Passkeys:
  • Cada dominio personalizado mantiene su propia inscripción de claves de acceso. Una clave de acceso inscrita en un dominio queda vinculada a ese identificador de parte de confianza (RP ID) específico y no puede usarse en otros dominios.
  • Si un usuario inscribió una llave de seguridad externa en el Dominio A e intenta iniciar sesión mediante el Dominio B, la autenticación no fallará sin más. En su lugar, como los RP ID no coinciden, el sistema mostrará inmediatamente al usuario una nueva pantalla de inscripción.