Keycloak et TOTP

# Deux mots sur Keycloak

Keycloak est une solution open source de gestion d’identités et d’accès. Les sources, sous licence Apache 2.0, sont disponibles sur GitHub. Keycloak est principalement utilisé pour réaliser l’authentification des utilisateurs pour des applications tiers via les protocoles OpenID Connect et SAML.

Pour plus de détails, n’hésitez pas à consulter l’infographie réalisée par notre service Communication. Elle date de début 2022 et reste globalement d’actualité.

# TOTP ?

TOTP (pour Time based One Time Password, ou mot de passe à usage unique basé sur le temps en français) est un algorithme permettant de générer des mots de passe à usage unique.

À la différence des autres systèmes de mots de passe à usage unique (comme l’envoi d’un code par SMS ou email, ou HOTP), TOPT se base sur deux éléments : une clé secrète et le temps. Ainsi un code TOTP, de part le principe de son algorithme, est valide pour une durée déterminée, habituellement entre 30 et 60 secondes. Le code est une simple suite de quelques chiffres (généralement une suite de 6 chiffres) que l’utilisateur peut facilement renseigner manuellement.

TOTP fait intervenir à la fois un serveur (Keycloak dans notre cas) et une application. Pour l’application TOTP, il s’agit généralement d’une application d’authentification installée sur un smartphone (comme Google Authenticator, Microsoft Authenticator). À noter que n’importe quelle application prenant en charge l’algorithme TOTP peut être utilisée. Ainsi l’application FreeOTP+ (licence Apache 2.0, disponible sur le store f-droid), ou Aegis Authenticator (licence GPLv3, disponible sur Google play et sur le store f-droid) ou le sobrement nommé Authenticator (licence GPLv3, disponible sur le store flathub pour le bureau Gnome) sont des alternatives crédibles aux applications de Google et Microsoft.

Ces deux éléments, serveur et application TOTP, partagent une clé secrète.

À l’usage, le principe est le suivant :

1. l’utilisateur ouvre son application TOTP
2. l’application TOTP, à partir de la clé secrète partagée et de l’heure actuelle, génère un code valide pour un intervalle de temps donné
3. l’utilisateur indique ce code au serveur
4. le serveur valide le code à partir de la clé secrète partagée et de l’intervalle de temps de validité du code

# TOTP dans Keycloak

Keycloak gère nativement l’authentification via TOTP comme second facteur d’authentification. Le comportement par défaut est celui-ci : lors d’une demande d’authentification, si l’utilisateur a préalablement configuré TOTP pour son compte (via l’association d’une application TOTP à son compte Keycloak), alors Keycloak exigera un code TOTP en plus de l’authentification classique avec identifiant et mot de passe, et cela quelle que soit l’application cliente à l’origine de la demande.

Un utilisateur peut, de lui-même et via la console utilisateur, associer une application TOTP à son compte. Il s’agit d’une démarche personnelle, Keycloak ne force pas les utilisateurs à configurer TOTP.

Lors de l’association de l’application TOPT à son compte utilisateur, Keycloak va présenter un QR Code que l’utilisateur devra scanner avec son application TOTP. Cette étape va permettre de partager la clé privée depuis Keycloak vers l’application TOTP ainsi que différents paramètres pour configurer l’algorithme TOTP.

Capture d’écran de l’interface Keycloak présenté aux utilisateurs pour l’association d’une application TOTP :

Après cette étape, l’utilisateur a associé une application TOTP à son compte Keycloak. Conséquence : lors des prochaines demandes d’authentification, Keycloak demandera un code unique TOTP à l’utilisateur (après authentification via identifiant et mot de passe).

Nous pourrions en rester là, le fonctionnement proposé par Keycloak est simple et intuitif, et laisse l’utilisateur décider de l’usage, ou non, de TOTP comme second facteur d’authentification. Cependant, le cas d’usage proposé par défaut par Keycloak ne correspond pas toujours à ce qui est attendu sur le terrain. Comment faire pour forcer l’usage de TOTP pour tous les utilisateurs ? Ou alors comment forcer TOTP uniquement pour certaines applications clientes de Keycloak ?
Je vous remercie de me poser ces questions auxquelles je vais m’empresser de répondre.

# Forcer l’usage de TOTP via un flow custom

La solution la plus simple avec Keycloak pour forcer l’utilisation de TOTP est de modifier la configuration globale de Keycloak. Ceci aura pour conséquence d’exiger un code TOTP aux utilisateurs pour toutes les demandes d’authentification, quelle que soit l’application cliente à l’origine de la demande (et accessoirement de forcer tous les utilisateurs à associer une application TOTP à son compte Keycloak).

Pour cela, laissez moi vous introduire la notion de Flow d’authentification.

Keycloak utilise un système de Flow pour décrire les étapes de l’authentification. Le Flow d’authentification par défaut (nommé “browser”, qui gère les authentifications réalisées via un navigateur) exige un code TOTP uniquement si l’utilisateur a configuré son compte pour utiliser TOTP (association d’une application TOTP à son compte Keycloak).

