Domaines personnalisés multiples

Découvrez comment configurer et gérer plusieurs domaines personnalisés dans un même tenant Auth0 pour des déploiements visant plusieurs marques et régions.

Dans Auth0, un domaine personnalisé vous permet d’unifier l’expérience de connexion avec votre propre image de marque et vos produits. Domaines personnalisés multiples vous permet de configurer plusieurs domaines personnalisés dans un même tenant Auth0. Cette fonctionnalité est offerte aux clients Enterprise, tant dans les déploiements Public Cloud que Private Cloud.

​

Prérequis

Avant de commencer avec MCD, prenez connaissance des exigences ci-dessous :

• Votre tenant dispose d’un plan Enterprise (déploiements Public Cloud ou Private Cloud). Pour en savoir plus, consultez Gérer les abonnements.
• Votre plan Enterprise comprend une allocation de base pouvant aller jusqu’à 20 domaines personnalisés par tenant.
• Des domaines personnalisés supplémentaires au-delà de l’allocation de base sont offerts au moyen d’un SKU de module complémentaire. Veuillez communiquer avec l’équipe des ventes d’Auth0 pour en savoir plus.
• Vous devez être en mesure de prouver que vous êtes propriétaire des domaines personnalisés configurés.

​

Configurer Domaines personnalisés multiples

Vous pouvez ajouter et gérer plusieurs domaines personnalisés pour votre tenant à l’aide de l’Auth0 Dashboard ou de la Management API.

Auth0 Dashboard

Pour créer un domaine personnalisé dans l’Auth0 Dashboard :

1. Accédez à Auth0 Dashboard > Branding > Custom Domains.

2. Sélectionnez +Add custom domain.

3. Dans le formulaire de configuration, fournissez les renseignements suivants :

   • Domain : Un nom de domaine pleinement qualifié qui vous appartient. Par exemple : my.custom-domain.com.
   • Certificate type : Choisissez les certificats gérés par Auth0 ou les certificats autogérés.
   • Metadata (Key/Value) : Ajoutez des métadonnées facultatives comme region, client_name ou client_id pour vous aider à organiser et à filtrer vos domaines.

4. Une fois les détails du domaine personnalisé configurés, sélectionnez Save.

Le nom de domaine que vous venez d’ajouter s’affichera comme pending jusqu’à ce que la vérification soit terminée.

​

Afficher et gérer les domaines

La page Custom Domains affiche tous les domaines configurés. Vous pouvez :

• Search : Rechercher des domaines par nom à l’aide de la zone de recherche
• Filter : Filtrer les domaines selon l’état de vérification, le type de certificat ou les valeurs de métadonnées
• Sort : Trier les domaines par nom, date de création ou état de vérification
• View details : Cliquer sur n’importe quel domaine pour voir la configuration détaillée, l’état de vérification et les renseignements sur le certificat
• Set default : Désigner un domaine comme domaine par défaut pour votre tenant

Ces fonctionnalités vous aident à gérer efficacement un grand nombre de domaines personnalisés dans votre tenant.

Management API

Pour créer un domaine personnalisé avec l’API de gestion (Management API), vous avez besoin d’une application machine-à-machine (M2M) autorisée à utiliser l’API de gestion. Pour en savoir plus, consultez Management API Access Tokens.

1. Accédez à Dashboard > Applications > Applications et sélectionnez Create Application.

2. Saisissez un nom descriptif pour votre application et choisissez Machine to Machine Applications. Ensuite, sélectionnez Create.

3. Passez à la vue APIs, puis activez la bascule de l’Auth0 Management API.

4. Développez la ligne pour configurer les autorisations de l’API. Pour le MCD, vous devez sélectionner les éléments suivants :

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

5. Sélectionnez Update.

6. Accédez à l’onglet Paramètres pour noter votre Client ID, votre Client Secret et votre Domain.

7. Consultez Obtenir des jetons d’accès pour l’API de gestion pour récupérer et stocker votre jeton d’accès.

​

Créer un domaine personnalisé

Vous pouvez créer un nouveau domaine personnalisé en envoyant une requête POST à l’endpoint /api/v2/custom-domains. Consultez l’exemple ci‑dessous pour créer un nouveau domaine personnalisé à l’aide du Management API Explorer, en utilisant les identifiants récupérés ci‑dessus :

Si l’opération réussit, vous devriez voir les éléments suivants retournés avec les détails de votre nouveau domaine personnalisé, y compris son état de vérification. Le status est initialement retourné comme 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"
    }
}

​

Fonctionnalités de MCD

MCD offre de nombreuses fonctionnalités clés pour gérer plus efficacement votre mise en œuvre d’Auth0 et améliorer l’expérience utilisateur. Vous êtes responsable d’être propriétaire des domaines personnalisés souhaités et de les enregistrer auprès d’un registraire de noms de domaine.

L’Auth0 Management API offre une prise en charge complète des opérations Create, Read, Update, Delete, and Verify pour ces domaines personnalisés, ce qui vous donne un contrôle programmatique complet sur leur cycle de vie.

