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.
Instale el proveedor login-hint de XFA en Keycloak
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>.jarresultante en el directorioprovidersde 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
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).
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.
Añada XFA al Post Login Flow
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 Redirector: abra sus Settings y ponga Default Identity Provider en
XFA.
2. Asócielo como Post Login Flow
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.
Implemente XFA en más grupos
Ejecute el flujo posterior al inicio de sesión de XFA solo para los grupos marcados con xfa-test=true. Empiece con un pequeño grupo de prueba y marque más grupos después de probarlo. Los usuarios sin ese atributo en su cuenta o sus grupos inician sesión sin esta verificación de dispositivo de XFA.
Use Keycloak 26.x con el proveedor login-hint instalado anteriormente. La condición de atributos de grupo está disponible en Keycloak 26.0; la compilación actual del proveedor está destinada a 26.7.2. En una integración nueva, configure este alcance antes de asociar el flujo posterior al inicio de sesión.
- Cree un pequeño grupo, como
XFA test, en Groups. - Añada el atributo
xfa-testcon el valortrueen la pestaña Attributes de ese grupo. - Guarde el atributo del grupo con Save.
- Añada un usuario de prueba sin permisos de administrador al grupo mediante Users > el usuario > Groups > Join Group.
- Abra Authentication > Flows >
XFA Device Verification. - Cree un subflujo de tipo Generic llamado
XFA groupscon Add sub-flow. - Establezca Requirement del subflujo en Conditional.
- Añada Condition - user attribute dentro de ese subflujo con Add condition.
- Establezca Requirement de la condición en Required.
- Abra Settings de la condición con el icono del engranaje.
- Configure la condición con Alias
xfa-groups-condition, Attribute namexfa-test, Expected attribute valuetruey Include group attributes activado. Deje Negate output y regex desactivados. - Guarde la condición con Save.
- Mueva IdP Redirector (login_hint) al subflujo, debajo de la condición, mediante su asa de arrastre.
- Mueva Identity Provider Redirector al subflujo, debajo de IdP Redirector (login_hint).
- Compruebe que ambos redirectores estén en Required, conserven Default Identity Provider
XFAy ninguno permanezca fuera del subflujo condicional. - Pruebe un nuevo inicio de sesión con el miembro del grupo sin permisos de administrador. El usuario debería llegar a XFA después de su inicio de sesión habitual.
- Pruebe un nuevo inicio de sesión con un usuario ajeno a los grupos marcados. Ese usuario debería completar el inicio de sesión sin esta verificación de XFA.
- Añada
xfa-test=truea los Attributes del siguiente grupo que quiera incluir. - Guarde el atributo del grupo con Save.
- Repita las pruebas de inicio de sesión antes de añadir otro grupo.
Use este marcador solo en los grupos. La condición también lee los atributos del usuario, por lo que establecer el mismo marcador directamente en un usuario también lo incluye. Si su configuración inicial ya creó XFA test y el subflujo condicional, consérvelos y continúe en los pasos de prueba.