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.comni 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é. 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.<hostname> |
idp-verify=<jeton base32 de 26 caractères> |
| CNAME | <hostname> |
<environment-slug>.<region>.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é.
É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. 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.