# Configurare un dominio di accesso personalizzato Un dominio personalizzato come `login.acme.com` serve ogni superficie rivolta agli utenti finali del tuo ambiente: l'accesso ospitato, il portale account, l'Admin Portal, gli endpoint OIDC e OAuth, SSO, SAML e SCIM e i link nelle email. Il dominio della tua applicazione non è ospitato da KeenAuth. L'ambiente `development` non ha domini personalizzati. ## Prima di iniziare - Il nome deve avere almeno tre etichette (un sottodominio), perché un CNAME non può essere impostato alla radice di un dominio. - Viene convertito nella sua etichetta A IDNA2008 e portato in minuscolo. Non può essere `keenauth.app`, `keenauth.com` né un loro sottodominio, e non può essere un suffisso pubblico. - Un nome è unico sull'intera piattaforma. Un nome rilasciato resta in quarantena per 30 giorni prima che un altro account possa aggiungerlo. - Piano Free: un dominio, e l'account deve avere una carta di pagamento verificata. Più di un dominio per ambiente è una funzionalità Enterprise. - Ogni account può aggiungere al massimo 10 domini al giorno (UTC). Anche i tentativi respinti vengono conteggiati. ## Passaggio 1: aggiungi il dominio Chiama [Aggiungi un dominio personalizzato](/docs/api/management/custom-domains/create). Il dominio parte in `pending_dns` e la risposta elenca i record DNS da pubblicare. ## Passaggio 2: pubblica due record DNS | Tipo | Nome | Valore | |---|---|---| | TXT | `_akp-verify.` | `idp-verify=` | | CNAME | `` | `..edge.keenauth.app` | Mantieni il record TXT nel DNS in modo permanente, anche dopo che il dominio è attivo. È la prova della proprietà: se il dominio cambia mano, il precedente proprietario non può più far servire la pagina. Entrambi i record devono essere visibili. Il controllo viene eseguito ogni 5 minuti per 72 ore, poi ogni ora per 30 giorni. Per riavviare un controllo fermato, chiama [Verifica un dominio personalizzato](/docs/api/management/custom-domains/verify). ## Passaggio 3: controlla i record CAA Se il dominio o un dominio padre ha un record CAA, deve autorizzare entrambe le autorità di certificazione ACME che KeenAuth usa. Altrimenti il dominio torna in `pending_dns` con il motivo di errore `caa_blocked`, e la dashboard mostra la riga CAA esatta da aggiungere. Se non esiste alcun record CAA, non serve nulla. ## Certificato e ciclo di vita KeenAuth ottiene e rinnova il certificato TLS per te. Un certificato viene rinnovato quando restano meno di 30 giorni della sua durata. Se il rinnovo fallisce per 7 giorni, ricevi l'evento `custom_domain.certificate_renewal_failed` e un'email. La consegna degli eventi non è ancora disponibile; arriva con i webhook nella fase 6A. | Stato | Significato | Passo successivo | |---|---|---| | `pending_dns` | Aggiunto; in attesa dei record TXT e CNAME | Entrambi visti: `issuing` | | `issuing` | Il certificato è in emissione | Emesso: `active`. Blocco CAA: `pending_dns` con `caa_blocked`. Non emesso entro 72 ore: `pending_dns` con `certificate_failed` | | `active` | In servizio | Un controllo giornaliero fallito: `degraded` | | `degraded` | Il record TXT o CNAME manca da un giorno o più; il dominio continua a servire | Risolto: `active`. Non risolto per 7 giorni: `disabled` | | `disabled` | Fuori servizio; il certificato viene eliminato e le sessioni su questo host vengono invalidate | Riavvii con `:verify`: `pending_dns` | | `released` | Il dominio o l'ambiente è stato eliminato | Dopo 30 giorni di quarantena il nome può essere aggiunto di nuovo | Un dominio attivo viene controllato una volta ogni 24 ore. Iscriviti agli eventi `custom_domain.verified`, `custom_domain.activated`, `custom_domain.degraded` e `custom_domain.disabled` per essere avvisato quando qualcosa cambia. Questi eventi non sono ancora disponibili; la consegna arriva con i webhook e l'API degli eventi nella fase 6A. ## Dominio primario ed eliminazione Uno dei domini dell'ambiente è primario; i link nelle email lo usano. Cambialo con [Imposta un dominio personalizzato come primario](/docs/api/management/custom-domains/make-primary). Quando l'emittente dell'ambiente segue il dominio primario, cambiare il dominio primario cambia anche l'emittente, ed è un'operazione pianificata con almeno 7 giorni di anticipo. Un dominio primario, o il dominio che è l'emittente, non può essere eliminato (`409 custom_domain_in_use`). Scegli prima un altro dominio primario. Anche un dominio usato come rpId di una passkey non può essere eliminato né disattivato (`409 domain_in_use_by_rp_id`). ## Più domini in un ambiente Su Enterprise un ambiente può avere più domini verificati. Ogni dominio ha il proprio cookie di sessione, quindi non c'è SSO silenzioso tra domini. Le passkey tra domini dipendono dalla scelta dell'rpId e dall'elenco delle origini correlate, che contiene al massimo 5 etichette di dominio registrato e solo i domini `active` dello stesso ambiente. Ogni applicazione può avere un proprio branding su ogni dominio; vedi [Personalizza le pagine di accesso](/docs/guides/branding).