API Domini Personalizzati

I Domini Personalizzati ti consentono di servire le pagine di login ospitate da Auris e i flussi OAuth sotto il tuo dominio brandizzato (es. auth.tuodominio.com) invece del dominio Auris predefinito. Questo offre un’esperienza white-label senza soluzione di continuità in cui i tuoi utenti non vedono mai il brand Auris.

Il ciclo di vita di un dominio personalizzato segue questi passaggi:

1. Aggiungi il dominio tramite l’API
2. Configura il DNS — aggiungi il record CNAME o TXT fornito da Auris
3. Verifica — Auris controlla il record DNS e provisiona un certificato SSL
4. Attiva — imposta il dominio come dominio primario per il tuo tenant

Una volta attivo, tutti i redirect OAuth, le pagine di login ospitate, i link nelle email e le configurazioni SDK utilizzano il tuo dominio personalizzato.

Tutti gli endpoint richiedono l’intestazione x-tenant e un token Bearer valido. La gestione dei domini personalizzati richiede accesso a livello amministratore.

Elenca Domini Personalizzati

Risposta di successo

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

Ciclo di Vita dello Stato del Dominio

Stato SSL

Aggiungi un Dominio Personalizzato

Corpo della richiesta

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

Risposta di successo

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

Dopo aver creato il dominio, aggiungi il record DNS mostrato in dnsRecord presso il tuo registrar di dominio. Il tipo di record dipende dalla configurazione del dominio:

Verifica CNAME (per sottodomini come auth.acme-corp.com):

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

Verifica TXT (metodo alternativo):

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

Una volta propagato il record DNS, chiama l’endpoint di verifica.

Codici di errore

Verifica un Dominio

Richiesta: nessun corpo richiesto.

Risposta di successo — verificato

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

Dopo il successo della verifica, lo stato SSL passa da PENDING ad ACTIVE entro pochi minuti durante il provisioning del certificato.

Risposta di successo — non ancora propagato

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

Risposta di successo — verifica fallita

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

Codici di errore

Elimina un Dominio Personalizzato

Risposta di successo

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

Codici di errore

Imposta Dominio Primario

Impostare un dominio come primario fa sì che tutti gli URL generati da Auris (base redirect OAuth, link email, issuer OIDC Discovery) utilizzino questo dominio invece del dominio Auris predefinito.

Corpo della richiesta

{
  "primaryDomain": true
}

Risposta di successo

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

Codici di errore

Come Funzionano i Domini Personalizzati

Quando un dominio personalizzato viene impostato come primario, cambiano i seguenti comportamenti di Auris:

Metodi di Verifica DNS

Auris supporta due metodi di verifica DNS:

Verifica CNAME (Consigliata)

Usata per sottodomini. Il record CNAME svolge un duplice scopo — verifica la proprietà e instrada il traffico verso Auris.

Tipo:  CNAME
Host:  auth.acme-corp.com
Valore: your-auris-domain.com
TTL:   3600 (o Auto)

Verifica TXT

Metodo alternativo quando CNAME non è adatto. Un record TXT separato viene aggiunto sotto il sottodominio _auris-verify.

Tipo:  TXT
Host:  _auris-verify.auth.acme-corp.com
Valore: auris-verify-mno345pqr678
TTL:   3600 (o Auto)

Con la verifica TXT, è necessario configurare separatamente un record CNAME o A per instradare il traffico verso Auris.

Riferimento Permessi

La gestione dei domini personalizzati è tipicamente riservata agli amministratori del tenant. Il permesso è incluso nel ruolo admin predefinito.

Correlati

• Guida ai Domini Personalizzati — Configurazione e verifica passo-passo del dominio
• Domini Personalizzati — Aggiungi e verifica domini dalla Console