Configuration du domaine

Enregistrements DNS

Utilisez un sous-domaine que vous contrôlez, comme login.acme.ca pour une application en direct ou login-dev.acme.ca pour une application de test. Les domaines racines comme acme.ca ne sont pas acceptés : un CNAME ne peut pas se trouver à la racine. Créer une application renvoie dns_records, deux enregistrements à publier chez votre hébergeur DNS :

; At your DNS host, for login.acme.ca
_honkio-auth.login.acme.ca.  TXT    "honkio-auth=<the token from dns_records>"
login.acme.ca.               CNAME  edge.signin.honkio.ca.

Vérification

Une fois les enregistrements publiés, vérifiez. Le tableau de bord les vérifie en direct pendant que vous travaillez; l’API les vérifie à chaque appel et indique ceux qu’elle a trouvés :

curl -X POST https://api.honkio.ca/v1/auth-apps/APP_ID/domain/verify \
  -H "Authorization: Bearer mk_test_YOUR_KEY"
# → { "domain_status": "PENDING_CERT", "found": { "txt": true, "cname": true } }

Les changements DNS peuvent prendre un moment à se propager. Vérifiez aussi souvent que vous le voulez; rien n’est perdu pendant l’attente.

Certificat HTTPS

HonkIO sert le HTTPS sur votre nom d’hôte par Cloudflare for SaaS, qui émet et renouvelle le certificat : rien à téléverser ni à renouveler. Un certificat n’est demandé que pour un nom d’hôte dont la preuve TXT est vérifiée, jamais pour un nom d’hôte qui pointe simplement vers HonkIO. Si la configuration des certificats est brièvement indisponible, la vérification répond 503 AUTH_APP_DOMAIN_UNAVAILABLE; réessayez sous peu.

DNS mandaté par Cloudflare

Si votre DNS est chez Cloudflare avec le mandataire (le nuage orange) activé pour le nom d’hôte de connexion, une recherche publique montre les adresses de Cloudflare au lieu du CNAME. Ce n’est pas un problème : HonkIO détermine si le trafic l’atteint d’après le statut du nom d’hôte chez Cloudflare, et non d’après une recherche DNS publique. Les noms d’hôte mandatés sont donc vérifiés et restent actifs. L’enregistrement TXT n’est jamais mandaté.

Pour faire simple, réglez le nom d’hôte de connexion sur DNS seulement (le nuage gris).

Contrôles quotidiens

HonkIO vérifie chaque nom d’hôte tous les jours. Si le trafic n’atteint plus HonkIO, l’application passe à INACTIVE et vous recevez un courriel; la connexion ne peut de toute façon plus fonctionner. Si seul l’enregistrement TXT a disparu, HonkIO continue de servir la page, car arrêter bloquerait vos utilisateurs. Vous êtes averti chaque jour, et après 14 jours l’application est signalée au personnel de HonkIO pour examen. Remettez l’enregistrement TXT pour régler la situation.

Changer de nom d’hôte

Une application peut passer à un nouveau nom d’hôte sur place : elle garde ses utilisateurs, son ID client et son secret. Envoyez PATCH /v1/auth-apps/:id avec hostname seul. Le nouveau nom d’hôte attend dans pending_hostname avec son propre enregistrement TXT (la cible CNAME reste la même); publiez les deux, puis vérifiez avec POST /v1/auth-apps/:id/domain/verify. L’application continue de servir sur l’ancien nom d’hôte jusqu’à la bascule, qui a lieu une fois la preuve TXT réussie et le certificat émis.

• À la bascule, l’émetteur change avec le nom d’hôte : chaque session et chaque jeton d’actualisation prennent fin, et les jetons émis pour l’ancien nom d’hôte ne sont plus acceptés. Les utilisateurs se reconnectent.
• Les clés d’accès liées seulement à l’ancien nom d’hôte exact cessent de fonctionner (celles liées à votre domaine entier continuent de fonctionner). Si les clés d’accès devaient alors être la seule méthode de connexion activée, l’API refuse le changement avec AUTH_APP_HOSTNAME_CHANGE_NEEDS_FALLBACK : activez d’abord la connexion par courriel ou par texto.
• Annulez un changement en attente avec DELETE /v1/auth-apps/:id/hostname-change. Un changement dont le certificat n’est pas émis dans les 14 jours suivant la preuve est annulé pour vous, et vous recevez un courriel.
• Depuis le tableau de bord (Domaines), le changement de nom d’hôte demande d’abord de confirmer votre identité; depuis une session du tableau de bord, l’API répond AUTH_APP_STEP_UP_REQUIRED sans cette confirmation.

Règles

• Une application par nom d’hôte. Un nom d’hôte déjà prouvé par une autre application renvoie 409 AUTH_APP_HOSTNAME_TAKEN.
• Supprimer une application libère son nom d’hôte immédiatement et cesse de le servir. Rattacher ce nom d’hôte à une autre application exige une nouvelle preuve TXT : personne ne peut s’approprier un CNAME oublié qui pointe encore vers HonkIO.
• Les domaines racines, les domaines de HonkIO et les noms mal formés renvoient 422 AUTH_APP_HOSTNAME_INVALID.
• Comme la page de connexion est sur votre domaine, les témoins que votre site définit pour le domaine entier (Domain=.acme.ca) l’atteignent aussi. HonkIO ne lit, ne conserve et ne journalise aucun témoin autre que ses propres témoins __Host-hk_, et ses journaux de requêtes omettent entièrement l’en-tête Cookie. Les témoins de HonkIO sont limités à l’hôte : HonkIO ne définit jamais de témoin pour votre domaine.