MCD est pris en charge par les Auth0 Management SDKs suivants : Node.js, Go, Python, Java et .NET. Les SDK d’authentication fonctionnent automatiquement avec les domaines personnalisés lorsqu’ils sont configurés dans votre application.

​

Domaine par défaut

Lorsque plusieurs domaines personnalisés sont configurés, vous pouvez désigner l’un d’eux comme domaine par défaut. Le domaine par défaut est utilisé lorsque des renseignements sur le domaine sont requis pour les points de terminaison de l’Auth0 Management API, mais qu’aucun domaine personnalisé n’est explicitement précisé au moyen de l’en-tête auth0-custom-domain. Ces renseignements servent à personnaliser les notifications par courriel (p. ex. les réinitialisations de mot de passe et la vérification de l’adresse courriel) en fonction du domaine.

Pour définir un domaine par défaut :

1. Accédez à Auth0 Dashboard > Branding > Custom Domains
2. Dans la liste, repérez le domaine que vous voulez définir comme domaine par défaut
3. Cliquez sur le bouton Set as Default pour ce domaine

Vous pouvez aussi définir le domaine par défaut à l’aide de la Management API en mettant à jour la configuration d’un domaine personnalisé. Une fois défini, le domaine par défaut sera automatiquement utilisé pour personnaliser les communications par courriel, sauf si un domaine précis est fourni au moyen de l’en-tête auth0-custom-domain.

Le domaine par défaut rend l’en-tête auth0-custom-domain facultatif pour les points de terminaison de la Management API qui déclenchent des notifications. Si vous ne précisez pas de domaine personnalisé lorsque vous effectuez une requête vers ces points de terminaison, Auth0 utilisera automatiquement le domaine par défaut pour personnaliser les courriels.

​

Vérification du domaine

La méthode de vérification de la propriété du nom de domaine dépend du type de gestion choisi :

Type de domaine	Méthode de vérification	Détails
Géré par Auth0	Enregistrement DNS CNAME	Configurez cet enregistrement pour confirmer la propriété du domaine et activer votre domaine.
Autogéré	Enregistrement DNS TXT	Les détails propres à l’enregistrement TXT sont fournis dans la réponse de l’API Create.

Une fois votre domaine personnalisé vérifié par Auth0, vous pouvez l’utiliser immédiatement pour configurer les fonctionnalités Auth0 pour vos utilisateurs. Pour en savoir plus, consultez Configurer les fonctionnalités pour utiliser des domaines personnalisés.

​

Métadonnées pour une gestion simplifiée

Vous pouvez configurer jusqu’à 10 champs de métadonnées par domaine personnalisé pour faciliter l’organisation et permettre une personnalisation ultérieure. Dans les prochaines versions, ces champs de métadonnées permettront de personnaliser davantage les modèles de courriel, Universal Login et la logique d’authentification.

​

Personnaliser les modèles de courriel

Tirez parti des renseignements sur votre domaine personnalisé pour personnaliser vos modèles de courriel et renforcer votre image de marque, afin d’assurer une expérience utilisateur cohérente. Pour ce faire, MCD met la variable custom_domain.domain à votre disposition dans la syntaxe Liquid.

Par exemple, vous pourriez définir le From Address de votre modèle de courriel à support@{{ custom_domain.domain }} , qui s’afficherait sous la forme [e-mail]. Cette variable est accessible dans la syntaxe Liquid des champs From Address, Subject et Message. Pour en savoir plus, consultez Personnaliser les modèles de courriel.

​

Personnaliser la gestion des courriels à l’aide de la Management API

Si vous avez configuré Domaines personnalisés multiples et activé Use Custom Domains in Emails, l’en-tête HTTP auth0-custom-domain est disponible lorsque vous utilisez l’Auth0 Management API. L’en-tête est transmis comme valeur de l’domain object dans les modèles de courriel.

Les points de terminaison de la Management API suivants acceptent l’en-tête HTTP auth0-custom-domain :

• Envoyer un courriel de vérification d’adresse courriel
• Créer un ticket de vérification du courriel
• Créer des invitations pour une organisation
• Créer un utilisateur
• Créer un ticket d’inscription à l’authentification multifacteur
• Créer un ticket de changement de mot de passe
• Mettre à jour un utilisateur

Par exemple : pour créer un ticket de changement de mot de passe à l’aide de l’Auth0 SDK pour Node.js.

import { ManagementClient, CustomDomainHeader } from "auth0";

// Niveau client : s'applique automatiquement aux endpoints sur liste blanche
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);
    }
})();

// Autrement, utilisez un remplacement par requête
const reqOptions = {
    ...CustomDomainHeader('my-custom-domain.com'),
};
const ticket = await auth0.tickets.changePassword(
    { user_id: 'auth0|abc123', result_url: 'https://example.com/success' },
    reqOptions
);

Exemple de réponse : Le domaine personnalisé est transmis dans l’en-tête servant à générer l’URL du ticket.

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

Messages de réponse

Lorsque vous incluez l’en-tête HTTP auth0-custom-domain, les réponses supplémentaires suivantes sont possibles :

code d’état HTTP	Message
409	Le tenant possède plusieurs domaines personnalisés vérifiés.
400	Le domaine personnalisé n’existe pas pour ce tenant.
400	L’en-tête HTTP auth0-custom-domain n’a pas un format valide.