Il est possible de créer un nouveau Flow d’authentification afin de changer ce comportement et forcer l’usage de TOTP. Ce nouveau Flow peut ensuite être utilisé par défaut en remplacement du Flow “browser” pour toutes les applications clientes de Keycloak.

Exemple de Flow forçant l’usage de TOTP (flow simplifié ne permettant ni Kerberos ni l’usage fournisseur d’identité tiers) :

Le principale différence entre ce nouveau flow et le flow “browser” vient de l’étape “OTP Form”. Celle-ci n’est plus conditionnée par le fait qu’un utilisateur ait préalablement configuré TOTP pour son compte. Cette étape est marquée comme “Required”, ce qui signifie que Keycloak passera toujours par cette étape.

Avec ce flow et si l’utilisateur n’a pas encore associé une application TOTP à son compte, alors Keycloak imposera l’association d’une application TOTP après l’étape d’authentification via identifiant et mot de passe. Les utilisateurs ne pourront plus s’authentifier auprès de Keycloak s’ils ne peuvent pas associer une application TOTP à leur compte. L’accès à une application TOTP devient donc un pré-requis pour l’utilisation de Keycloak.

# Forcer l’usage de TOTP pour les nouveaux utilisateurs

Une alternative au remplacement du flow “browser” existe dans Keycloak pour forcer l’usage de TOPT, cela se passe dans le menu Authentication, puis dans l’onglet Required action. Il est possible d’activer “Configure OTP” comme action par défaut. Ceci aura pour effet d’exiger la configuration TOTP pour tous les nouveaux utilisateurs. C’est pratique et plus simple que de configurer un flow ! Oui, mais vous aurez noté le mot “nouveaux” dans “pour tous les nouveaux utilisateurs”, ce qui a toute son importance car les utilisateurs existants dans Keycloak ne seront pas affectés. À voir donc en fonction des cas d’usages.

Il reste toutefois possible de forcer TOTP pour un utilisateur déjà existant en ajoutant une action obligatoire lors de sa prochaine connexion pour le forcer à configurer TOTP pour son compte. Cela se passe cette fois-ci au niveau des détails de l’utilisateur, il faut lui ajouter l’action “Configure OTP”.

À noter que ces deux options n’empêchent pas un utilisateur de supprimer l’association application TOPT ↔ Keycloak et ainsi à s’authentifier désormais sans second facteur. C’est pourquoi la méthode de modification du flow “browser” reste préférable pour forcer TOTP.

# Forcer l’usage de TOTP par Client

Si l’usage de TOTP doit être forcé pour une application cliente spécifique, il est possible de conserver le flow “browser” par défaut et appliqué le nouveau flow créer précédemment uniquement pour un “Client” Keycloak (dans Clients > sélectionner le client > Advanced > Authentication flow overrides > Browser Flow). Ainsi, toutes les applications gérées par ce Client utilisent le nouveau flow et forcent l’usage de TOTP. Il n’est pas possible d’utiliser des flows différents pour les applications d’un même Client. Cela dit, la bonne pratique est d’ajouter un Client par application et d’éviter ainsi d’avoir plusieurs applications regroupées dans un même Client.

À noter que cette méthode est loin d’être optimale car il y a un risque que TOTP ne soit jamais demandé même pour les applications qui utilisent le nouveau flow.

1. un utilisateur s’authentifie pour une application A (qui utilise le flow par défaut et ne force pas TOTP) : authentification uniquement via login et mot de passe, pas de TOTP
2. Keycloak conserve la session de l’utilisateur dans un Cookie, il est considéré comme déjà authentifié et il n’aura pas besoin de s’authentifier pour accéder à d’autres applications (le principe du SSO)
3. ce même utilisateur s’authentifie à présent pour une autre application B (qui utilise le nouveau flow forçant l’usage de TOTP) : Keycloak ne demandera rien à cet utilisateur et le redirigera directement vers l’application B car celui-ci a déjà une session auprès de Keycloak

Un contournement à ce problème serait de supprimer la partie Cookie du nouveau flow, mais cela engendre la perte du SSO pour les applications utilisant ce flow. Pas de solution miracle alors ? Et bien pas en l’état … mais pour avoir quelque chose de plus robuste et standard, il faut aller voir du côté du Step-Up Authentication et du Level of Authentication. Notions qui feront l’objet d’un prochain article qui sera disponible rapidement (on croise les doigts !).

# Ce qu’il faut retenir

• Keycloak propose en standard une implémentation de TOTP comme second facteur d’authentification
• TOTP nécessite l’usage d’une application tiers gérant l’algorithme TOTP (application sur smartphone ou ordinateur)
• Par défaut, Keycloak permet l’usage de TOTP à l’initiative de l’utilisateur …
• … mais il est possible de forcer l’usage de TOTP avec un peu de configuration