Domaines personnalisés

Servez l'expérience de connexion sur votre propre domaine, avec preuve de propriété par TXT DNS, résolution du tenant par hôte et TLS automatique.

Un domaine personnalisé permet à vos utilisateurs de se connecter sur id.votremarque.com plutôt que sur accounts.obexal.com. Une fois le domaine vérifié, la page de connexion y est servie avec votre marque, et le tenant est résolu automatiquement depuis le Host de la requête : les flux pré-authentification sur votre domaine n'ont besoin d'aucun en-tête de tenant. La gestion des domaines exige la permission tenant:manage.

Comment ça marche

Trois mécanismes coopèrent, et chacun est conditionné à la vérification :

• Preuve de propriété : vous prouvez le contrôle du domaine en publiant un enregistrement DNS TXT contenant un jeton de défi.
• Résolution du tenant : seul un domaine vérifié résout vers votre tenant. Une entrée non vérifiée ne résout rien : ni thème, ni connexion, ni certificat.
• TLS automatique : le certificat est émis à la demande lors de la première visite HTTPS, et l'émission n'est autorisée que pour les domaines de tenant vérifiés.

Un domaine est unique à l'échelle de la plateforme : un domaine appartient à au plus un tenant. Enregistrer un domaine déjà pris renvoie 409.

Connecter votre domaine en quatre étapes

1. Déclarer le domaine

curl -X POST https://accounts.obexal.com/v1/admin/domains \
  -H "Authorization: Bearer $OBX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"id.votremarque.com"}'

{
  "domain": "id.votremarque.com",
  "verified": false,
  "createdAt": "2026-07-02T09:15:00Z",
  "dnsRecord": {
    "type": "TXT",
    "name": "_obexal-challenge.id.votremarque.com",
    "value": "k3J9x...jeton de défi..."
  }
}

2. Publier la preuve TXT

Chez votre fournisseur DNS, créez l'enregistrement TXT exactement tel que renvoyé : nom _obexal-challenge.id.votremarque.com, valeur = le jeton de défi. La propagation DNS peut prendre de quelques minutes à quelques heures selon le fournisseur.

3. Vérifier la propriété

curl -X POST https://accounts.obexal.com/v1/admin/domains/id.votremarque.com/verify \
  -H "Authorization: Bearer $OBX_TOKEN"
# {"verified":true}

Une réponse {"verified":false} signifie que l'enregistrement n'a pas encore été trouvé (propagation, faute de frappe) : corrigez et réessayez, l'appel se répète sans risque. La vérification est un contrôle ponctuel ; une fois vérifié, le domaine le reste.

4. Pointer le domaine vers Obexal

Créez l'enregistrement A/AAAA ou CNAME pour que id.votremarque.com résolve vers la plateforme Obexal. La première visite HTTPS déclenche alors l'émission du certificat, et la page de connexion est servie sur votre domaine.

TLS automatique, protégé contre les abus

Les certificats des domaines personnalisés sont émis à la demande, au premier handshake TLS pour l'hôte. Avant d'émettre, le reverse-proxy de la plateforme demande l'autorisation à l'API :

curl -i https://accounts.obexal.com/v1/tls/authorize?domain=id.votremarque.com
# 200 si id.votremarque.com est un domaine de tenant VÉRIFIÉ, 404 sinon

Seuls les domaines de tenant vérifiés obtiennent un 200. Sans ce garde-fou, n'importe qui pointant des hôtes arbitraires vers la plateforme pourrait épuiser les quotas de certificats ACME (un déni de service). L'endpoint n'est pas authentifié (il est appelé serveur à serveur par le proxy) mais ne révèle que l'existence de domaines déjà publiquement en service.

Seuls les domaines vérifiés résolvent

La résolution du tenant par hôte ne considère que les domaines vérifiés. C'est ce qui rend le mécanisme sûr : un attaquant qui déclare votre domaine dans son propre tenant, mais ne peut pas publier votre enregistrement DNS, n'obtient rien. C'est la vérification, pas la déclaration, qui active la connexion, le thème et le TLS.

Gérer vos domaines

# Lister (les domaines en attente incluent leur dnsRecord pour relire le défi)
curl https://accounts.obexal.com/v1/admin/domains \
  -H "Authorization: Bearer $OBX_TOKEN"

# Supprimer un domaine (idempotent)
curl -X DELETE https://accounts.obexal.com/v1/admin/domains/id.votremarque.com \
  -H "Authorization: Bearer $OBX_TOKEN"

Les ajouts, vérifications et suppressions de domaines sont inscrits au journal d'audit.