Benutzerdefinierte Domains

Standardmäßig stellt Auris gehostete Login-Seiten auf einer Subdomain wie ihr-tenant.accounts.altovar.net bereit. Benutzerdefinierte Domains ermöglichen es dir, diese durch deine eigene Domain zu ersetzen (z. B. auth.ihrUnternehmen.com), was ein vollständig gebrandetes Authentifizierungserlebnis bietet, bei dem Benutzer niemals die Auris-Domain sehen.

Dieser Leitfaden behandelt das Hinzufügen einer benutzerdefinierten Domain, die Durchführung der DNS-Verifizierung und die Konfiguration deiner SDKs zur Verwendung dieser Domain.

Was benutzerdefinierte Domains tun

Wenn du eine benutzerdefinierte Domain konfigurierst:

Die gehostete Login-Seite wird unter https://auth.ihrUnternehmen.com statt https://ihr-tenant.accounts.altovar.net bereitgestellt
OAuth2-Autorisierungs- und Token-Endpunkte verwenden deine Domain
OIDC-Discovery (.well-known/openid-configuration) wird unter deiner Domain aufgelöst
JWKS-Endpunkt zur Token-Verifizierung verwendet deine Domain
An Benutzer gesendete E-Mails (Magic Links, Verifizierung, Passwort-Reset) enthalten Links zu deiner Domain
SSL-Zertifikate werden automatisch über Let’s Encrypt provisioniert und erneuert

Deine Benutzer interagieren vollständig mit deiner Marke, ohne Hinweis darauf, dass Auris die Authentifizierung betreibt.

Benutzerdefinierte Domains sind auf den Pro- und Enterprise-Plänen verfügbar. Free-Plan-Tenants verwenden die standardmäßige ihr-tenant.accounts.altovar.net-Subdomain.

Voraussetzungen

Stelle vor der Einrichtung einer benutzerdefinierten Domain sicher, dass du hast:

Administratorzugriff auf deinen DNS-Anbieter (z. B. Cloudflare, Route 53, GoDaddy)
Eine für die Authentifizierung reservierte Subdomain (z. B. auth.ihrUnternehmen.com, login.ihrUnternehmen.com oder id.ihrUnternehmen.com)
Einen aktiven Auris-Tenant im Pro- oder Enterprise-Plan

Verwende nicht deine Root-/Apex-Domain (z. B. ihrUnternehmen.com) als benutzerdefinierte Domain. CNAME-Einträge können bei den meisten DNS-Anbietern nicht auf Apex-Domains gesetzt werden. Verwende immer eine Subdomain.

Schritt 1: Domain in der Console hinzufügen

Öffne die Auris-Console und navigiere zu Einstellungen → Benutzerdefinierte Domains
Klicke auf Domain hinzufügen
Gib deine Domain ein (z. B. auth.ihrUnternehmen.com)
Klicke auf Hinzufügen

Auris generiert ein Verifizierungstoken und zeigt die DNS-Einträge an, die du erstellen musst. Der Domain-Status wird als Ausstehend angezeigt, bis die Verifizierung abgeschlossen ist.

Du kannst auch eine Domain über die API hinzufügen:


curl -X POST https://auth.ihredomain.com/api/custom-domains \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: ihr-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "auth.ihrUnternehmen.com"
  }'

Schritt 2: DNS konfigurieren

Auris unterstützt zwei Verifizierungsmethoden. Die Console zeigt die Methode und die exakten zu erstellenden Einträge an.

Methode A: CNAME-Verifizierung (Empfohlen)

Erstelle zwei DNS-Einträge bei deinem DNS-Anbieter:

Verifizierungseintrag:

Typ	Name	Wert
CNAME	`_auris-verify.auth.ihrUnternehmen.com`	`verify.accounts.altovar.net`

Traffic-Eintrag (nach Verifizierung erstellen):

Typ	Name	Wert
CNAME	`auth.ihrUnternehmen.com`	`ihr-tenant.accounts.altovar.net`

Methode B: TXT-Verifizierung

Falls dein DNS-Anbieter kein CNAME für die Verifizierungssubdomain unterstützt, verwende stattdessen einen TXT-Eintrag:

Typ	Name	Wert
TXT	`_auris-verify.auth.ihrUnternehmen.com`	`auris-verify-a1b2c3d4e5f6`

Schritt 3: Auf Verifizierung und SSL warten

Nach dem Erstellen der DNS-Einträge prüft Auris regelmäßig den Verifizierungseintrag (alle paar Minuten). Du kannst auch eine manuelle Prüfung auslösen:

