Autenticazione a due fattori e multifattore (2FA/MFA)

FoxIDs supporta sia una modalita semplice a due fattori sia una modalita avanzata multifattore nel metodo di autenticazione login.

• Modalita a due fattori: Advanced multi-factor e disabilitato (predefinito).
• Modalita multifattore: Advanced multi-factor e abilitato.

Usa la modalita a due fattori quando basta un fattore aggiuntivo. Usa la modalita multifattore quando hai bisogno di una catena MFA ordinata o vuoi includere metodi di autenticazione come passaggi MFA.

Concetti

L'autenticazione a due fattori (2FA) e l'autenticazione multifattore (MFA) aggiungono uno o piu passaggi di verifica dopo l'accesso primario.

• 2FA: accesso primario piu un fattore aggiuntivo.
• MFA: accesso primario piu uno o piu fattori aggiuntivi ordinati.

Fattori supportati

FoxIDs supporta fattori integrati e metodi di autenticazione come elementi MFA.

Factor	Type	AMR value
Codice SMS	Integrato	sms
Codice email	Integrato	email
Codice app autenticatrice	Integrato	otp
Codice di recupero	Integrato (app autenticatrice)	otp
Metodo di autenticazione (OIDC, SAML 2.0, Environment Link)	Elemento configurabile	AMR configurato, oppure nome del metodo/profilo se vuoto

Puoi usare qualsiasi app autenticatrice compatibile, ad esempio Google Authenticator, Microsoft Authenticator, Authy e altre app TOTP.

Quando e richiesto MFA

MFA viene attivato quando si applica una delle seguenti condizioni:

• L'utente ha abilitato Require multi-factor (2FA/MFA).
• Il metodo di autenticazione login ha abilitato Require multi-factor (2FA/MFA).
• L'applicazione chiamante richiede MFA con ACR urn:foxids:mfa.

I requisiti MFA si applicano in entrambe le modalita. Se Advanced multi-factor e disabilitato, il requisito viene soddisfatto dal flusso semplice a due fattori.

Se vengono richiesti valori ACR specifici insieme a urn:foxids:mfa, sono richiesti solo i valori ACR corrispondenti.

Modalita a due fattori (Advanced multi-factor e disabilitato)

In questa modalita, le opzioni integrate di autenticazione a due fattori sono configurate direttamente:

• App autenticatrice
• SMS
• Email

Per configurare la modalita a due fattori:

1. Apri la scheda Authentication.
2. Fai clic sul metodo di autenticazione Login per modificarlo.
3. Fai clic su Show advanced.
4. Vai alla sezione Multi-factor.
5. Mantieni Advanced multi-factor disabilitato e configura le opzioni App autenticatrice, SMS ed Email.

Il nome dell'app autenticatrice mostrato agli utenti puo essere configurato. Per impostazione predefinita viene usato il nome del tenant.

I fattori SMS ed email richiedono informazioni di contatto dell'utente. Queste possono essere fornite come identificatori utente oppure come claim (phone_number ed email).

Comportamento di selezione a due fattori

In modalita a due fattori, FoxIDs preferisce un'app autenticatrice gia registrata. Se non ne e registrata alcuna, SMS ha priorita sull'email quando entrambi sono disponibili.

SMS two-factor enabled and user has phone number	Email two-factor enabled and user has email	User has registered authenticator app	Possible two-factor type(s)	Selected two-factor type
false	false	false	Configurazione app autenticatrice	Configurazione app autenticatrice
false	false	true	App autenticatrice	App autenticatrice
true	false	false	SMS, con configurazione facoltativa dell'app autenticatrice dopo la verifica SMS	SMS
true	false	true	SMS e app autenticatrice	App autenticatrice
false	true	false	Email, con configurazione facoltativa dell'app autenticatrice dopo la verifica email	Email
false	true	true	Email e app autenticatrice	App autenticatrice
true	true	false	SMS ed email, con configurazione facoltativa dell'app autenticatrice dopo verifica SMS o email	SMS
true	true	true	SMS, email e app autenticatrice	App autenticatrice

Notificare un’API quando viene registrata un’app di autenticazione

Il metodo di autenticazione login può notificare immediatamente il backend dopo che un utente registra una nuova app di autenticazione. La notifica è facoltativa e si applica solo alle nuove registrazioni, non ai successivi login con l’app.

Per configurare la notifica:

1. Apri la scheda Authentication.
2. Fai clic sul metodo di autenticazione Login per modificarlo.
3. Fai clic su Show advanced.
4. Vai alla sezione Multi-factor.
5. In modalità a due fattori, abilita Notify an API when an authenticator app is registered sotto le opzioni dei fattori integrati. In modalità multifattore avanzata, abilitalo nell’elemento MFA Authenticator app.
6. Configura l’URL di base e il secret dell’API.

