Benutzerdefinierte Domains API

Benutzerdefinierte Domains ermöglichen es dir, gehostete Auris-Login-Seiten und OAuth-Flows unter deiner eigenen Marken-Domain bereitzustellen (z. B. auth.ihredomain.com) anstelle der Standard-Auris-Domain. Dies bietet ein nahtloses White-Label-Erlebnis, bei dem deine Benutzer nie die Auris-Marke sehen.

Der Lebenszyklus einer benutzerdefinierten Domain umfasst folgende Schritte:

1. Hinzufügen der Domain über die API
2. DNS konfigurieren — den von Auris bereitgestellten CNAME- oder TXT-Eintrag hinzufügen
3. Verifizieren — Auris prüft den DNS-Eintrag und provisioniert ein SSL-Zertifikat
4. Aktivieren — die Domain als primäre Domain für deinen Tenant festlegen

Nach der Aktivierung verwenden alle OAuth-Weiterleitungen, gehostete Login-Seiten, E-Mail-Links und SDK-Konfigurationen deine benutzerdefinierte Domain.

Alle Endpunkte erfordern den x-tenant-Header und ein gültiges Bearer-Token. Die Verwaltung benutzerdefinierter Domains erfordert Administrator-Zugriff.

Benutzerdefinierte Domains auflisten

Erfolgsantwort

{
  "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
    }
  ]
}

Lebenszyklus des Domain-Status

SSL-Status

Benutzerdefinierte Domain hinzufügen

Anfrage-Body

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

Erfolgsantwort

{
  "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"
  }
}

Füge nach dem Erstellen der Domain den in dnsRecord angezeigten DNS-Eintrag bei deinem Domain-Registrar hinzu. Der Eintragstyp hängt von der Domain-Konfiguration ab:

CNAME-Verifizierung (für Subdomains wie auth.acme-corp.com):

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

TXT-Verifizierung (alternative Methode):

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

Sobald der DNS-Eintrag propagiert wurde, rufe den Verifizierungs-Endpunkt auf.

Fehlercodes

Domain verifizieren

Anfrage: Kein Body erforderlich.

Erfolgsantwort — verifiziert

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

Nach erfolgreicher Verifizierung wechselt der SSL-Status innerhalb weniger Minuten von PENDING zu ACTIVE, während das Zertifikat provisioniert wird.

Erfolgsantwort — noch nicht propagiert

{
  "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."
  }
}

Erfolgsantwort — Verifizierung fehlgeschlagen

{
  "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"
  }
}

Fehlercodes

Benutzerdefinierte Domain löschen

Erfolgsantwort

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

Fehlercodes

Primäre Domain festlegen

Das Festlegen einer Domain als primär bewirkt, dass alle von Auris generierten URLs (OAuth-Weiterleitungs-Basis, E-Mail-Links, OIDC-Discovery-Issuer) diese Domain anstelle der Standard-Auris-Domain verwenden.

Anfrage-Body

{
  "primaryDomain": true
}

Erfolgsantwort

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

Fehlercodes

Funktionsweise benutzerdefinierter Domains

Wenn eine benutzerdefinierte Domain als primär festgelegt wird, ändern sich folgende Auris-Verhaltensweisen:

DNS-Verifizierungsmethoden

Auris unterstützt zwei DNS-Verifizierungsmethoden:

CNAME-Verifizierung (empfohlen)

Wird für Subdomains verwendet. Der CNAME-Eintrag dient einem doppelten Zweck — er verifiziert den Besitz und leitet den Datenverkehr zu Auris weiter.

Typ:   CNAME
Host:  auth.acme-corp.com
Wert:  your-auris-domain.com
TTL:   3600 (oder Auto)

TXT-Verifizierung

Alternative Methode, wenn CNAME nicht geeignet ist. Ein separater TXT-Eintrag wird unter der _auris-verify-Subdomain hinzugefügt.

Typ:   TXT
Host:  _auris-verify.auth.acme-corp.com
Wert:  auris-verify-mno345pqr678
TTL:   3600 (oder Auto)

Bei der TXT-Verifizierung musst du außerdem separat einen CNAME- oder A-Eintrag konfigurieren, um den Datenverkehr zu Auris weiterzuleiten.

Berechtigungsreferenz

Die Verwaltung benutzerdefinierter Domains ist typischerweise auf Tenant-Administratoren beschränkt. Die Berechtigung ist in der Standard-admin-Rolle enthalten.

Verwandte Themen

• Leitfaden für benutzerdefinierte Domains — Schritt-für-Schritt-Anleitung zur Domain-Einrichtung und Verifizierung
• Benutzerdefinierte Domains — Domains über die Konsole hinzufügen und verifizieren