# Configurer un domaine de connexion personnalisé Un domaine personnalisé tel que `login.acme.com` sert chaque surface destinée aux utilisateurs finaux de votre environnement : la connexion hébergée, le portail de compte, l'Admin Portal, les points de terminaison OIDC et OAuth, SSO, SAML et SCIM, ainsi que les liens figurant dans les e-mails. Le domaine de votre propre application n'est pas hébergé par KeenAuth. L'environnement `development` n'a pas de domaine personnalisé. ## Avant de commencer - Le nom doit comporter au moins trois étiquettes (un sous-domaine), car un CNAME ne peut pas être défini à la racine d'un domaine. - Il est converti en son étiquette A IDNA2008 et mis en minuscules. Il ne peut pas être `keenauth.app`, `keenauth.com` ni un sous-domaine de ces derniers, et il ne peut pas être un suffixe public. - Un nom est unique sur toute la plateforme. Un nom libéré est placé en quarantaine pendant 30 jours avant qu'un autre compte puisse l'ajouter. - Plan Free : un domaine, et le compte doit disposer d'une carte de paiement vérifiée. Plus d'un domaine par environnement est une fonctionnalité Enterprise. - Chaque compte peut ajouter au plus 10 domaines par jour (UTC). Les tentatives rejetées sont aussi comptées. ## Étape 1 : ajouter le domaine Appelez [Ajouter un domaine personnalisé](/docs/api/management/custom-domains/create). Le domaine commence à `pending_dns` et la réponse liste les enregistrements DNS à publier. ## Étape 2 : publier deux enregistrements DNS | Type | Nom | Valeur | |---|---|---| | TXT | `_akp-verify.` | `idp-verify=` | | CNAME | `` | `..edge.keenauth.app` | Conservez l'enregistrement TXT dans le DNS de façon permanente, y compris après l'activation du domaine. C'est la preuve de propriété : si le domaine change de mains, l'ancien propriétaire ne peut plus faire servir la page. Les deux enregistrements doivent être visibles. La vérification s'exécute toutes les 5 minutes pendant 72 heures, puis toutes les heures pendant 30 jours. Pour relancer une vérification arrêtée, appelez [Vérifier un domaine personnalisé](/docs/api/management/custom-domains/verify). ## Étape 3 : vérifier les enregistrements CAA Si le domaine ou l'un de ses domaines parents possède un enregistrement CAA, celui-ci doit autoriser les deux autorités de certification ACME qu'utilise KeenAuth. Sinon, le domaine revient à `pending_dns` avec la raison d'échec `caa_blocked`, et le tableau de bord affiche la ligne CAA exacte à ajouter. Si aucun enregistrement CAA n'existe, rien n'est nécessaire. ## Certificat et cycle de vie KeenAuth obtient et renouvelle le certificat TLS à votre place. Un certificat est renouvelé lorsqu'il lui reste moins de 30 jours de validité. Si le renouvellement échoue pendant 7 jours, vous recevez l'événement `custom_domain.certificate_renewal_failed` ainsi qu'un e-mail. La livraison des événements n'est pas encore disponible ; elle arrive avec les webhooks en phase 6A. | Statut | Signification | Étape suivante | |---|---|---| | `pending_dns` | Ajouté ; en attente des enregistrements TXT et CNAME | Les deux sont vus : `issuing` | | `issuing` | Le certificat est en cours d'émission | Émis : `active`. Blocage CAA : `pending_dns` avec `caa_blocked`. Non émis sous 72 heures : `pending_dns` avec `certificate_failed` | | `active` | En service | Une vérification quotidienne échoue : `degraded` | | `degraded` | L'enregistrement TXT ou CNAME manque depuis un jour ou plus ; le domaine reste servi | Corrigé : `active`. Non corrigé pendant 7 jours : `disabled` | | `disabled` | Hors service ; le certificat est supprimé et les sessions sur cet hôte sont invalidées | Vous le relancez avec `:verify` : `pending_dns` | | `released` | Le domaine ou l'environnement a été supprimé | Après 30 jours de quarantaine, le nom peut être de nouveau ajouté | Un domaine actif est vérifié une fois toutes les 24 heures. Abonnez-vous aux événements `custom_domain.verified`, `custom_domain.activated`, `custom_domain.degraded` et `custom_domain.disabled` pour être informé de tout changement. Ces événements ne sont pas encore disponibles ; leur livraison arrive avec les webhooks et l'API d'événements en phase 6A. ## Domaine principal et suppression Un domaine de l'environnement est principal ; les liens des e-mails l'utilisent. Modifiez-le avec [Définir un domaine personnalisé comme principal](/docs/api/management/custom-domains/make-primary). Lorsque l'émetteur de l'environnement suit le domaine principal, changer de domaine principal modifie l'émetteur ; c'est une opération planifiée, programmée au moins 7 jours à l'avance. Un domaine principal, ou le domaine qui sert d'émetteur, ne peut pas être supprimé (`409 custom_domain_in_use`). Choisissez d'abord un autre domaine principal. Un domaine utilisé comme rpId de passkey ne peut pas non plus être supprimé ni désactivé (`409 domain_in_use_by_rp_id`). ## Plusieurs domaines dans un environnement Sur Enterprise, un environnement peut avoir plusieurs domaines vérifiés. Chaque domaine a son propre cookie de session ; il n'y a donc pas de SSO silencieux entre les domaines. Les passkeys entre domaines dépendent du choix du rpId et de la liste des origines associées, qui contient au plus 5 étiquettes de domaine enregistré et uniquement les domaines `active` du même environnement. Chaque application peut avoir sa propre identité visuelle sur chaque domaine ; voir [Personnaliser vos pages de connexion](/docs/guides/branding).