Personalizzazioni

Di seguito trovi il contenuto pronto per un README.md.

# Authentik - Password Reset, Forced Password Change e MFA Onboarding

## Scopo

Questa documentazione descrive la configurazione effettuata su **authentik** per gestire:

1. il reset password self-service tramite **Password dimenticata**;
2. il cambio password forzato al login successivo;
3. la richiesta di configurazione MFA tramite **TOTP** o **Passkey/WebAuthn**.

La configurazione adottata per l'onboarding MFA è la **Path A**:

> L'utente imposta la prima password tramite il flow di password dimenticata.  
> La configurazione MFA viene richiesta al secondo accesso, cioè al primo login normale successivo.

---

## 1. Reset password self-service

Il reset password self-service viene gestito tramite il **Recovery Flow** di authentik.

### Comportamento atteso

L'utente può accedere alla pagina di login e usare la funzione:

```text
Password dimenticata / Recover account / Forgot password

Il flow consente all'utente di:

inserire username o indirizzo email;
ricevere un link di recupero via email;
impostare una nuova password;
accedere con la nuova password.

Requisiti

Per il corretto funzionamento del reset password è necessario che:

l'utente abbia un indirizzo email valorizzato;
la configurazione SMTP globale di authentik sia funzionante;
il Recovery Flow sia associato al Brand attivo.

Brand

Nel Brand attivo deve essere configurato il Recovery Flow:

System → Brands → [Brand attivo] → Default flows → Recovery flow

Il valore deve puntare al flow di recovery utilizzato, ad esempio:

default-recovery-flow

2. Cambio password forzato al login successivo

È stata configurata una logica per forzare un utente a cambiare password al login successivo.

Questa funzionalità si basa su un attributo custom dell'utente:

reset_password: true

Quando l'attributo è impostato a true, l'utente viene obbligato a scegliere una nuova password dopo aver inserito la password attuale.

Dopo il cambio password, l'attributo viene automaticamente riportato a:

reset_password: false

3. Expression Policies

Sono state create due Expression Policy.

3.1 Policy `reset_password`

Questa policy verifica se l'utente deve essere obbligato a cambiare password.

if request.context["pending_user"].attributes.get("reset_password") == True:
    return True

return False

Utilizzo

Questa policy deve essere associata al binding dello stage:

Force Password Reset Prompt Stage

Serve a mostrare lo stage di cambio password solo agli utenti che hanno:

reset_password: true

3.2 Policy `password_update`

Questa policy aggiorna l'attributo dell'utente dopo il cambio password.

pending_user = request.context.get("pending_user")

if not pending_user:
    return False

if pending_user.attributes.get("reset_password") is True:
    pending_user.attributes["reset_password"] = False
    return True

return False

Utilizzo

Questa policy deve essere associata al binding dello stage:

Force Password Reset User Write Stage

Serve a riportare l'attributo reset_password a false dopo che la nuova password è stata salvata.

4. Default Authentication Flow

La configurazione è stata applicata al flow:

default-authentication-flow

La sequenza corretta degli stage è la seguente:

10   default-authentication-identification
20   default-authentication-password
25   Force Password Reset Prompt Stage
26   Force Password Reset User Write Stage
30   default-authentication-mfa-validation
100  default-authentication-login

5. Force Password Reset Prompt Stage

Tipo stage

Prompt Stage

Nome

Force Password Reset Prompt Stage

Order

Lo stage è posizionato dopo la verifica della password attuale e prima della validazione MFA.

Fields

Lo stage deve contenere solo i campi per il cambio password:

default-password-change-field-password
default-password-change-field-password-repeat

Non devono essere presenti campi relativi a:

email;
username;
dati profilo;
enrollment;
user settings.

Validation Policies

Come validation policy deve essere presente:

default-password-change-policy

Questa policy valida la nuova password inserita dall'utente.

Policy Binding

Nel binding dello stage deve essere associata la policy:

reset_password

6. Force Password Reset User Write Stage

Tipo stage

User Write Stage

Nome

Force Password Reset User Write Stage

Order

Questo stage salva effettivamente la nuova password sull'utente.

Policy Binding

Nel binding dello stage deve essere associata la policy:

password_update

Questa policy aggiorna l'attributo utente da:

reset_password: true

reset_password: false

7. Come forzare il cambio password per un utente

Per obbligare un utente a cambiare password al prossimo login:

Directory → Users → [utente] → Edit

Nel campo Attributes aggiungere:

reset_password: true

Salvare le modifiche.

Dopo il cambio password, l'attributo verrà automaticamente aggiornato a:

reset_password: false

8. Note importanti su YAML e Python

Nel campo Attributes dell'utente, i valori booleani sono scritti in formato YAML:

reset_password: true

oppure:

reset_password: false

Dentro le Expression Policy, invece, i booleani Python devono essere scritti con la maiuscola:

True
False

Esempio corretto:

if pending_user.attributes.get("reset_password") is True:
    ...

9. MFA obbligatorio

È stata configurata la richiesta MFA tramite lo stage:

default-authentication-mfa-validation

L'obiettivo è obbligare l'utente ad avere almeno un metodo MFA configurato tra:

TOTP
Passkey / WebAuthn

10. Onboarding MFA - Path A

Per l'onboarding è stata scelta la Path A.

Comportamento

L'utente viene creato in authentik.
L'utente usa la funzione Password dimenticata per impostare la prima password.
L'utente può completare il primo accesso.
Al login successivo, passando dal default-authentication-flow, authentik richiede la configurazione MFA se non è già presente.

Quindi la configurazione MFA non viene richiesta direttamente nel Recovery Flow, ma nel login flow normale.

11. Authenticator Validation Stage

Lo stage usato per la validazione MFA è:

default-authentication-mfa-validation

Posizione nel flow

Lo stage deve rimanere prima dello User Login Stage:

30   default-authentication-mfa-validation
100  default-authentication-login

Configurazione attesa

Lo stage deve accettare almeno le seguenti classi di dispositivo:

TOTP
WebAuthn

La configurazione consigliata è:

Not configured action: Configure

In questo modo, se l'utente non ha ancora configurato alcun dispositivo MFA, authentik lo porta alla configurazione di un metodo MFA.

12. TOTP Setup Stage

Per consentire la configurazione di un'app authenticator è previsto uno stage di tipo:

TOTP Authenticator Setup Stage

Nome suggerito:

eagle-authenticator-totp-setup

Google Authenticator;
Microsoft Authenticator;
Authy;
1Password;
Bitwarden;
altri password manager compatibili.

13. WebAuthn / Passkey Setup Stage

Per consentire la configurazione di Passkey o security key è previsto uno stage di tipo:

WebAuthn / FIDO2 / Passkeys Authenticator Setup Stage

Nome suggerito:

eagle-authenticator-webauthn-setup

Windows Hello;
Touch ID;
Face ID;
password manager con supporto Passkey;
security key FIDO2 compatibili.

14. Configuration stages MFA

Nello stage:

default-authentication-mfa-validation

devono essere associati gli stage di configurazione MFA disponibili, ad esempio:

eagle-authenticator-totp-setup
eagle-authenticator-webauthn-setup

In questo modo, se l'utente non ha dispositivi MFA configurati, authentik gli permette di configurare almeno uno dei metodi disponibili.

15. Flusso finale atteso per nuovo utente

Primo accesso / prima password

Utente creato → Password dimenticata → Email recovery → Impostazione nuova password

Accesso successivo

Login normale → Username → Password → Configurazione MFA obbligatoria → Login completato

16. Flusso finale atteso per cambio password forzato

Se un admin imposta sull'utente:

reset_password: true

Username → Password attuale → Nuova password → Conferma nuova password → MFA → Login

Al termine, l'attributo utente diventa:

reset_password: false

17. Troubleshooting

L'utente continua a ricevere la richiesta di cambio password

Verificare che lo stage:

Force Password Reset User Write Stage

abbia associata la policy:

password_update

e che l'attributo utente venga aggiornato a:

reset_password: false

Il cambio password non viene richiesto

Verificare che:

l'utente abbia l'attributo:

reset_password: true

la policy reset_password sia associata allo stage:

Force Password Reset Prompt Stage

lo stage Force Password Reset Prompt Stage abbia order 25;
lo stage Force Password Reset User Write Stage abbia order 26.

Errore relativo a email o user settings durante il cambio password

Verificare che il Prompt Stage contenga solo i campi:

default-password-change-field-password
default-password-change-field-password-repeat

e che nelle Validation Policies sia presente solo:

default-password-change-policy

Rimuovere eventuali campi o policy relativi a:

email;
username;
profilo utente;
enrollment;
user settings.

18. Riepilogo configurazione

Flow modificato

default-authentication-flow

Stage aggiunti

25 - Force Password Reset Prompt Stage
26 - Force Password Reset User Write Stage

Policy create

reset_password
password_update

Attributo utente

reset_password: true

MFA

TOTP oppure Passkey/WebAuthn

Strategia onboarding MFA

Path A - MFA richiesto al secondo accesso

Personalizzazioni

Requisiti

Brand

2. Cambio password forzato al login successivo

3. Expression Policies

3.1 Policy reset_password

Utilizzo

3.2 Policy password_update

Utilizzo

4. Default Authentication Flow

5. Force Password Reset Prompt Stage

Tipo stage

Nome

Order

Fields

Validation Policies

Policy Binding

6. Force Password Reset User Write Stage

Tipo stage

Nome

Order

Policy Binding

7. Come forzare il cambio password per un utente

8. Note importanti su YAML e Python

9. MFA obbligatorio

10. Onboarding MFA - Path A

Comportamento

11. Authenticator Validation Stage

Posizione nel flow

Configurazione attesa

12. TOTP Setup Stage

13. WebAuthn / Passkey Setup Stage

14. Configuration stages MFA

15. Flusso finale atteso per nuovo utente

Primo accesso / prima password

Accesso successivo

16. Flusso finale atteso per cambio password forzato

17. Troubleshooting

L'utente continua a ricevere la richiesta di cambio password

Il cambio password non viene richiesto

Errore relativo a email o user settings durante il cambio password

18. Riepilogo configurazione

Flow modificato

Stage aggiunti

Policy create

Attributo utente

MFA

Strategia onboarding MFA

3.1 Policy `reset_password`

3.2 Policy `password_update`