Configurer des fonctionnalités pour utiliser des Domaines personnalisés

Pour configurer les fonctionnalités Auth0 afin qu’elles utilisent votre domaine personnalisé, vous devrez peut-être suivre des étapes supplémentaires en fonction des fonctions que vous utilisez. Par exemple, vous devrez peut-être apporter des modifications avant de pouvoir utiliser votre domaine personnalisé sur votre page de connexion ou pour appeler vos API.

Si vous utilisez Auth0 depuis un certain temps et que vous décidez d’activer un domaine personnalisé, vous devrez migrer vos applications existantes et mettre à jour les paramètres comme décrit ci-dessous, y compris pour tout VPN ou pare-feu que vous utilisez. Notez que les sessions existantes créées à {yourDomain} ne seront plus valides une fois que vous commencerez à utiliser votre domaine personnalisé, de sorte que les utilisateurs devront se connecter à nouveau.

Vous devriez avoir déjà configuré et vérifié votre domaine personnalisé.

Si vous utilisez Connexion universelle Auth0. et que vous avez personnalisé la page de connexion, vous devez mettre à jour le code pour utiliser votre domaine personnalisé. Si vous utilisez la page de connexion par défaut sans personnalisation, vous n’avez aucune modification à effectuer. Pour en savoir plus, consultez Connexion universelle Auth0.

Si vous utilisezLock pour le Web vous devez définir les options configurationBaseUrl et overrides comme indiqué dans l’exemple de script suivant :

var lock = new Auth0Lock(config.clientID, config.auth0Domain, {
  //code omitted for brevity
  configurationBaseUrl: config.clientConfigurationBaseUrl,
  overrides: {
  	__tenant: config.auth0Tenant,
  	__token_issuer: config.authorizationServer.issuer
  },
  //code omitted for brevity
});

Si vous utilisez Auth0.js sur la page de Connexion universelle, vous devez définir l’option overrides.

var webAuth = new auth0.WebAuth({
  clientID: config.clientID,
  domain: config.auth0Domain,
  //code omitted for brevity
  overrides: {
  	__tenant: config.auth0Tenant,
  	__token_issuer: config.authorizationServer.issuer
  },
  //code omitted for brevity
});

Dans la plupart des cas, les bibliothèques Auth0.js et Lock récupèrent le nom du locataire (nécessaire pour /usernamepassword/login) et l’émetteur (nécessaire pour la validation id_token) à partir du domaine. Cependant, si vous êtes un client Private Cloud qui utilise un proxy ou un nom de domaine personnalisé où le nom de domaine est différent du locataire/émetteur, vous pouvez utiliser __tenant et __token_issuer pour fournir vos valeurs uniques.

Si vous utilisez Lock pour le Web intégré dans votre application, vous devez mettre à jour le code pour utiliser votre domaine personnalisé lors de l’initialisation de Lock. Vous devrez également définir la valeur configurationBaseUrl sur le CDN approprié URL.

var lock = new Auth0Lock('{yourClientId}', '{yourCustomDomain}', {
  //code omitted for brevity
  configurationBaseUrl: 'https://cdn.us.auth0.com'
  //code omitted for brevity
});

L’URL CDN varie selon la région. Utilisez https://cdn.[us|eu|au|jp].auth0.com (au pour l’Australie, ca pour Canada, eu l’Europe, jp pour le Japon, uk pour Royaume-Uni, us pour les États-Unis).

Si vous utilisez la Trousse SDK Auth0 pour les applications à page unique (SPA), Auth0.js ou d’autres trousses SDK, vous devrez initialiser la trousse SDK en utilisant votre domaine personnalisé. Par exemple, si vous utilisez la trousse SDK Auth0.js, vous devez définir ce qui suit :

webAuth = new auth0.WebAuth({
  domain: '{yourCustomDomain}',
  clientID: '{yourClientId}'
});

Et pour la trousse SDK Auth0 pour les applications à page unique (SPA) :

const auth0 = await createAuth0Client({
  domain: '{yourCustomDomain}',
  client_id: '{yourClientId}'
});

Consultez la section API ci-dessous si vous utilisez un domaine personnalisé et avez également l’intention d’effectuer des actions avec Management API via Auth0.js.

Si vous souhaitez utiliser votre domaine personnalisé dans vos courriels Auth0, vous devez activer cette fonctionnalité.

1. Affichez Auth0 Dashboard > Image de marque > Domaines personnalisés.

2. Activez l’option Use Custom Domain in Emails (Utiliser le domaine personnalisé dans les courriels).

