Skip to Content

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:

  1. Il client invia una richiesta di autenticazione backchannel a /api/oauth/ciba con un login_hint (email, numero di telefono o user ID) che identifica l’utente
  2. Auris valida la richiesta e invia una notifica all’utente sul suo dispositivo o canale registrato
  3. L’utente vede i dettagli della richiesta (nome dell’applicazione, binding message) e approva o nega
  4. 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 FunzionaIdeale Per
PollIl client fa polling sull’endpoint token a intervalli regolari finché l’utente rispondeIntegrazioni semplici, client lato server
PingAuris invia una notifica a un callback URL pre-registrato, poi il client scambia l’auth request ID con un tokenArchitetture event-driven
PushAuris consegna il token direttamente a un callback URL pre-registratoRequisiti 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:

CanaleRequisiti
EmailL’utente deve avere un indirizzo email verificato
SMSL’utente deve avere un numero di telefono verificato. Richiede la configurazione del provider SMS (Twilio).
PushRichiede 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:

ImpostazioneDefaultNote
Durata Richiesta300 secondi (5 minuti)Tempo massimo che l’utente ha per approvare o negare
Intervallo Polling5 secondiIntervallo 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

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:

ParametroObbligatorioDescrizione
scopeSìScope OpenID Connect (deve includere openid)
login_hintSìIdentifica l’utente. Può essere un indirizzo email, un numero di telefono o uno user ID.
binding_messageNoBreve messaggio mostrato all’utente nella schermata di approvazione (es. “Approva accesso alla Dashboard”). Max 128 caratteri.
requested_expiryNoDurata richiesta della richiesta di autenticazione in secondi. Limitata dalla configurazione dell’applicazione.
acr_valuesNoValori 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 ErroreHTTP StatusSignificato
authorization_pending400L’utente non ha ancora risposto alla notifica
slow_down400Il client sta facendo polling troppo velocemente
expired_token400La richiesta di autenticazione è scaduta (l’utente non ha risposto)
access_denied400L’utente ha esplicitamente negato la richiesta
invalid_request400Parametri mancanti o non validi
unknown_user_id400Il login_hint non corrisponde a nessun utente conosciuto
unauthorized_client401Il 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

POST/api/oauth/ciba

Avvia 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.

POST/api/auth/token

Endpoint 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.

GET/api/oauth/ciba/requestsRequires: view:ciba_requests

Elenca le richieste di autenticazione CIBA attive per il tenant. Endpoint admin per il monitoraggio.


Permessi Richiesti

OperazionePermesso
Abilita CIBA su un’applicazionemanage:applications
Configura le impostazioni CIBAmanage:ciba_config
Elenca le richieste CIBA attiveview:ciba_requests
Avvia/polling per il tokenSolo autenticazione client (nessun permesso utente)

Guide Correlate