Configurer XFA comme facteur d'authentification dans Keycloak

Configurez XFA dans Keycloak pour ajouter la vérification d'appareil après que l'utilisateur s'est authentifié. XFA s'exécute comme étape après la connexion, compare l'appareil à la politique configurée et laisse la connexion se poursuivre lorsque la décision sur l'appareil autorise l'accès. Utilisez cette page pour vérifier les réglages nécessaires et tester le parcours d'authentification avant le déploiement.

Remarque : ce guide part du principe que votre organisation dispose d'un compte XFA et que vous en êtes administrateur, aussi bien dans XFA que dans Keycloak. Si vous n'avez pas encore de compte XFA, vous pouvez en créer un sur https://dashboard.xfa.tech/signup.

Créer une intégration dans le tableau de bord XFA

Connectez-vous au tableau de bord XFA, allez sur la page Enforcement, cliquez sur Nouveau et choisissez Keycloak comme type d'intégration.

Cette page affiche plusieurs valeurs dont vous aurez besoin aux étapes suivantes (Client ID, Client Secret et les endpoints OpenID Connect). Elle contient aussi un champ Redirect URI, que vous remplirez plus bas avec une valeur venant de Keycloak.

Laissez cette page ouverte pendant les étapes suivantes.

Par défaut, Keycloak ne transmet pas l'identité de l'utilisateur déjà authentifié à un fournisseur d'identité externe. XFA a besoin de cette identité (l'adresse e-mail de l'utilisateur) pour savoir quel appareil vérifier. Un petit provider open source pour Keycloak s'en charge : il lit l'utilisateur authentifié dans la session et positionne le paramètre login_hint sur la redirection vers XFA. Vous trouverez ce provider sur github.com/gl-ventures/xfa-keycloak-login-hint-mapper.

Clonez le dépôt du provider et compilez-le (ou utilisez le jar prêt à l'emploi) :
```
mvn clean package
```
Copiez le fichier login-hint-idp-<version>.jar obtenu dans le répertoire providers de Keycloak :
```
cp target/login-hint-idp-*.jar /opt/keycloak/providers/
```

Reconstruisez Keycloak pour que le provider soit enregistré, puis redémarrez l'instance en cours pour l'activer :

/opt/keycloak/bin/kc.sh build
# then restart Keycloak, e.g. restart the service or container running it,
# or start it again directly:
/opt/keycloak/bin/kc.sh start

Pourquoi c'est nécessaire

Le provider récupère l'adresse e-mail dans la session Keycloak authentifiée (getAuthenticatedUser()), et non dans un paramètre fourni par le client. Vous avez ainsi la garantie que l'appareil vérifié par XFA appartient bien à l'utilisateur qui s'est réellement connecté.

Créer le fournisseur d'identité XFA dans Keycloak

Dans la Keycloak Admin Console, choisissez votre realm et allez dans Identity providers. Cliquez sur Add provider et choisissez OpenID Connect v1.0.

Remplissez les champs suivants avec les valeurs de la page du tableau de bord XFA que vous avez laissée ouverte.

Provider

Alias : XFA (c'est exactement cet alias qui est repris plus bas dans le Post Login Flow)
Display name: XFA

Paramètres OpenID Connect

Mettez Use discovery endpoint sur off. Les champs dans lesquels vous saisissez les endpoints à la main apparaissent alors.
Authorization URL
Token URL
User Info URL
Issuer
Mettez Validate Signatures sur on pour faire apparaître le champ JWKS URL, puis saisissez-y la JWKS URL.
Réglez Client authentication sur Client secret sent in the request body.
Client ID
Client Secret

Enregistrez le provider. Keycloak affiche maintenant une Redirect URI pour ce fournisseur d'identité (elle ressemble à https://<keycloak-host>/realms/<realm>/broker/XFA/endpoint). Recopiez cette valeur dans le champ Redirect URI de la page du tableau de bord XFA et enregistrez l'intégration XFA.

Paramètres avancés

Ouvrez le provider que vous venez de créer et dépliez la section Advanced (fermée par défaut) :

Réglez Default Scopes sur openid email profile.
Mettez Pass login_hint sur on, pour que Keycloak transmette à XFA l'adresse e-mail de l'utilisateur authentifié (positionnée par le provider installé ci-dessus).

Correspondance des attributs

Laissez les mappers par défaut en place. XFA renvoie l'adresse email (et sub) de l'utilisateur dans le token signé, ce qui permet à Keycloak de rattacher le résultat de la vérification à l'utilisateur déjà authentifié.

XFA doit s'exécuter après que l'utilisateur s'est authentifié, vous le configurez donc comme Post Login Flow sur votre authentification primaire.

1. Créer un flow d'authentification

Dans l'Admin Console, allez dans Authentication > Flows et créez un nouveau flow (par exemple XFA Device Verification) de type Basic flow.

Ajoutez deux executions, toutes les deux sur Required, dans cet ordre :

IdP Redirector (login_hint) : il vient du jar que vous avez installé. Ouvrez ses Settings (l'icône d'engrenage) et réglez Default Identity Provider sur XFA.
Identity Provider Redirect : ouvrez ses Settings et réglez Default Identity Provider sur XFA.

Ouvrez l'authentification primaire qui exécute la première étape de connexion (par exemple votre fournisseur d'identité Microsoft sous Identity providers), allez dans ses paramètres avancés et réglez Post login flow sur le flow XFA Device Verification que vous venez de créer.

Désormais, une fois qu'un utilisateur a terminé sa connexion habituelle, Keycloak le redirige vers XFA pour faire vérifier son appareil avant que la session ne soit établie.

Paramètres avancés

Pour des réglages plus avancés, comme limiter le facteur à certains utilisateurs ou ne déclencher XFA que dans certains cas, utilisez les conditional authenticators de Keycloak au sein du flow XFA Device Verification et reportez-vous à la documentation de Keycloak.