# Authentification à deux facteurs

`auth.twoFactor` active l'**authentification à deux facteurs basée sur TOTP** (mots de passe à usage unique basés sur le temps). Les utilisateurs ajoutent un second facteur avec une application d'authentification (Google Authenticator, 1Password, Authy, …) et saisissent un code rotatif à la connexion.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  twoFactor:
    issuer: MyApp
    backupCodes: true
```

:::callout
**La 2FA nécessite la stratégie `emailAndPassword`.** Le TOTP superpose un second facteur par-dessus la connexion par mot de passe. Configurer `twoFactor` sans une stratégie `emailAndPassword` dans `auth.strategies` échoue à la validation au démarrage.
:::

## Activer la 2FA

La forme la plus simple est un booléen — activer avec les valeurs par défaut :

```yaml
auth:
  strategies:
    - type: emailAndPassword
  twoFactor: true
```

Pour contrôler le nom de l'émetteur, les codes de secours et le format des codes, utilisez la forme objet :

```yaml
auth:
  strategies:
    - type: emailAndPassword
  twoFactor:
    issuer: MyApp
    backupCodes: true
    digits: 6
    period: 30
```

## Configuration

`auth.twoFactor` accepte soit un booléen, soit un objet de configuration.

| Propriété     | Description                                                                                                         |
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
| _(booléen)_   | `true` active la 2FA avec les valeurs par défaut ; `false` (ou l'omission du champ) la désactive.                   |
| `issuer`      | Nom affiché dans l'application d'authentification de l'utilisateur (par ex. `MyApp`). Identifie l'entrée du compte. |
| `backupCodes` | Booléen. Lorsque `true`, génère des codes de secours à usage unique pour la récupération du compte.                 |
| `digits`      | Nombre de chiffres dans le code TOTP, 4–8. Par défaut `6`.                                                          |
| `period`      | Intervalle de rotation du code en secondes (positif). Par défaut `30`.                                              |

:::callout
Conservez `digits: 6` et `period: 30` sauf besoin de compatibilité spécifique — ils correspondent aux valeurs par défaut que presque toutes les applications d'authentification attendent. Des valeurs non standard peuvent dérouter certaines applications.
:::

## Codes de secours

Lorsque `backupCodes: true`, les utilisateurs reçoivent un ensemble de codes de récupération à usage unique lors de l'inscription à la 2FA — essentiels s'ils perdent l'accès à leur appareil d'authentification. La livraison est personnalisable via le [modèle d'e-mail](/fr/docs/auth-strategies#email-templates) `twoFactorBackupCodes` :

```yaml
auth:
  strategies:
    - type: emailAndPassword
  twoFactor:
    issuer: MyApp
    backupCodes: true
  emailTemplates:
    twoFactorBackupCodes:
      subject: Your MyApp recovery codes
      text: 'Keep these recovery codes safe: $code'
```

## Flux d'inscription

1. L'utilisateur se connecte avec son e-mail et son mot de passe comme d'habitude.
2. Il s'inscrit à la 2FA — l'application affiche un secret TOTP (généralement sous forme de QR code) étiqueté avec `issuer`.
3. Il le scanne dans une application d'authentification, qui commence à générer des codes toutes les `period` secondes.
4. Lors des connexions ultérieures, après l'étape du mot de passe, il saisit le code courant de longueur `digits`.
5. S'ils sont activés, les codes de secours offrent une voie de récupération lorsque l'appareil est indisponible.

## Pages associées

- [Stratégies](/fr/docs/auth-strategies) — la stratégie `emailAndPassword` dont dépend la 2FA, ainsi que le modèle d'e-mail `twoFactorBackupCodes`.
- [Sessions](/fr/docs/auth-sessions) — sessions émises après la réussite du second facteur.
- [Présentation de l'authentification](/fr/docs/auth-overview) — le bloc `auth` en contexte.