In der Console gehe zu Einstellungen → Benutzerdefinierte Domains
Klicke auf die Prüfen-Schaltfläche neben deiner ausstehenden Domain

Sobald die DNS-Verifizierung besteht, ändert sich der Domain-Status auf Verifizierung und Auris beginnt mit der SSL-Provisionierung. Ein SSL-Zertifikat wird automatisch über Let’s Encrypt ausgestellt. Dies dauert typischerweise wenige Minuten.

Verifizierungs-Zeitplan

Phase	Dauer	Status
DNS-Propagation	1 Minute bis 48 Stunden (abhängig von TTL und Anbieter)	AUSSTEHEND
DNS-Verifizierung	Sofort nach Propagation	VERIFIZIERUNG
SSL-Provisionierung	1 bis 5 Minuten	AKTIV (sslStatus: AUSSTEHEND)
Vollständig betriebsbereit	Sofort nach SSL	AKTIV (sslStatus: AKTIV)

Schritt 4: Als primäre Domain festlegen

Wenn du mehrere benutzerdefinierte Domains hast (z. B. für verschiedene Marken oder Regionen), kannst du eine als primäre Domain festlegen. Die primäre Domain wird verwendet für:

E-Mail-Links (Magic Links, Verifizierung, Passwort-Reset)
Standard-iss-Claim in JWTs
OIDC-Discovery-Dokument

In der Console klicke auf die Als primär festlegen-Schaltfläche bei der gewünschten Domain.

Benutzerdefinierte Domains mit dem SDK verwenden

Sobald deine benutzerdefinierte Domain aktiv ist, aktualisiere den domain-Parameter in deiner SDK-Konfiguration:


import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({
  domain: 'auth.ihrUnternehmen.com', // deine benutzerdefinierte Domain
  clientId: 'ihr-client-id',
  redirectUri: 'https://app.ihrUnternehmen.com/callback',
})

Für React-Anwendungen:


import { AurisProvider } from '@auris/react'
 
function App() {
  return (
    <AurisProvider
      domain="auth.ihrUnternehmen.com"
      clientId="ihr-client-id"
      redirectUri="https://app.ihrUnternehmen.com/callback"
    >
      <MyApp />
    </AurisProvider>
  )
}

Für Next.js aktualisiere deine Umgebungsvariablen:


NEXT_PUBLIC_AURIS_DOMAIN=auth.ihrUnternehmen.com
NEXT_PUBLIC_AURIS_CLIENT_ID=ihr-client-id
AURIS_JWKS_URL=https://auth.ihrUnternehmen.com/.well-known/jwks.json

Branding-Konfiguration

Benutzerdefinierte Domains funktionieren zusammen mit den Branding-Einstellungen in der Console. Um das vollständige White-Label-Erlebnis abzuschließen:

Gehe zu Console → Branding
Lade dein Logo hoch (wird auf der gehosteten Login-Seite angezeigt)
Setze den Firmennamen (erscheint in Seitentiteln und E-Mail-Kopfzeilen)
Wähle eine Hintergrundfarbe oder verwende eine Voreinstellung
Lade optional ein Favicon für die Registerkarten der gehosteten Login-Seite hoch

Fehlerbehebung

DNS-Einträge nicht gefunden

Symptom: Domain bleibt nach Erstellen der DNS-Einträge im AUSSTEHEND-Status.

Häufige Ursachen:

Propagationsverzögerung. DNS-Änderungen können bis zu 48 Stunden dauern.
Falscher Eintragsname. Stelle sicher, dass der CNAME-Name genau _auris-verify.auth ist.
Proxy-Eintrag. Bei Cloudflare stelle sicher, dass der Verifizierungs-CNAME auf “Nur DNS” (graue Wolke) gesetzt ist, nicht auf “Proxied” (orange Wolke).

Überprüfe deine Einträge über die Befehlszeile:


# CNAME-Verifizierungseintrag prüfen
dig _auris-verify.auth.ihrUnternehmen.com CNAME +short
 
# Traffic-CNAME prüfen
dig auth.ihrUnternehmen.com CNAME +short

SSL-Zertifikat wird nicht provisioniert

Symptom: Domain ist AKTIV, aber SSL-Status bleibt AUSSTEHEND.

Stelle sicher, dass auth.ihrUnternehmen.com auf ihr-tenant.accounts.altovar.net zeigt. Falls deine Domain CAA-DNS-Einträge hat, stelle sicher, dass letsencrypt.org als erlaubte CA enthalten ist:


ihrUnternehmen.com.  IN  CAA  0 issue "letsencrypt.org"