CIBA (Backchannel Authentication)
Il Client Initiated Backchannel Authentication (CIBA) è un’estensione OpenID Connect che consente a un’applicazione client di avviare l’autenticazione per conto di un utente senza richiedere che l’utente interagisca direttamente con il client. L’utente riceve invece una notifica (via SMS, email o push) su un dispositivo separato e lì approva o nega la richiesta.
Casi d’uso comuni:
- Un agente di call center autentica un cliente al telefono attivando un’approvazione sul dispositivo mobile del cliente
- Un terminale di pagamento richiede l’approvazione dal telefono del titolare del conto prima di elaborare una transazione di alto valore
- Un’applicazione desktop delega il login al telefono dell’utente per un’esperienza passwordless
- Un servizio backend avvia l’autenticazione step-up quando viene richiesta un’operazione sensibile
Come Funziona
CIBA disaccoppia il dispositivo da cui parte l’autenticazione dal dispositivo in cui l’utente fornisce il consenso:
- Il client invia una richiesta di autenticazione backchannel a
/api/oauth/cibacon unlogin_hint(email, numero di telefono o user ID) che identifica l’utente - Auris valida la richiesta e invia una notifica all’utente sul suo dispositivo o canale registrato
- L’utente vede i dettagli della richiesta (nome dell’applicazione, binding message) e approva o nega
- Il client riceve il risultato tramite una delle tre modalità: polling, ping (callback) o push
Modalità di Notifica
Auris supporta tre modalità per consegnare il risultato dell’autenticazione al client:
| Modalità | Come Funziona | Ideale Per |
|---|---|---|
| Poll | Il client fa polling sull’endpoint token a intervalli regolari finché l’utente risponde | Integrazioni semplici, client lato server |
| Ping | Auris invia una notifica a un callback URL pre-registrato, poi il client scambia l’auth request ID con un token | Architetture event-driven |
| Push | Auris consegna il token direttamente a un callback URL pre-registrato | Requisiti di bassa latenza |
La modalità Poll è la più semplice da implementare ed è consigliata per la maggior parte dei casi d’uso. Le modalità Ping e Push richiedono un callback URL pubblicamente accessibile e un’adeguata sicurezza del webhook.
Configurazione nella Console
Abilita CIBA
Nella Console Auris, vai su Applicazioni e seleziona la tua applicazione. Nella scheda Impostazioni, attiva Abilita CIBA.
Configura la Modalità di Notifica
Seleziona la modalità di notifica (Poll, Ping o Push). Per le modalità Ping e Push, fornisci un Callback URL dove Auris invierà le notifiche.
Imposta il Canale di Notifica
Scegli come gli utenti ricevono la notifica della richiesta di autenticazione:
| Canale | Requisiti |
|---|---|
| L’utente deve avere un indirizzo email verificato | |
| SMS | L’utente deve avere un numero di telefono verificato. Richiede la configurazione del provider SMS (Twilio). |
| Push | Richiede un’integrazione custom di push notification (avanzato) |
Configura la Durata della Richiesta
Imposta il tempo massimo in cui una richiesta CIBA rimane valida prima di scadere:
| Impostazione | Default | Note |
|---|---|---|
| Durata Richiesta | 300 secondi (5 minuti) | Tempo massimo che l’utente ha per approvare o negare |
| Intervallo Polling | 5 secondi | Intervallo minimo per i client in modalità poll |
Copia le Credenziali
CIBA richiede un client confidenziale. Copia il Client ID e il Client Secret dalla scheda Credenziali.
Implementazione
JavaScript (Modalità Poll)
const AURIS_DOMAIN = 'https://auth.tuodominio.com'
const CLIENT_ID = 'il-tuo-client-id'
const CLIENT_SECRET = 'il-tuo-client-secret'
// Passo 1: Avvia l'autenticazione backchannel
const cibaResponse = await fetch(`${AURIS_DOMAIN}/api/oauth/ciba`, {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'Authorization': `Basic ${btoa(`${CLIENT_ID}:${CLIENT_SECRET}`)}`,
},
body: new URLSearchParams({
scope: 'openid profile',
login_hint: '[email protected]',
binding_message: 'Approva l\'accesso alla Dashboard',
}),
}).then(r => r.json())
console.log('Auth request ID:', cibaResponse.auth_req_id)
console.log('L\'utente riceverà una notifica...')
// Passo 2: Fai polling per il token
const token = await pollForCibaToken(cibaResponse)
async function pollForCibaToken(cibaResponse) {
const interval = cibaResponse.interval * 1000
const expiresAt = Date.now() + cibaResponse.expires_in * 1000
while (Date.now() < expiresAt) {
await new Promise(resolve => setTimeout(resolve, interval))
const response = await fetch(`${AURIS_DOMAIN}/api/auth/token`, {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'Authorization': `Basic ${btoa(`${CLIENT_ID}:${CLIENT_SECRET}`)}`,
},
body: new URLSearchParams({
grant_type: 'urn:openid:params:grant-type:ciba',
auth_req_id: cibaResponse.auth_req_id,
}),
})
if (response.ok) {
return await response.json()
}
const error = await response.json()
if (error.error === 'authorization_pending') continue
if (error.error === 'slow_down') {
await new Promise(r => setTimeout(r, 5000))
continue
}
if (error.error === 'expired_token') {
throw new Error('Richiesta CIBA scaduta. L\'utente non ha risposto in tempo.')
}
if (error.error === 'access_denied') {
throw new Error('L\'utente ha negato la richiesta di autenticazione.')
}
throw new Error(`Errore CIBA: ${error.error}`)
}
throw new Error('Richiesta CIBA scaduta.')
}Parametri della Richiesta CIBA
La richiesta di autenticazione backchannel accetta i seguenti parametri:
| Parametro | Obbligatorio | Descrizione |
|---|---|---|
scope | Sì | Scope OpenID Connect (deve includere openid) |
login_hint | Sì | Identifica l’utente. Può essere un indirizzo email, un numero di telefono o uno user ID. |
binding_message | No | Breve messaggio mostrato all’utente nella schermata di approvazione (es. “Approva accesso alla Dashboard”). Max 128 caratteri. |
requested_expiry | No | Durata richiesta della richiesta di autenticazione in secondi. Limitata dalla configurazione dell’applicazione. |
acr_values | No | Valori ACR (Authentication Context Class Reference) per l’autenticazione step-up |
Il Binding Message
Il binding_message è una funzionalità di sicurezza fondamentale. Viene mostrato all’utente nella notifica di approvazione e deve contenere abbastanza contesto perché l’utente possa confermare cosa sta approvando:
- “Approva l’accesso alla Dashboard” (login)
- “Conferma pagamento di EUR 49.99 a ACME Corp” (approvazione pagamento)
- “Autorizza l’agente del supporto ad accedere al tuo account” (call center)
Includi sempre un binding message significativo. Senza di esso, gli utenti non possono distinguere una richiesta CIBA legittima da un tentativo di phishing. Il binding message deve essere specifico per l’azione corrente — non usare mai un generico “Approva login” per pagamenti o operazioni sensibili.
Gestione degli Errori
| Codice Errore | HTTP Status | Significato |
|---|---|---|
authorization_pending | 400 | L’utente non ha ancora risposto alla notifica |
slow_down | 400 | Il client sta facendo polling troppo velocemente |
expired_token | 400 | La richiesta di autenticazione è scaduta (l’utente non ha risposto) |
access_denied | 400 | L’utente ha esplicitamente negato la richiesta |
invalid_request | 400 | Parametri mancanti o non validi |
unknown_user_id | 400 | Il login_hint non corrisponde a nessun utente conosciuto |
unauthorized_client | 401 | Il client non è autorizzato per CIBA |
Considerazioni sulla Sicurezza
- Client confidenziale obbligatorio: CIBA richiede sempre l’autenticazione del client (client ID + secret). I client pubblici non possono usare CIBA.
- Breve durata della richiesta: Di default 300 secondi. Durate più brevi riducono la finestra per attacchi di social engineering.
- Consenso utente obbligatorio: L’utente deve approvare esplicitamente la richiesta. Auris non approva mai automaticamente.
- Visualizzazione del binding message: L’interfaccia di approvazione mostra sempre il binding message, il nome dell’applicazione e gli scope richiesti.
- Verifica del canale di notifica: Auris invia notifiche CIBA solo a indirizzi email o numeri di telefono verificati.
- Audit logging: Tutte le richieste CIBA (avviate, approvate, negate, scadute) vengono registrate a fini di audit.
Endpoint API
/api/oauth/cibaAvvia una richiesta di autenticazione backchannel. Richiede l’autenticazione del client (Basic auth o client_id/client_secret nel corpo). Restituisce auth_req_id, expires_in e interval.
/api/auth/tokenEndpoint token. Per CIBA, imposta grant_type=urn:openid:params:grant-type:ciba e auth_req_id. Restituisce l’access token all’approvazione dell’utente, o un codice di errore di polling.
/api/oauth/ciba/requestsRequires: view:ciba_requestsElenca le richieste di autenticazione CIBA attive per il tenant. Endpoint admin per il monitoraggio.
Permessi Richiesti
| Operazione | Permesso |
|---|---|
| Abilita CIBA su un’applicazione | manage:applications |
| Configura le impostazioni CIBA | manage:ciba_config |
| Elenca le richieste CIBA attive | view:ciba_requests |
| Avvia/polling per il token | Solo autenticazione client (nessun permesso utente) |
Guide Correlate
- Device Authorization Flow — Flusso disaccoppiato simile per dispositivi con input limitato
- Login Ospitato (PKCE) — Autenticazione standard browser-based
- Multi-Factor Authentication — CIBA può integrarsi con MFA per l’autenticazione step-up