FoxIDs salva localmente la registrazione dell’app di autenticazione prima di chiamare l’API e scrive la traccia Authenticator app registration saved locally; external notification pending. L’API viene quindi chiamata in modo sincrono. Il login continua solo se l’API restituisce lo stato HTTP 200 OK. Se la chiamata non riesce o restituisce un altro stato, FoxIDs rimuove la nuova registrazione e mostra la pagina di errore. Le registrazioni esistenti non vengono modificate.

La registrazione riuscita viene scritta nel log di audit dopo che l’API ha restituito 200 OK. Se la notifica è disabilitata, l’audit viene scritto immediatamente dopo il salvataggio della registrazione locale.

Richiesta all’API di notifica

Se l’URL di base configurato è https://backend.example/authenticator, FoxIDs invia una richiesta HTTP POST a:

https://backend.example/authenticator/notification

FoxIDs Cloud chiama la tua API dall’IP 57.128.60.142.

Gli indirizzi IP possono cambiare o essere ampliati.

La richiesta usa HTTP Basic authentication:

• Nome utente: authenticator_app
• Password: il secret API configurato

La richiesta JSON contiene:

{
  "type": "registered",
  "registration_id": "7a772286-76a2-4f17-a0f8-4e927bb1772d",
  "user_id": "e061ed17-7b44-48a8-b224-ecdb800ed5cc",
  "email": "user@example.com",
  "phone": "+4512345678",
  "username": "user@example.com"
}

type identifica la notifica. Il tipo supportato registered indica che è stata registrata una nuova app di autenticazione. registration_id è l’ID univoco permanente della nuova registrazione. L’API può usarlo come chiave di idempotenza. user_id è l’ID utente tecnico stabile di FoxIDs. email, phone e username sono inclusi quando hanno un valore. Il secret dell’app di autenticazione e il codice di recupero non vengono mai inviati.

L’API deve accettare la notifica e restituire 200 OK non appena il lavoro sincrono richiesto è completato. Qualsiasi ulteriore accodamento o distribuzione ad altri deployments è responsabilità del backend.

Gestire le registrazioni delle app di autenticazione

Gli amministratori possono elencare e rimuovere singolarmente le registrazioni delle app di autenticazione di un utente in Internal Users → modifica utente → Advanced → Two-factor. Le registrazioni sono identificate dall'ID persistente e, per le nuove registrazioni, dalla data di registrazione. Durante la registrazione non viene richiesto un nome visualizzato.

Per elencare, leggere, creare, aggiornare, eliminare o sincronizzare registrazioni tramite Control API, consulta Control API - utenti e app di autenticazione. La guida documenta endpoint, risorsa di request, sicurezza, response di errore e comportamento delle notification in un unico punto.

Modalita multifattore (Advanced multi-factor e abilitato)

Quando Advanced multi-factor e abilitato, MFA viene configurato come elenco ordinato di massimo 5 elementi MFA.

È possibile configurare un solo elemento MFA Authenticator app. Un utente può avere fino a cinque registrazioni di app di autenticazione per tale elemento. Tutte le registrazioni sono alternative per completare lo stesso elemento MFA: FoxIDs verifica il codice inviato rispetto alle app registrate e accetta la prima corrispondenza. La richiesta di registrazione durante il login crea una registrazione solo quando l’utente non ne ha alcuna; non ne aggiunge un’altra quando ne esiste già una. Il nome dell’app di autenticazione e l’API facoltativa per le notifiche di registrazione sono configurati nell’elemento MFA Authenticator app.

Per configurare la modalita multifattore:

1. Apri la scheda Authentication.
2. Fai clic sul metodo di autenticazione Login per modificarlo.
3. Fai clic su Show advanced.
4. Vai alla sezione Multi-factor.
5. Abilita Advanced multi-factor e configura gli elementi MFA ordinati.

Tipi di elemento MFA supportati:

• Integrati:
  • SMS
  • Email
  • App autenticatrice
• Metodo di autenticazione:
  • OpenID Connect
  • SAML 2.0
  • Environment Link

Regole di configurazione:

• I tipi integrati possono essere configurati una sola volta ciascuno.
• Gli elementi di metodo di autenticazione possono essere configurati piu volte, ad esempio con profili diversi.
• Gli elementi vengono eseguiti nell'ordine dell'elenco.
• Puoi aggiungere, rimuovere e riordinare gli elementi.

Comportamento AMR e ACR degli elementi MFA

