Plusieurs domaines personnalisés

Découvrez comment configurer et gérer plusieurs domaines personnalisés au sein d’un même locataire Auth0 pour des déploiements multimarques et multirégion.

Dans Auth0, un domaine personnalisé vous permet d’harmoniser l’expérience de connexion avec votre propre marque et vos produits. La fonctionnalité de domaines personnalisés multiples vous permet de configurer plusieurs domaines personnalisés dans un seul locataire Auth0. Cette fonctionnalité est offerte aux clients Enterprise, dans les déploiements Public Cloud comme Private Cloud.

​

Prérequis

Avant de commencer à utiliser MCD, consultez les exigences ci-dessous :

• Votre locataire est associé à un forfait Enterprise (déploiements Public Cloud ou Private Cloud). Pour en savoir plus, consultez Gérer les abonnements.
• Votre forfait Enterprise comprend une allocation de base pouvant aller jusqu’à 20 domaines personnalisés par locataire.
• Des domaines personnalisés additionnels au-delà de l’allocation de base sont offerts au moyen d’un SKU 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 plusieurs domaines personnalisés

Vous pouvez ajouter et gérer plusieurs domaines personnalisés pour votre locataire au moyen d’Auth0 Dashboard ou de la Management API.

Auth0 Dashboard

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

1. Accédez à Auth0 Dashboard > Image de marque > Domaines personnalisés.

2. Sélectionnez +Ajouter un domaine personnalisé.

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

   • Domaine : un nom de domaine pleinement qualifié dont vous êtes propriétaire. Par exemple : my.custom-domain.com.
   • Type de certificat : choisissez les certificats gérés par Auth0 ou les certificats autogérés.
   • Métadonnées (clé/valeur) : ajoutez des métadonnées facultatives comme region, client_name ou client_id pour vous aider à organiser et à filtrer vos domaines.

4. Après avoir configuré les détails du domaine personnalisé, sélectionnez Enregistrer.

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

​

Afficher et gérer les domaines

La page Domaines personnalisés affiche tous les domaines configurés. Vous pouvez :

• Rechercher : trouver des domaines par nom à l’aide de la zone de recherche
• Filtrer : filtrer les domaines par état de vérification, type de certificat ou valeurs de métadonnées
• Trier : trier les domaines par nom, date de création ou état de vérification
• Afficher les détails : cliquer sur n’importe quel domaine pour voir la configuration détaillée, l’état de vérification et les renseignements sur le certificat
• Définir par défaut : désigner un domaine comme domaine par défaut pour votre locataire

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

Management API

Pour créer un domaine personnalisé avec la Management API, vous avez besoin d’une application machine à machine (M2M) autorisée à utiliser la Management API. Pour plus d’informations, consultez Jetons d’accès de la Management API.

1. Accédez à Dashboard > Applications > Applications, puis 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 le bouton bascule de Auth0 Management API.

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

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

5. Cliquez sur Update.

6. Accédez à l’onglet Paramètres pour récupérer votre ID client, votre Secret client et votre Domaine.

7. Consultez Obtenir des jetons d’accès pour la Management API pour récupérer et enregistrer votre jeton d’accès.

​

Créer un domaine personnalisé

Vous pouvez créer un nouveau domaine personnalisé en envoyant une requête POST au point de terminaison /api/v2/custom-domains. Consultez l’exemple ci-dessous pour créer un nouveau domaine personnalisé à l’aide de l’explorateur Management API, en utilisant les informations d’identification obtenues précédemment :

Si l’opération réussit, vous devriez voir les informations suivantes avec les détails de votre nouveau domaine personnalisé, y compris son statut de vérification. Le status est d’abord 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 pour vous aider à gérer plus efficacement votre implémentation Auth0 et à améliorer l’expérience utilisateur. Vous devez détenir les domaines personnalisés souhaités et les enregistrer auprès d’un registraire de noms de domaine.

L’Auth0 Management API prend entièrement en charge les opérations de création, de lecture, de mise à jour, de suppression et de vérification pour ces domaines personnalisés, ce qui vous donne un contrôle total par programmation sur leur cycle de vie.

MCD est pris en charge par les SDK de gestion d’Auth0 suivants : Node.js, Go, Python, Java et .NET. Les SDK d’authentification 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 un domaine comme domaine par défaut. Le domaine par défaut est utilisé lorsque les informations de domaine sont requises pour les points de terminaison de l’Auth0 Management API, mais qu’aucun domaine personnalisé n’est explicitement indiqué au moyen de l’en-tête auth0-custom-domain. Ces informations servent à personnaliser les notifications par courriel (par ex. les réinitialisations de mot de passe et la vérification du courriel) selon les caractéristiques du domaine.