Si vous activez MCD et utilisez le Auth0 Dashboard pour configurer des modèles de courriel, la fonction Try s’exécutera avec votre domaine personnalisé par défaut plutôt qu’avec le domaine Auth0 standard.

​

Variables de remplacement d’URL d’application

Vous pouvez utiliser les métadonnées de domaine personnalisé comme variables de remplacement dynamiques dans les URL d’application, comme les URL de rappel, les URL de déconnexion et l’Application Login URI (initiate_login_uri). Ainsi, chaque domaine personnalisé peut pointer vers une URL d’application différente à l’exécution. Pour en savoir plus, consultez Variables de remplacement d’URL de domaine personnalisé.

​

Domaines personnalisés multiples avec Actions

Les Actions d’Auth0 vous permettent de créer une logique personnalisée pour gérer vos différentes transactions en fonction du domaine personnalisé.

Par exemple, vous pourriez créer une Action qui dirige un utilisateur vers une Organisation associée, ou appliquer une politique de contrôle d’accès.

Pour ce faire, les Actions post-login incluent l’objet event.custom_domain, qui indique le domaine personnalisé utilisé pour le flux d’authentification.

​

Cas d’utilisation : restreindre l’accès d’un utilisateur à une Organisation en fonction du custom domain

Stockez une liste de domaines autorisés et une liste de domaines rejetés (par exemple, allow_domains et deny_domains) dans les métadonnées de votre Organisation.

Créez une Action qui :

1. Récupère le domaine de l’utilisateur à partir de la propriété event.custom_domain?.domain
2. Compare ce domaine aux deux listes
3. Autorise ou rejette l’accès de l’utilisateur en conséquence

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`);
    }

    // Vérifier soit rejeter (A) soit autoriser (B), mais pas les deux
    // (A) vérifie la liste de rejet de l'organisation
    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) vérifie la liste d'autorisation de l'organisation
    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 donne accès aux métadonnées du domaine personnalisé dans Actions par l’intermédiaire de l’objet event.custom_domain. Vous pouvez utiliser ces informations avec les métadonnées du domaine personnalisé configurées dans votre tenant afin d’implémenter une logique propre au domaine dans vos Actions.

​

Attributs des domaines personnalisés

MCD fournit les attributs suivants liés à la vérification des domaines personnalisés et à la gestion des certificats SSL/TLS. Ces attributs fournissent des renseignements détaillés sur l’état du provisionnement et du fonctionnement des domaines personnalisés.

​

Attributs mis à jour

Attribut	Description
status	Une nouvelle valeur d’énumération, failed, a été ajoutée à l’attribut status. Cette valeur indique que le processus de vérification du domaine personnalisé a rencontré une erreur et n’a pas abouti. Elle s’ajoute aux valeurs existantes pending et ready.

​

Nouveaux attributs

Les attributs suivants sont pris en charge uniquement pour les domaines gérés par Auth0 :

Attribut	Description
verification.status	Statut du processus de vérification de l’enregistrement DNS. Les valeurs possibles sont : verified, pending et failed.
verification.error_msg	Si verification.status indique un échec, cet attribut de type chaîne contiendra un message d’erreur compréhensible par l’humain fournissant du contexte sur l’échec de la vérification.
verification.last_verified_at	Cet attribut d’horodatage enregistre la date et l’heure de la dernière vérification réussie du domaine personnalisé. Le format de cet horodatage respecte la norme ISO 8601.
certificate	Cet objet regroupe les renseignements liés au certificat SSL/TLS associé au domaine personnalisé.
certificate.status	Cet attribut indique l’état actuel du provisionnement du certificat SSL/TLS. Les valeurs possibles comprennent notamment provisioning, provisioned, provisioning_failed et renewing_failed.
certificate.error_msg	Si certificate.status est provisioning_failed ou renewing_failed, cet attribut de type chaîne fournira un message d’erreur convivial détaillant la raison de l’échec.
certificate.certificate_authority	Cet attribut de type chaîne précise l’autorité de certification qui a délivré le certificat SSL/TLS pour le domaine personnalisé.
certificate.renews_before	Pour les domaines personnalisés gérés par Auth0, ce nouvel attribut d’horodatage indique la date et l’heure avant lesquelles le certificat SSL/TLS doit être renouvelé. Le format de cet horodatage respecte la norme ISO 8601.

​

Limitations

Les limitations suivantes s’appliquent à Domaines personnalisés multiples :

• WebAuthn/clés d’accès:
  • Chaque domaine personnalisé a son propre enrôlement de clé d’accès. Une clé d’accès enrôlée sur un domaine personnalisé est liée à ce Relying Party ID (RP ID) précis et ne peut pas être utilisée sur d’autres domaines.
  • Si un utilisateur a enrôlé une clé de sécurité itinérante sous le domaine A et tente de se connecter au moyen du domaine B, l’authentification n’échouera pas simplement. Comme les RP ID ne correspondent pas, le système affichera immédiatement à l’utilisateur un nouvel écran d’enrôlement.