Si vous souhaitez utiliser votre domaine personnalisé avec des fournisseurs d’identité sociale (IdP), vous devez mettre à jour la liste des URI de redirection autorisés de votre IdP pour y inclure votre domaine personnalisé (tel que https://login.northwind.com/login/callback).

Vous ne pouvez pas utiliser Clés de développeur Auth0 avec des domaines personnalisés.

Si vous souhaitez utiliser votre domaine personnalisé avec les connexions Google Workspace, vous devez mettre à jour l’URI de redirection autorisée dans les Client Settings (Paramètres du client) OAuth. Dans la console de développement Google, accédez à Credentials (Identifiants), choisissez votre client OAuth dans la liste et une page de paramètres s’affichera avec l’ID client de l’application, le secret et d’autres champs. Dans le champ Authorized redirect URIs (URI de redirection autorisées), ajoutez une URL au format https://<YOUR-CUSTOM-DOMAIN>/login/callback qui inclut votre domaine personnalisé (tel que https://login.northwind.com/login/callback).

Les identifiants d’API (c’est-à-dire audience) ne changeront pas. Il s’agit d’une valeur constante pour chaque API et, bien qu’il soit conventionnel d’utiliser une URI, elle est totalement indépendante du domaine utilisé pour obtenir le jeton.

Auth0 émet des jetons avec la revendication iss du domaine que vous avez utilisé pour obtenir le jeton.

Continuez à utiliser votre nom de domaine de locataire par défaut (tel que https://{yourDomain}/userinfo et https://{yourDomain}/api/v2/) au lieu de votre domaine personnalisé lorsque vous spécifiez une audience. C’est le seul endroit où vous pouvez utiliser votre domaine de locataire par défaut.

Toutes les demandes (c’est-à-dire l’obtention du jeton et l’appel effectif de l’API) doivent utiliser le même domaine. Les jetons obtenus via un domaine personnalisé doivent être utilisés sur une API Auth0 utilisant le même domaine personnalisé.

Si vous utilisez un flux d’authentification avec votre domaine personnalisé pour demander des jetons d’accès afin d’accéder à Management API, vous devez également appeler le point de terminaison de Management API avec votre domaine personnalisé.

POST https://mycustomdomain.com/oauth/token
... // other parameters 
...
audience:https://defaulttenant.eu.auth0.com/api/v2/

Votre demande de jeton d’accès devrait ressembler à ce qui suit

GET https://mycustomdomain.com/api/v2/clients

Headers:
Authorization: Bearer <access_token>

Si vous utilisez Auth0 avec un domaine personnalisé pour émettre des jetons d’accès pour vos API, vous devez valider le ou les émetteurs de JWT par rapport à votre domaine personnalisé. Par exemple, si vous utilisez le logiciel médiateur/intergiciel express-jwt, vous devez effectuer le changement suivant :

app.use(jwt({
  issuer: 'https://<YOUR-CUSTOM-DOMAIN>/',
  //code omitted for brevity
}));

Pour utiliser votre domaine personnalisé avec des SAML Identity Providers (Fournisseurs d’identité SAML) (IdP), vous devez mettre à jour votre Assertion Consumer Service (ACS) (Services de consommation d’assertions) URL(s) avec le ou les Identity Providers (Fournisseurs d’identité). En fonction de ce qui est pris en charge par l’IdP, vous pouvez procéder de l’une des deux manières suivantes :

1. Vous pouvez obtenir les métadonnées du fournisseur de services auprès d’Auth0 à https://<YOUR-CUSTOM-DOMAIN>/samlp/metadata?connection=<YOUR-CONNECTION-NAME>. Ceci inclura l’ACS mis à jour URL. Ensuite, vous devez mettre à jour manuellement cette valeur dans les paramètres de votre ou vos IdP. Cette modification de votre ou vos IdP doit être effectuée en même temps que vous commencez à utiliser votre domaine personnalisé dans vos applications. Cela peut poser un problème s’il y a plusieurs IdP à configurer.

2. Si pris en charge par l’IdP, vous pouvez utiliser des requêtes signées pour satisfaire cette exigence :

• Téléchargez le certificat de signature à partir de https://<TENANT>.auth0.com/pem. Notez que https://<YOUR-CUSTOM-DOMAIN>.com/pem renverra le même certificat.

• Remettez le certificat à l’IdP ou aux IdP pour qu’ils le téléchargent. Cela permet à l’IdP de valider la signature sur le message AuthnRequest qu’Auth0 envoie à l’IdP

• L’IdP importera le certificat et, si nécessaire, la vérification de la signature devra être activée (les étapes exactes varient selon l’IdP)

• Activez Sign Request (Requête de signature) dans le Tableau de bord sous Connections > Enterprise > SAML > CONNECTION. Cela déclenchera la signature par Auth0 des messages SAML AuthnRequest qu’il envoie à l’IdP.

Une fois cette étape terminée et que vous commencez à utiliser votre domaine personnalisé lorsque vous lancez une demande d’authentification dans votre application, l’IdP recevra ce domaine personnalisé dans votre demande signée. Étant donné que la requête signée de votre application est fiable, l’IdP devrait automatiquement remplacer la valeur configurée dans votre ACS URL par la valeur envoyée dans la requête signée. Cependant, certains IdP n’acceptent pas l’ACS URL dans la requête signée. Vous devez donc d’abord vérifier auprès du vôtre si cela est pris en charge ou pas.

Si c’est le cas, cela vous évitera d’avoir à modifier un ou plusieurs paramètres de l’IdP en même temps et vous permettra de les préparer à accepter vos requêtes signées à l’avance. Vous pouvez alors modifier l’ACS URL configuré de manière statique dans les paramètres de votre IdP à une date ultérieure.

Notez que si votre fournisseur d’identité SAML est configuré pour utiliser votre domaine personnalisé, tester la connexion via le bouton Try (Tester) dans le Tableau de bord ne fonctionnera pas et les liens par défaut pour télécharger les métadonnées depuis Auth0 afficheront toujours le domaine par défaut, et non le domaine personnalisé.

Si vous avez un flux d’authentification initié par l’IdP, vous devrez mettre à jour l’IdP ou les IdP et votre application (ou vos applications) en même temps pour utiliser le domaine personnalisé.

Si vous souhaitez utiliser votre domaine personnalisé avec des applications SAML (lorsque Auth0 est l’IdP), vous devez mettre à jour votre fournisseur de services avec les nouvelles métadonnées du fournisseur d’identité provenant d’Auth0. Vous pouvez obtenir les métadonnées mises à jour reflétant le domaine personnalisé à partir de https://<YOUR-CUSTOM-DOMAIN>/samlp/metadata/<YOUR-CLIENT-ID>. Notez que l’ID de l’entité émettrice pour l’assertion renvoyée par Auth0 changera lors de l’utilisation d’un domaine personnalisé (passant de quelque chose comme urn:northwind.auth0.com à un format avec le domaine personnalisé, tel que urn:login.northwind.com).

Si vous avez un flux d’authentification initié par l’IdP, vous devrez mettre à jour l’URL utilisée pour invoquer le flux d’authentification initié par l’IdP afin de refléter le domaine personnalisé. Au lieu de https://<TENANT>.auth0.com/samlp/<YOUR-CLIENT-ID>, vous devrez utiliser https://<YOUR-CUSTOM-DOMAIN>/samlp/<YOUR-CLIENT-ID>.

Si vous souhaitez utiliser votre domaine personnalisé avec des applications WS-Fed avec Auth0 comme IdP, vous devez mettre à jour votre Service Provider (Fournisseur de services) avec les nouvelles métadonnées du fournisseur d’identité provenant d’Auth0. Vous pouvez obtenir les métadonnées reflétant le domaine personnalisé à partir de https://<YOUR-CUSTOM-DOMAIN>/wsfed/FederationMetadata/2007-06/FederationMetadata.xml.

Si vous souhaitez utiliser votre domaine personnalisé avec les connexions Azure AD, vous devez mettre à jour l’URL Allowed Reply (Réponse autorisée) dans vos paramètres Azure AD. Dans votre Azure Active Directory, accédez à Apps registrations (Enregistrements d’applications) et sélectionnez votre application. Cliquez ensuite sur Paramètres -> URL de redirection et ajoutez une URL avec votre domaine personnalisé au format https://<YOUR-CUSTOM-DOMAIN>/login/callback (tel que https://login.northwind.com/login/callback).

Si vous souhaitez utiliser votre domaine personnalisé avec les connexions ADFS, vous devez mettre à jour le point de terminaison dans vos paramètres ADFS. Celui-ci devra être mis à jour pour utiliser votre domaine personnalisé dans l’URL de rappel au format https://<YOUR-CUSTOM-DOMAIN>/login/callback (tel que https://login.northwind.com/login/callback).

Si vous n’avez pas besoin de la prise en charge de Kerberos, les connexions AD/LDAP ne nécessitent pas de configuration supplémentaire.

Pour utiliser les connexions AD/LDAP avec la prise en charge de Kerberos, vous devrez mettre à jour le point de terminaison Ticket pour qu’il fonctionne avec le domaine personnalisé. Comme indiqué dans la documentation du connecteur AD/LDAP d’Auth0, le fichier config.json doit être modifié, avec la valeur PROVISIONING_TICKET changée pour utiliser votre domaine personnalisé au format https://<YOUR-CUSTOM-DOMAIN>/p/ad/jUG0dN0R.

Une fois cette modification enregistrée, vous devez redémarrer le service AD/LDAP Connector pour qu’elle prenne effet.

• Configurer des domaines personnalisés avec des certificats gérés par Auth0
• Configurer des domaines personnalisés avec des certificats autogérés
• Dépanner les domaines personnalisés
• Vérifier les appels d’API
• Dépanner des configurations SAML