Domini Personalizzati

Di default, Auris serve le pagine di login ospitate su un sottodominio come tuo-tenant.accounts.altovar.net. I domini personalizzati ti permettono di sostituirlo con il tuo dominio (es. auth.tuazienda.com), offrendo un’esperienza di autenticazione completamente branded in cui gli utenti non vedono mai il dominio Auris.

Questa guida copre l’aggiunta di un dominio personalizzato, il completamento della verifica DNS e la configurazione dei tuoi SDK per utilizzarlo.

Cosa Fanno i Domini Personalizzati

Quando configuri un dominio personalizzato:

La pagina di login ospitata viene servita su https://auth.tuazienda.com invece di https://tuo-tenant.accounts.altovar.net
Gli endpoint OAuth2 di autorizzazione e token usano il tuo dominio
OIDC Discovery (.well-known/openid-configuration) si risolve sotto il tuo dominio
L’endpoint JWKS per la verifica dei token usa il tuo dominio
Le email inviate agli utenti (magic link, verifica, reset password) contengono link al tuo dominio
I certificati SSL vengono automaticamente provisionati e rinnovati tramite Let’s Encrypt

I tuoi utenti interagiscono interamente con il tuo brand, senza alcuna indicazione che Auris alimenta l’autenticazione.

I domini personalizzati sono disponibili nei piani Pro e Enterprise. I tenant del piano Free usano il sottodominio predefinito tuo-tenant.accounts.altovar.net.

Prerequisiti

Prima di configurare un dominio personalizzato, assicurati di avere:

Accesso amministrativo al tuo provider DNS (es. Cloudflare, Route 53, GoDaddy)
Un sottodominio riservato per l’autenticazione (es. auth.tuazienda.com, login.tuazienda.com, o id.tuazienda.com)
Un tenant Auris attivo nel piano Pro o Enterprise

Non usare il tuo dominio radice/apex (es. tuazienda.com) come dominio personalizzato. I record CNAME non possono essere impostati su domini apex con la maggior parte dei provider DNS. Usa sempre un sottodominio.

Passaggio 1: Aggiungere il Dominio nella Console

Apri la Console Auris e naviga su Impostazioni poi Domini Personalizzati
Clicca Aggiungi Dominio
Inserisci il tuo dominio (es. auth.tuazienda.com)
Clicca Aggiungi

Auris genera un token di verifica e mostra i record DNS che devi creare. Lo stato del dominio sarà In Attesa fino al completamento della verifica.

Puoi anche aggiungere un dominio tramite API:


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

Risposta:


{
  "ok": true,
  "data": {
    "id": "cd_abc123",
    "domain": "auth.tuazienda.com",
    "status": "PENDING",
    "verificationMethod": "CNAME",
    "verificationToken": "auris-verify-a1b2c3d4e5f6",
    "sslStatus": "PENDING",
    "primaryDomain": false,
    "createdAt": "2026-01-15T10:00:00Z"
  }
}

Passaggio 2: Configurare il DNS

Auris supporta due metodi di verifica. La Console mostra il metodo e i record esatti da creare.

Metodo A: Verifica CNAME (Consigliato)

Crea due record DNS presso il tuo provider DNS:

Record di verifica:

Tipo	Nome	Valore
CNAME	`_auris-verify.auth.tuazienda.com`	`verify.accounts.altovar.net`

Record di traffico (da creare dopo la verifica):

Tipo	Nome	Valore
CNAME	`auth.tuazienda.com`	`tuo-tenant.accounts.altovar.net`

Metodo B: Verifica TXT

Se il tuo provider DNS non supporta CNAME sul sottodominio di verifica, usa un record TXT:

Tipo	Nome	Valore
TXT	`_auris-verify.auth.tuazienda.com`	`auris-verify-a1b2c3d4e5f6`

Poi crea il CNAME di traffico:

Tipo	Nome	Valore
CNAME	`auth.tuazienda.com`	`tuo-tenant.accounts.altovar.net`

Esempi di Provider DNS

Cloudflare:

Vai alle impostazioni DNS del tuo dominio
Clicca Aggiungi Record
Imposta Tipo su CNAME, Nome su _auris-verify.auth, e Target su verify.accounts.altovar.net
Disabilita la nuvola arancione proxy (imposta su DNS Only / nuvola grigia) per il record di verifica
Aggiungi il CNAME di traffico: Nome auth, Target tuo-tenant.accounts.altovar.net

AWS Route 53:

Apri la hosted zone per il tuo dominio
Clicca Crea Record
Nome record: _auris-verify.auth
Tipo record: CNAME
Valore: verify.accounts.altovar.net
TTL: 300

GoDaddy:

Vai su Gestione DNS per il tuo dominio
Clicca Aggiungi sotto la tabella dei record
Tipo: CNAME, Nome: _auris-verify.auth, Valore: verify.accounts.altovar.net, TTL: 600

Passaggio 3: Attendere la Verifica e l’SSL

Dopo aver creato i record DNS, Auris controlla periodicamente il record di verifica (ogni pochi minuti). Puoi anche attivare una verifica manuale:

Nella Console, vai su Impostazioni poi Domini Personalizzati
Clicca il pulsante Controlla accanto al dominio in attesa

O tramite API:


curl -X POST https://auth.tuodominio.com/api/custom-domains/cd_abc123/verify \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-tenant-id"

