Authentification à deux facteurs et multi-facteur (2FA/MFA)

FoxIDs prend en charge à la fois un mode simple à deux facteurs et un mode avancé multi-facteur dans la méthode d'authentification de connexion.

Mode à deux facteurs : Advanced multi-factor est désactivé (par défaut).
Mode multi-facteur : Advanced multi-factor est activé.

Utilisez le mode à deux facteurs lorsqu'un facteur supplémentaire suffit. Utilisez le mode multi-facteur lorsque vous avez besoin d'une chaîne MFA ordonnée ou que vous souhaitez utiliser des méthodes d'authentification comme étapes MFA.

Concepts

L'authentification à deux facteurs (2FA) et l'authentification multi-facteur (MFA) ajoutent toutes deux une ou plusieurs étapes de vérification après la connexion primaire.

2FA : une connexion primaire plus un facteur supplémentaire.
MFA : une connexion primaire plus un ou plusieurs facteurs supplémentaires ordonnés.

Facteurs pris en charge

FoxIDs prend en charge des facteurs intégrés et des méthodes d'authentification comme éléments MFA.

Facteur	Type	Valeur AMR
Code SMS	Intégré	`sms`
Code e-mail	Intégré	`email`
Code d'authenticator app	Intégré	`otp`
Recovery code	Intégré (authenticator app)	`otp`
Méthode d'authentification (OIDC, SAML 2.0, TrackLink)	Élément configurable	AMR configurée, ou nom de méthode/profil si vide

Vous pouvez utiliser n'importe quelle authenticator app compatible, par exemple Google Authenticator, Microsoft Authenticator, Authy et d'autres applications TOTP.

Quand la MFA est requise

La MFA est déclenchée lorsque l'une des conditions suivantes s'applique :

L'utilisateur a activé Require multi-factor (2FA/MFA).
La méthode d'authentification de connexion a activé Require multi-factor (2FA/MFA).
L'application appelante demande la MFA avec ACR urn:foxids:mfa.

Les exigences MFA s'appliquent dans les deux modes. Si Advanced multi-factor est désactivé, l'exigence est satisfaite par le flux simple à deux facteurs.

Si des valeurs ACR spécifiques sont demandées avec urn:foxids:mfa, seules les valeurs ACR correspondantes sont requises.

Mode à deux facteurs (Advanced multi-factor est désactivé)

Dans ce mode, les options intégrées à deux facteurs sont configurées directement :

Authenticator app
SMS
E-mail

Pour configurer le mode à deux facteurs :

Ouvrez l'onglet Authentication.
Cliquez sur la méthode d'authentification de connexion Login pour la modifier.
Cliquez sur Show advanced.
Accédez à la section Multi-factor.
Laissez Advanced multi-factor désactivé et configurez les options Authenticator app, SMS et E-mail.

Le nom de l'authenticator app affiché aux utilisateurs peut être configuré. Par défaut, le nom du tenant est utilisé.

Configure simple two-factor options in login authentication method

Les facteurs SMS et e-mail nécessitent des informations de contact de l'utilisateur. Elles peuvent être fournies comme identifiants utilisateur ou comme claims (phone_number et email).

Comportement de sélection du type à deux facteurs

En mode à deux facteurs, FoxIDs privilégie une authenticator app déjà enregistrée. Si aucune authenticator app n'est enregistrée, SMS est préféré à l'e-mail lorsque les deux sont disponibles.

SMS deux facteurs activé et l'utilisateur a un numéro de téléphone	E-mail deux facteurs activé et l'utilisateur a un e-mail	L'utilisateur a enregistré une authenticator app	Types deux facteurs possibles	Type deux facteurs sélectionné
false	false	false	Configuration de l'authenticator app	Configuration de l'authenticator app
false	false	true	Authenticator app	Authenticator app
true	false	false	SMS avec configuration optionnelle d'une authenticator app après vérification SMS	SMS
true	false	true	SMS et authenticator app	Authenticator app
false	true	false	E-mail avec configuration optionnelle d'une authenticator app après vérification de l'e-mail	E-mail
false	true	true	E-mail et authenticator app	Authenticator app
true	true	false	SMS et e-mail avec configuration optionnelle d'une authenticator app après vérification par SMS ou e-mail	SMS
true	true	true	SMS, e-mail et authenticator app	Authenticator app

Notifier une API lorsqu’une application d’authentification est enregistrée

La méthode d’authentification de connexion peut notifier immédiatement votre backend après qu’un utilisateur a enregistré une nouvelle application d’authentification. La notification est facultative et s’applique uniquement aux nouvelles inscriptions, pas aux connexions ultérieures avec l’application.

