API Domaines Personnalisés

Les Domaines Personnalisés te permettent de servir les pages de connexion hébergées par Auris et les flux OAuth sous ton domaine brandé (ex. auth.votredomaine.com) au lieu du domaine Auris par défaut. Cela offre une expérience white-label transparente dans laquelle tes utilisateurs ne voient jamais la marque Auris.

Le cycle de vie d’un domaine personnalisé suit ces étapes :

1. Ajouter le domaine via l’API
2. Configurer le DNS — ajoute l’enregistrement CNAME ou TXT fourni par Auris
3. Vérifier — Auris contrôle l’enregistrement DNS et provisionne un certificat SSL
4. Activer — définis le domaine comme domaine principal pour ton tenant

Une fois actif, tous les redirects OAuth, les pages de connexion hébergées, les liens dans les emails et les configurations SDK utilisent ton domaine personnalisé.

Tous les endpoints requièrent l’en-tête x-tenant et un token Bearer valide. La gestion des domaines personnalisés nécessite un accès de niveau administrateur.

Lister les Domaines Personnalisés

Réponse de succès

{
  "ok": true,
  "data": [
    {
      "id": "cd_abc123",
      "domain": "auth.acme-corp.com",
      "status": "ACTIVE",
      "sslStatus": "ACTIVE",
      "verificationMethod": "CNAME",
      "verificationToken": "auris-verify-abc123def456",
      "primaryDomain": true,
      "createdAt": "2025-01-15T10:00:00Z",
      "verifiedAt": "2025-01-15T10:45:00Z"
    },
    {
      "id": "cd_def456",
      "domain": "login.acme.io",
      "status": "PENDING",
      "sslStatus": "PENDING",
      "verificationMethod": "TXT",
      "verificationToken": "auris-verify-ghi789jkl012",
      "primaryDomain": false,
      "createdAt": "2025-02-10T08:00:00Z",
      "verifiedAt": null
    }
  ]
}

Cycle de Vie de l’État du Domaine

État SSL

Ajouter un Domaine Personnalisé

Corps de la requête

{
  "domain": "auth.acme-corp.com"
}

Réponse de succès

{
  "ok": true,
  "data": {
    "id": "cd_ghi789",
    "domain": "auth.acme-corp.com",
    "status": "PENDING",
    "sslStatus": "PENDING",
    "verificationMethod": "CNAME",
    "verificationToken": "auris-verify-mno345pqr678",
    "primaryDomain": false,
    "dnsRecord": {
      "type": "CNAME",
      "host": "auth.acme-corp.com",
      "value": "your-auris-domain.com"
    },
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Après avoir créé le domaine, ajoute l’enregistrement DNS affiché dans dnsRecord auprès de ton registrar de domaine. Le type d’enregistrement dépend de la configuration du domaine :

Vérification CNAME (pour les sous-domaines comme auth.acme-corp.com) :

CNAME auth.acme-corp.com → your-auris-domain.com

Vérification TXT (méthode alternative) :

TXT _auris-verify.auth.acme-corp.com → auris-verify-mno345pqr678

Une fois l’enregistrement DNS propagé, appelle l’endpoint de vérification.

Codes d’erreur

Vérifier un Domaine

Requête : aucun corps requis.

Réponse de succès — vérifié

{
  "ok": true,
  "data": {
    "id": "cd_ghi789",
    "domain": "auth.acme-corp.com",
    "status": "ACTIVE",
    "sslStatus": "PENDING",
    "verifiedAt": "2025-02-18T10:45:00Z"
  }
}

Après la vérification réussie, l’état SSL passe de PENDING à ACTIVE en quelques minutes lors du provisionnement du certificat.

Réponse de succès — pas encore propagé

{
  "ok": true,
  "data": {
    "id": "cd_ghi789",
    "domain": "auth.acme-corp.com",
    "status": "PENDING",
    "message": "DNS record not found yet. DNS propagation can take up to 48 hours."
  }
}

Réponse de succès — vérification échouée

{
  "ok": true,
  "data": {
    "id": "cd_ghi789",
    "domain": "auth.acme-corp.com",
    "status": "FAILED",
    "message": "CNAME record found but points to an incorrect target. Expected: your-auris-domain.com, Found: other-service.com"
  }
}

Codes d’erreur

Supprimer un Domaine Personnalisé

Réponse de succès

{
  "ok": true,
  "data": { "deleted": true }
}

Codes d’erreur

Définir le Domaine Principal

Définir un domaine comme principal fait en sorte que tous les URLs générés par Auris (base de redirection OAuth, liens email, issuer OIDC Discovery) utilisent ce domaine au lieu du domaine Auris par défaut.

Corps de la requête

{
  "primaryDomain": true
}

Réponse de succès

{
  "ok": true,
  "data": {
    "id": "cd_abc123",
    "domain": "auth.acme-corp.com",
    "primaryDomain": true,
    "updatedAt": "2025-02-18T12:00:00Z"
  }
}

Codes d’erreur

Comment Fonctionnent les Domaines Personnalisés

Lorsqu’un domaine personnalisé est défini comme principal, les comportements Auris suivants changent :

Méthodes de Vérification DNS

Auris supporte deux méthodes de vérification DNS :

Vérification CNAME (Recommandée)

Utilisée pour les sous-domaines. L’enregistrement CNAME a un double rôle — il vérifie la propriété et route le trafic vers Auris.

Type :  CNAME
Hôte :  auth.acme-corp.com
Valeur : your-auris-domain.com
TTL :   3600 (ou Auto)

Vérification TXT

Méthode alternative lorsque CNAME n’est pas adapté. Un enregistrement TXT séparé est ajouté sous le sous-domaine _auris-verify.

Type :  TXT
Hôte :  _auris-verify.auth.acme-corp.com
Valeur : auris-verify-mno345pqr678
TTL :   3600 (ou Auto)

Avec la vérification TXT, tu dois configurer séparément un enregistrement CNAME ou A pour router le trafic vers Auris.

Référence des Permissions

La gestion des domaines personnalisés est généralement réservée aux administrateurs du tenant. La permission est incluse dans le rôle admin par défaut.

Corrélés

• Guide des Domaines Personnalisés — Configuration et vérification du domaine étape par étape
• Domaines Personnalisés — Ajoute et vérifie des domaines depuis la Console