Una volta superata la verifica DNS, lo stato del dominio cambia in Verifica e Auris inizia il provisioning SSL. Un certificato SSL viene emesso automaticamente tramite Let’s Encrypt, in genere in pochi minuti.

Quando l’SSL è pronto, lo stato del dominio cambia in Attivo e lo stato SSL cambia in Attivo. Il tuo dominio personalizzato è ora completamente operativo.

Tempistica di Verifica

Fase	Durata	Stato
Propagazione DNS	Da 1 minuto a 48 ore (dipende da TTL e provider)	PENDING
Verifica DNS	Immediata una volta propagati i record	VERIFYING
Provisioning SSL	Da 1 a 5 minuti	ACTIVE (sslStatus: PENDING)
Completamente operativo	Immediato dopo SSL	ACTIVE (sslStatus: ACTIVE)

Passaggio 4: Impostare come Dominio Primario

Se hai più domini personalizzati (es. per brand o regioni diverse), puoi designarne uno come dominio primario. Il dominio primario viene usato in:

Link nelle email (magic link, verifica, reset password)
Claim iss predefinito nei JWT
Documento OIDC Discovery

Nella Console, clicca il pulsante Imposta come Primario sul dominio che vuoi usare come predefinito. O tramite API:


curl -X PATCH https://auth.tuodominio.com/api/custom-domains/cd_abc123 \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{ "primaryDomain": true }'

Usare i Domini Personalizzati con l’SDK

Una volta che il tuo dominio personalizzato è attivo, aggiorna il parametro domain nella configurazione del tuo SDK:


import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({
  domain: 'auth.tuazienda.com', // Il tuo dominio personalizzato
  clientId: 'tuo-client-id',
  redirectUri: 'https://app.tuazienda.com/callback',
})

Per applicazioni React:


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

Per Next.js, aggiorna le variabili d’ambiente:


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

L’endpoint OIDC Discovery è disponibile su:


https://auth.tuazienda.com/.well-known/openid-configuration

E l’endpoint JWKS su:


https://auth.tuazienda.com/.well-known/jwks.json

Configurazione del Branding

I domini personalizzati funzionano insieme alle impostazioni di branding nella Console. Per completare l’esperienza white-label:

Vai su Console poi Branding
Carica il tuo logo (mostrato sulla pagina di login ospitata)
Imposta il nome azienda (mostrato nei titoli delle pagine e nelle intestazioni delle email)
Scegli un colore di sfondo o usa un preset
Carica facoltativamente una favicon per i tab della pagina di login ospitata

Queste impostazioni di branding si applicano a tutte le pagine ospitate servite sul tuo dominio personalizzato.

Risoluzione dei Problemi

Record DNS Non Trovati

Sintomo: Il dominio rimane in stato PENDING dopo la creazione dei record DNS.

Cause comuni:

Ritardo di propagazione. Le modifiche DNS possono richiedere fino a 48 ore per propagarsi globalmente, sebbene la maggior parte dei provider propaghi in pochi minuti. Controlla la propagazione usando dnschecker.org .
Nome record errato. Assicurati che il nome CNAME sia esattamente _auris-verify.auth (non _auris-verify.auth.tuazienda.com — la maggior parte dei provider aggiunge automaticamente la zona).
Record proxiato. Se usi Cloudflare, assicurati che il CNAME di verifica sia impostato su “DNS Only” (nuvola grigia), non “Proxied” (nuvola arancione).
TTL troppo alto. Se il tuo record precedente per questo sottodominio aveva un TTL alto, il vecchio valore potrebbe essere in cache. Attendi la scadenza del vecchio TTL.

Verifica i tuoi record dalla riga di comando:


# Controlla il record CNAME di verifica
dig _auris-verify.auth.tuazienda.com CNAME +short
 
# Controlla il record TXT di verifica (se usi il metodo TXT)
dig _auris-verify.auth.tuazienda.com TXT +short
 
# Controlla il CNAME di traffico
dig auth.tuazienda.com CNAME +short

Certificato SSL Non in Provisioning

Sintomo: Il dominio è ACTIVE ma lo stato SSL rimane PENDING.

Cause comuni:

CNAME di traffico mancante. Il provisioner SSL necessita che il CNAME di traffico sia risolvibile prima di poter emettere un certificato. Assicurati che auth.tuazienda.com si risolva a tuo-tenant.accounts.altovar.net.
Record CAA che bloccano l’emissione. Se il tuo dominio ha record DNS CAA, assicurati che letsencrypt.org sia incluso come CA autorizzata:


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

Rinnovo del Certificato SSL

I certificati SSL vengono rinnovati automaticamente prima della scadenza. Non è richiesta alcuna azione. Se il rinnovo fallisce (es. il DNS è stato modificato), lo stato del dominio cambia in Attivo con stato SSL Scaduto. Correggi il DNS e Auris riproverà il rinnovo automaticamente.

Eliminare un Dominio Personalizzato

Per rimuovere un dominio personalizzato:


curl -X DELETE https://auth.tuodominio.com/api/custom-domains/cd_abc123 \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-tenant-id"

Dopo l’eliminazione, aggiorna la configurazione del tuo SDK per usare il dominio Auris predefinito o un altro dominio personalizzato. Ricorda di ripulire i record DNS presso il tuo provider.

Guide Correlate

Login Ospitato (PKCE) — Configurare il flusso Authorization Code OAuth2
Enterprise SSO — Federazione SAML e OIDC per clienti enterprise
Branding — Guida completa alla personalizzazione del branding