Pour configurer la notification :

Ouvrez l’onglet Authentication.
Cliquez sur la méthode d’authentification Login pour la modifier.
Cliquez sur Show advanced.
Accédez à la section Multi-factor.
En mode à deux facteurs, activez Notify an API when an authenticator app is registered sous les options de facteur intégrées. En mode multi-facteur avancé, activez cette option dans l’élément MFA Authenticator app.
Configurez l’URL de base et le secret de l’API.

FoxIDs enregistre localement l’application d’authentification avant d’appeler l’API et écrit la trace Authenticator app registration saved locally; external notification pending. L’API est ensuite appelée de manière synchrone. La connexion ne se poursuit que si l’API renvoie le statut HTTP 200 OK. Si l’appel échoue ou renvoie un autre statut, FoxIDs supprime la nouvelle inscription et affiche la page d’erreur. Les inscriptions existantes ne sont pas modifiées.

L’inscription réussie est écrite dans le journal d’audit après que l’API a renvoyé 200 OK. Si la notification est désactivée, l’audit est écrit immédiatement après l’enregistrement local de l’inscription.

Requête vers l’API de notification

Si l’URL de base configurée est https://backend.example/authenticator, FoxIDs envoie une requête HTTP POST à :

https://backend.example/authenticator/notification

FoxIDs Cloud appelle votre API depuis l’IP 57.128.60.142.

Les adresses IP peuvent changer ou être étendues.

La requête utilise HTTP Basic authentication :

Nom d’utilisateur : authenticator_app
Mot de passe : le secret d’API configuré

La requête JSON contient :

