Login Ospitato (Authorization Code + PKCE)
Il modo più semplice e sicuro per autenticare gli utenti con Auris è utilizzare la Hosted Login Page — un’interfaccia utente di autenticazione completamente gestita, ospitata su Auris. Reindirizza gli utenti ad Auris per il login, ricevi un codice di autorizzazione nel callback, e scambialo con token tramite il flusso OAuth2 Authorization Code con PKCE.
Questo approccio ti evita di dover gestire form di login, password, flussi MFA o aggiornamenti di sicurezza: tutto è gestito da Auris.
Come Funziona
Il flusso Authorization Code + PKCE segue questi passaggi:
- La tua app genera un
code_verifiercasuale e il suocode_challenge(SHA-256) - Reindirizza l’utente all’endpoint di autorizzazione di Auris con il
code_challenge - L’utente effettua l’autenticazione su Auris (login, MFA, consenso)
- Auris reindirizza alla tua
redirect_uricon uncodemonouso - Il tuo backend scambia il
code+code_verifieroriginale con i token - Auris verifica il
code_verifiercontro ilcode_challengee restituisce access token, refresh token e ID token
Configurazione nella Console
Crea un’Applicazione
Vai su Console → Applicazioni → Nuova Applicazione. Scegli Web Application (SPA) o Regular Web Application (backend) in base alla tua architettura.
Configura gli URL di Callback
Nella scheda Impostazioni, aggiungi il tuo URL di callback alla lista degli URL di Redirect Autorizzati:
- Sviluppo:
http://localhost:3000/api/auth/callback - Produzione:
https://tuaapp.com/api/auth/callback
Configura i Logout URL
Aggiungi gli URL di logout autorizzati:
http://localhost:3000https://tuaapp.com
Copia le Credenziali
Copia il Client ID dalla scheda Credenziali. Le applicazioni SPA usano PKCE (nessun client secret necessario). Le app backend richiedono anche il Client Secret.
(Opzionale) Configura il Branding
Vai su Console → Impostazioni → Branding per personalizzare il logo, i colori e il testo della Hosted Login Page.
Implementazione
JavaScript
import { AurisClient } from '@auris/js'
const auris = new AurisClient({
domain: 'auth.tuodominio.com',
clientId: 'il-tuo-client-id',
redirectUri: 'http://localhost:3000/callback',
scopes: ['openid', 'profile', 'email'],
})
// Avvia il login — reindirizza alla Hosted Login Page
document.getElementById('login-btn').addEventListener('click', () => {
auris.loginWithRedirect()
})
// Nel tuo handler di callback (http://localhost:3000/callback)
const { tokens, user } = await auris.handleRedirectCallback()
console.log('Utente autenticato:', user)
console.log('Access token:', tokens.accessToken)Opzioni di Personalizzazione
Puoi passare parametri opzionali al reindirizzamento di login per controllare il comportamento della Hosted Login Page:
| Parametro | Tipo | Descrizione |
|---|---|---|
locale | string | Lingua della UI di login (es. it, en, fr) |
login_hint | string | Pre-popola il campo email con un indirizzo specifico |
prompt | string | login forza il re-login; none usa la sessione esistente senza interazione |
screen_hint | string | signup apre direttamente la schermata di registrazione |
connection | string | Salta la selezione del provider e usa direttamente una connessione specifica (es. google) |
auris.loginWithRedirect({
locale: 'it',
screen_hint: 'signup',
login_hint: '[email protected]',
})Gestione dei Token
Dopo un login riuscito, la tua app riceve:
| Token | Utilizzo |
|---|---|
| Access Token | Includi nell’header Authorization: Bearer per le chiamate API |
| ID Token | JWT con i claims dell’utente (nome, email, foto, ecc.) |
| Refresh Token | Ottieni nuovi access token senza richiedere un nuovo login |
Gli access token hanno una durata breve (di default 1 ora). Usa il refresh token per rinnovarli silenziosamente. Gli SDK Auris gestiscono il rinnovo automaticamente.
Variabili d’Ambiente
AURIS_DOMAIN=auth.tuodominio.com
AURIS_CLIENT_ID=il-tuo-client-id
AURIS_CLIENT_SECRET=il-tuo-client-secret # solo per le app backend
NEXT_PUBLIC_APP_URL=https://tuaapp.comConsiderazioni sulla Sicurezza
- PKCE è obbligatorio per le SPA: impedisce l’intercettazione del codice di autorizzazione
- La validazione dello
stateprotegge dagli attacchi CSRF — gli SDK Auris la gestiscono automaticamente - I redirect URI vengono validati rigorosamente — aggiungi tutti gli URL di produzione nella Console
- Non esporre mai il client secret nel codice frontend o in bundle pubblici
- Usa HTTPS per tutti gli URL di callback in produzione
Endpoint API
/api/oauth/authorizeEndpoint di autorizzazione OAuth2. Reindirizza l’utente alla Hosted Login Page. Accetta client_id, redirect_uri, response_type=code, scope, state e code_challenge.
/api/auth/tokenScambia un codice di autorizzazione con i token. Richiede grant_type=authorization_code, code, redirect_uri e code_verifier.
/api/auth/tokenRinnova l’access token. Imposta grant_type=refresh_token e refresh_token.
Guide Correlate
- Social Login — Aggiungi Google, GitHub e altri provider
- Magic Link — Login passwordless via email
- SMS OTP — Autenticazione via codice SMS
- Passkey / WebAuthn — Biometria e chiavi di sicurezza
- Enterprise SSO — SAML 2.0 e OIDC per le aziende
- Client Credentials M2M — Autenticazione machine-to-machine