Pour définir un domaine par défaut :

1. Accédez à Auth0 Dashboard > Branding > Custom Domains
2. Repérez dans la liste 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 appelez ces points de terminaison, Auth0 utilisera automatiquement le domaine par défaut pour personnaliser les courriels.

​

Vérification du domaine

La méthode permettant de vérifier 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 précis de 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 d’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 améliorée

Vous pouvez ajouter jusqu’à 10 champs de métadonnées par domaine personnalisé pour faciliter l’organisation et les personnalisations futures. Dans les prochaines versions, ces champs de métadonnées offriront des options de personnalisation avancée pour les modèles de courriel, Universal Login et la logique d’authentification.

​

Personnaliser les modèles de courriel

Exploitez les informations de votre domaine personnalisé pour personnaliser vos modèles de courriel et les harmoniser à votre image de marque, afin d’offrir une expérience utilisateur cohérente. Pour ce faire, MCD met à votre disposition la variable custom_domain.domain à utiliser dans la syntaxe Liquid.

Par exemple, vous pouvez définir le champ From Address de votre modèle de courriel à support@{{ custom_domain.domain }} , qui s’affichera comme [e-mail]. Cette variable est accessible dans la syntaxe Liquid pour les champs From Address, Subject et Message. Pour en savoir plus, consultez Customize Email Templates.

​

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

Si vous avez configuré plusieurs domaines personnalisés et activé Utiliser des domaines personnalisés dans les courriels, l’en-tête HTTP auth0-custom-domain est disponible lorsque vous utilisez la Management API d’Auth0. L’en-tête est transmis comme valeur de l’objet domain object dans les modèles de courriel.

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

• Envoyer un courriel de vérification d’adresse de courriel
• Créer un ticket de vérification d’adresse de 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 du SDK Auth0 pour Node.js.

import { ManagementClient, CustomDomainHeader } from "auth0";

// Niveau application : s'applique automatiquement aux points de terminaison autorisés
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 le 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 fournissez l’en-tête HTTP auth0-custom-domain, les types de réponse supplémentaires suivants sont possibles :

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

Si vous activez MCD et utilisez l’Auth0 Dashboard pour configurer des modèles de courriel, la fonctionnalité Try s’exécutera à l’aide de votre domaine personnalisé par défaut plutôt que du domaine Auth0 standard.

​

Espaces réservés d’URL d’application

Vous pouvez utiliser les métadonnées de domaine personnalisé comme espaces réservés dynamiques dans les URL d’application, comme les URL de rappel, les URL de déconnexion et l’URI de connexion de l’application (initiate_login_uri). Cela permet à chaque domaine personnalisé de pointer vers une URL d’application différente au moment de l’exécution. Pour en savoir plus, consultez Espaces réservés d’URL de domaine personnalisé.

​

Plusieurs domaines personnalisés avec Actions

Les Actions d’Auth0 vous permettent de créer une logique personnalisée pour traiter différentes transactions selon le domaine personnalisé.

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

À cette fin, les Actions post-connexion 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 d’un domaine personnalisé

Stockez une liste de domaines autorisés et une liste de domaines refusé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 refuse 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 le refus (A) soit l'autorisation (B), pas les deux
    // (A) vérifie la liste de refus 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 au moyen de l’objet event.custom_domain. Vous pouvez utiliser ces informations, ainsi que les métadonnées du domaine personnalisé configurées dans votre locataire, pour mettre en œuvre 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 donnent une vue détaillée du provisionnement et de l’état opérationnel 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 prises en charge 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	État 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 qui fournit 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 informations liées 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 fournit un message d’erreur clair détaillant la raison de l’échec.
certificate.certificate_authority	Cet attribut de type chaîne précise l’autorité de certification qui a émis 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 laquelle le certificat SSL/TLS doit être renouvelé. Le format de cet horodatage respecte la norme ISO 8601.

​

Limitations

Les limitations suivantes s’appliquent à plusieurs domaines personnalisés :

• WebAuthn/Passkeys:
  • Chaque domaine personnalisé gère sa propre inscription de clés d’accès. Une clé d’accès inscrite sur un domaine personnalisé est liée à cet identifiant de tiers de confiance (RP ID) précis et ne peut pas être utilisée sur d’autres domaines.
  • Si un utilisateur a inscrit une clé de sécurité itinérante sur 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’inscription.