{
  "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 identifie la notification. Le type pris en charge registered signifie qu’une nouvelle application d’authentification a été enregistrée. registration_id est l’ID unique permanent de la nouvelle inscription. Votre API peut l’utiliser comme clé d’idempotence. user_id est l’ID utilisateur technique et stable de FoxIDs. email, phone et username sont inclus lorsqu’ils ont une valeur. Le secret de l’application d’authentification et le code de récupération ne sont jamais envoyés.

L’API doit accepter la notification et renvoyer 200 OK dès que le travail synchrone requis est terminé. Toute mise en file d’attente ou distribution supplémentaire vers d’autres deployments relève de la responsabilité du backend.

Gérer les enregistrements d'applications d'authentification

Les administrateurs peuvent lister et supprimer individuellement les enregistrements d'applications d'authentification d'un utilisateur dans Internal Users → modifier l'utilisateur → Advanced → Two-factor. Les enregistrements sont identifiés par leur ID persistant et, pour les nouveaux enregistrements, par leur date. Aucun nom d'affichage n'est demandé à l'utilisateur pendant l'enregistrement.

Pour lister, lire, créer, mettre à jour, supprimer ou synchroniser des enregistrements via Control API, consultez Control API - utilisateurs et applications d'authentification. Ce guide documente les endpoints, la ressource de request, la sécurité, les réponses d'erreur et le comportement de notification à un seul endroit.

Mode multi-facteur (Advanced multi-factor est activé)

Lorsque Advanced multi-factor est activé, la MFA est configurée comme une liste ordonnée d'au maximum 5 éléments MFA.

Un seul élément MFA Authenticator app peut être configuré. Un utilisateur peut posséder jusqu’à cinq inscriptions d’applications d’authentification pour cet élément. Toutes les inscriptions sont des alternatives pour compléter le même élément MFA : FoxIDs vérifie le code soumis par rapport aux applications enregistrées et accepte la première correspondance. L’invite d’inscription lors de la connexion ne crée une inscription que lorsque l’utilisateur n’en possède aucune ; elle n’en ajoute pas une autre lorsqu’une inscription existe déjà. Le nom de l’application d’authentification et l’API facultative de notification d’inscription sont configurés dans l’élément MFA Authenticator app.

Pour configurer le mode multi-facteur :

Ouvrez l'onglet Authentication.
Cliquez sur la méthode d'authentification de connexion Login pour la modifier.
Cliquez sur Show advanced.
Accédez à la section Multi-factor.
Activez Advanced multi-factor et configurez les éléments MFA ordonnés.

Types d'éléments MFA pris en charge :

Intégrés :
- SMS
- E-mail
- Authenticator app
Méthode d'authentification :

Règles de configuration :

Les types d'éléments intégrés ne peuvent être configurés qu'une seule fois chacun.
Les éléments de type méthode d'authentification peuvent être configurés plusieurs fois, par exemple avec des profils différents.
Les éléments sont exécutés dans l'ordre de la liste.
Vous pouvez ajouter, supprimer et réorganiser des éléments.

Configure advanced multi-factor item list with add/remove/reorder

Comportement AMR et ACR des éléments MFA

Chaque élément MFA terminé contribue des valeurs de claim AMR à la session.

Les valeurs AMR intégrées sont fixes :
- SMS : sms
- E-mail : email
- Authenticator app et recovery code : otp
Élément MFA de type méthode d'authentification :
- Une AMR personnalisée optionnelle peut être configurée.
- Si l'AMR est vide, le nom de la méthode d'authentification ou du profil est utilisé.

Les valeurs ACR demandées sont mises en correspondance avec les valeurs AMR des éléments MFA dans ce format :

urn:foxids:<amr>
Exemple : urn:foxids:link

urn:foxids:mfa est l'exigence MFA générale, et FoxIDs ajoute AMR mfa lorsque la MFA est terminée.

Sélection et enchaînement des éléments MFA

Si des valeurs ACR spécifiques sont demandées, l'un des éléments MFA correspondants doit être terminé.
Si seule la MFA générale est demandée, n'importe quel élément MFA configuré et disponible peut satisfaire l'exigence.
Si plusieurs éléments MFA éligibles existent et que FoxIDs ne peut pas en sélectionner un automatiquement, une interface de sélection est affichée.
Si une authenticator app est configurée et déjà enregistrée, FoxIDs la privilégie pour les demandes MFA générales.
Si la configuration de l'authenticator app est sélectionnée et qu'elle n'est pas encore enregistrée, le flux de configuration peut continuer après une étape SMS, e-mail ou méthode d'authentification sélectionnée.
Si seule l'authenticator app est configurée, la configuration peut commencer directement après la connexion du premier facteur.

Page MFA de méthode d'authentification avec enregistrement optionnel d'une authenticator app et possibilité de choisir un autre élément MFA. MFA authentication method selection page

Page MFA SMS avec enregistrement optionnel d'une authenticator app et possibilité de choisir un autre élément MFA. MFA SMS page

Page MFA e-mail où l'authenticator app est configurée, avec possibilité de choisir un autre élément MFA. MFA Email page

Page MFA pour authenticator app avec possibilité de choisir un autre élément MFA. MFA authenticator app page

Méthodes d'authentification utilisées comme éléments MFA

Les méthodes d'authentification (OIDC, SAML 2.0, TrackLink) peuvent être utilisées comme éléments MFA avec les règles suivantes :

Les valeurs ACR spécifiques à la MFA ne sont pas transférées vers la requête de méthode d'authentification MFA.
La réponse de la méthode d'authentification doit inclure la valeur AMR requise pour l'élément MFA sélectionné.
La valeur AMR est généralement ajoutée dans le claim transform si l'identité retournée correspond à l'identité attendue. Voir l'exemple de claim transform.
Si la valeur AMR requise est absente, la connexion échoue.
Après une validation réussie, FoxIDs ajoute AMR mfa à la session résultante.

Demander la MFA depuis les applications

Les applications peuvent demander la MFA aussi bien en OpenID Connect qu'en SAML 2.0.

Si des valeurs ACR spécifiques sont demandées mais ne sont pas configurées sur les éléments MFA de la méthode d'authentification de connexion sélectionnée, l'authentification échoue.

OpenID Connect

Utilisez acr_values :

MFA générale : acr_values=urn:foxids:mfa
MFA générale et méthode spécifique : acr_values=urn:foxids:mfa urn:foxids:link

SAML 2.0

Utilisez RequestedAuthnContext.AuthnContextClassRef :

MFA générale : inclure urn:foxids:mfa
MFA générale et méthode spécifique : inclure urn:foxids:mfa et des valeurs spécifiques comme urn:foxids:link

Comportement de session

FoxIDs valide les valeurs AMR requises par rapport à la session de connexion actuelle.

Nouvelle connexion : la session est créée lorsque toutes les exigences sont satisfaites.
Step-up login : une session existante est mise à jour lorsque toutes les exigences MFA supplémentaires sont satisfaites.
Réutilisation de session : si la session satisfait déjà les valeurs AMR requises, FoxIDs réutilise la session et ne redemande pas de connexion.

Dépannage

Raisons courantes des échecs MFA :

Les valeurs ACR demandées ne sont pas configurées comme éléments MFA dans la méthode d'authentification de connexion.
Une méthode d'authentification utilisée comme MFA ne retourne pas la valeur AMR requise.
Aucun élément MFA configuré n'est actuellement disponible pour l'utilisateur, par exemple parce que les données téléphone ou e-mail manquent pour SMS ou e-mail.