Configurar XFA como factor de autenticación en Keycloak

Configure XFA en Keycloak para añadir la verificación del dispositivo después de que el usuario se autentique. XFA se ejecuta como paso posterior al inicio de sesión, compara el dispositivo con la política que haya configurado y deja continuar el inicio de sesión cuando la decisión sobre el dispositivo permite el acceso. Úselo para confirmar los ajustes necesarios y probar el flujo de autenticación antes del despliegue.

Nota: esta guía da por supuesto que su organización tiene una cuenta de XFA y que usted es administrador de esa organización tanto en XFA como en Keycloak. Si todavía no tiene una cuenta de XFA, puede crear una en https://dashboard.xfa.tech/signup.

Cree una integración en el panel de control de XFA

Después de iniciar sesión en el panel de control de XFA, vaya a la página Enforcement, haga clic en Nuevo y seleccione Keycloak como tipo de integración.

La página muestra varios valores que necesitará en los pasos siguientes (Client ID, Client Secret y los endpoints de OpenID Connect). También contiene un campo Redirect URI que rellenará con un valor de Keycloak en los pasos que se describen más abajo.

Mantenga esta página abierta durante los pasos siguientes.

De forma predeterminada, Keycloak no transmite la identidad del usuario ya autenticado a un Identity Provider externo. XFA necesita esa identidad (el correo electrónico del usuario) para saber qué dispositivo debe verificar. De eso se encarga un pequeño proveedor de código abierto para Keycloak: lee el usuario autenticado de la sesión y añade el parámetro login_hint a la redirección hacia XFA. El proveedor está disponible en github.com/gl-ventures/xfa-keycloak-login-hint-mapper.

Clone el repositorio del proveedor y compílelo (u obtenga el jar ya compilado):
```
mvn clean package
```
Copie el archivo login-hint-idp-<version>.jar resultante en el directorio providers de su Keycloak:
```
cp target/login-hint-idp-*.jar /opt/keycloak/providers/
```

Vuelva a compilar Keycloak para que el proveedor quede registrado y reinicie después la instancia en ejecución para que surta efecto:

/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

Por qué hace falta

El proveedor toma el correo electrónico de la sesión autenticada de Keycloak (getAuthenticatedUser()), no de un parámetro facilitado por el cliente. Así se garantiza que el dispositivo que verifica XFA pertenece al usuario que realmente ha iniciado sesión.

Cree el Identity Provider de XFA en Keycloak

En la consola de administración de Keycloak, seleccione su realm y vaya a Identity providers. Haga clic en Add provider y elija OpenID Connect v1.0.

Rellene lo siguiente, copiando los valores de la página del panel de control de XFA que ha dejado abierta.

Provider

Alias: XFA (este alias exacto se usa en el Post Login Flow más abajo)
Display name: XFA

Ajustes de OpenID Connect

Desactive Use discovery endpoint. Así aparecen los campos en los que introduce los endpoints manualmente.
Authorization URL
Token URL
User Info URL
Issuer
Active Validate Signatures para que aparezca el campo JWKS URL y rellene después la JWKS URL.
Ponga Client authentication en Client secret sent in the request body.
Client ID
Client Secret

Guarde el proveedor. Keycloak muestra ahora una Redirect URI para este Identity Provider (tiene el aspecto de https://<keycloak-host>/realms/<realm>/broker/XFA/endpoint). Copie ese valor en el campo Redirect URI de la página del panel de control de XFA y guarde la integración de XFA.

Configuración avanzada

Abra el proveedor que acaba de crear y despliegue la sección Advanced (contraída de forma predeterminada):

Ponga Default Scopes en openid email profile.
Active Pass login_hint para que Keycloak transmita a XFA el correo electrónico del usuario autenticado (establecido por el proveedor instalado más arriba).

Asignación de atributos

Deje los mappers predeterminados tal como están. XFA devuelve el email (y el sub) del usuario en el token firmado, que Keycloak usa para asociar el resultado de la verificación al usuario ya autenticado.

XFA tiene que ejecutarse después de que el usuario se haya autenticado, así que se configura como Post Login Flow en su autenticación principal.

1. Cree un flujo de autenticación

En la consola de administración, vaya a Authentication > Flows y cree un nuevo flujo (por ejemplo, XFA Device Verification) de tipo Basic flow.

Añada dos ejecuciones, ambas marcadas como Required, en este orden:

IdP Redirector (login_hint): lo aporta el jar que ha instalado. Abra sus Settings (el icono del engranaje) y ponga Default Identity Provider en XFA.
Identity Provider Redirect: abra sus Settings y ponga Default Identity Provider en XFA.

Abra la autenticación principal que ejecuta el primer paso de inicio de sesión (por ejemplo, su Identity Provider de Microsoft en Identity providers), vaya a sus ajustes avanzados y ponga Post login flow en el flujo XFA Device Verification que acaba de crear.

Ahora, cuando un usuario completa su inicio de sesión habitual, Keycloak lo redirige a XFA para verificar su dispositivo antes de establecer la sesión.

Configuración avanzada

Para ajustes más avanzados, como limitar el factor a determinados usuarios o activar XFA solo en ciertos casos, use los autenticadores condicionales de Keycloak dentro del flujo XFA Device Verification y consulte la documentación de Keycloak.