Ogni elemento MFA completato contribuisce ai valori del claim AMR nella sessione.

• I valori AMR integrati sono fissi:
  • SMS: sms
  • Email: email
  • App autenticatrice e codice di recupero: otp
• AMR dell'elemento metodo di autenticazione:
  • Puo essere configurato facoltativamente un AMR personalizzato.
  • Se l'AMR e vuoto, viene usato il nome del metodo di autenticazione o del profilo.

I valori ACR richiesti vengono confrontati con i valori AMR degli elementi MFA in questo formato:

• urn:foxids:<amr>
• Esempio: urn:foxids:link

urn:foxids:mfa e il requisito MFA generale e FoxIDs aggiunge AMR mfa quando MFA viene completato.

Selezione e concatenazione degli elementi MFA

• Se vengono richiesti valori ACR specifici, deve essere completato uno degli elementi MFA corrispondenti.
• Se viene richiesto solo MFA generale, qualsiasi elemento MFA configurato e disponibile puo soddisfare il requisito.
• Se esiste piu di un elemento MFA idoneo e FoxIDs non riesce a selezionarne uno automaticamente, viene mostrata una UI di selezione.
• Se e configurata un'app autenticatrice e questa e gia registrata, FoxIDs la preferisce per richieste MFA generali.
• Se viene selezionata la configurazione dell'app autenticatrice e questa non e ancora registrata, il flusso di configurazione puo continuare dopo un passaggio selezionato di SMS, email o metodo di autenticazione.
• Se e configurata solo l'app autenticatrice, la configurazione puo iniziare direttamente dopo l'accesso del primo fattore.

Pagina del metodo di autenticazione MFA con registrazione facoltativa dell'app autenticatrice e opzione per scegliere un elemento MFA diverso.

Pagina MFA SMS con registrazione facoltativa dell'app autenticatrice e opzione per scegliere un elemento MFA diverso.

Pagina MFA email in cui viene configurata l'app autenticatrice, con opzione per scegliere un elemento MFA diverso.

Pagina MFA app autenticatrice con opzione per scegliere un elemento MFA diverso.

Metodi di autenticazione usati come elementi MFA

I metodi di autenticazione (OIDC, SAML 2.0, Environment Link) possono essere usati come elementi MFA con queste regole:

• I valori ACR specifici per MFA non vengono inoltrati alla richiesta del metodo di autenticazione MFA.
• La risposta del metodo di autenticazione deve includere il valore AMR richiesto per l'elemento MFA selezionato.
• Il valore AMR viene normalmente aggiunto nella trasformazione dei claim se l'identita restituita corrisponde all'identita attesa. Vedi l'esempio di trasformazione dei claim.
• Se il valore AMR richiesto manca, il login fallisce.
• Dopo una validazione riuscita, FoxIDs aggiunge AMR mfa alla sessione risultante.

Richiedere MFA dalle applicazioni

Le applicazioni possono richiedere MFA sia in OpenID Connect sia in SAML 2.0.

Se vengono richiesti valori ACR specifici ma questi non sono configurati sugli elementi MFA nel metodo di autenticazione login selezionato, l'autenticazione fallisce.

OpenID Connect

Usa acr_values:

• MFA generale: acr_values=urn:foxids:mfa
• MFA generale e metodo specifico: acr_values=urn:foxids:mfa urn:foxids:link

SAML 2.0

Usa RequestedAuthnContext.AuthnContextClassRef:

• MFA generale: includi urn:foxids:mfa
• MFA generale e metodo specifico: includi urn:foxids:mfa e valori specifici come urn:foxids:link

Comportamento della sessione

FoxIDs valida i valori AMR richiesti rispetto alla sessione di login corrente.

• Nuovo login: la sessione viene creata dopo che tutti i requisiti sono soddisfatti.
• Step-up login: una sessione esistente viene aggiornata dopo che tutti i requisiti MFA aggiuntivi sono soddisfatti.
• Riutilizzo della sessione: se la sessione soddisfa gia i valori AMR richiesti, FoxIDs riutilizza la sessione e non richiede di nuovo il login.

Risoluzione dei problemi

Motivi comuni dei fallimenti MFA:

• I valori ACR richiesti non sono configurati come elementi MFA nel metodo di autenticazione login.
• Un metodo di autenticazione usato come MFA non restituisce il valore AMR richiesto.
• Nessun elemento MFA configurato e attualmente disponibile per l'utente, ad esempio perche mancano dati di telefono o email per SMS o email.

Documentazione correlata

• Login e Home Realm Discovery
• Utenti interni
• Metodi di autenticazione
• Trasformazioni e attivita dei claim
• Interfaccia utente estesa