Configure XFA as an Authentication Factor on Keycloak
Configure XFA on Keycloak to add device verification after the user authenticates. XFA runs as a post-login step, checks the device against your configured policy, and lets the login continue when the device decision allows access. Use it to confirm the required settings and test the authentication flow before rollout.
Note: This guide assumes that you have an account set up with XFA for your organization and you're an admin for that organization on both XFA and Keycloak. If you do not have an account for XFA, you can create one at https://dashboard.xfa.tech/signup.
Create an integration in XFA Dashboard
After logging in to the XFA Dashboard, navigate to the Enforcement page, click on New and select Keycloak as the integration type.
The page shows several values you will need during the next steps (Client ID, Client Secret and the OpenID Connect endpoints). It also contains a Redirect URI field that you will fill with a value from Keycloak during the steps below.
Keep this page open during the next steps.
Install the XFA login-hint provider on Keycloak
Keycloak does not, by default, pass the identity of the already-authenticated user to an external Identity Provider. XFA needs that identity (the user's email) to know which device to verify. A small open-source Keycloak provider takes care of this: it reads the authenticated user from the session and sets the login_hint parameter on the redirect to XFA. The provider is available at github.com/gl-ventures/xfa-keycloak-login-hint-mapper.
-
Clone the provider repository and build it (or obtain the pre-built jar):
mvn clean package -
Copy the resulting
login-hint-idp-<version>.jarinto your Keycloakprovidersdirectory:cp target/login-hint-idp-*.jar /opt/keycloak/providers/ -
Rebuild Keycloak so the provider is registered, then restart the running instance for it to take effect:
/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
The provider sources the email from the authenticated Keycloak session (getAuthenticatedUser()), not from a parameter supplied by the client. This guarantees that the device verified by XFA belongs to the user who actually logged in.
Create the XFA Identity Provider in Keycloak
In the Keycloak Admin Console, select your realm and navigate to Identity providers. Click Add provider and choose OpenID Connect v1.0.
Fill out the following, copying the values from the XFA Dashboard page you left open.
Provider
- Alias:
XFA(this exact alias is referenced in the Post Login Flow below) - Display name:
XFA
OpenID Connect settings
- Switch Use discovery endpoint off. This reveals the fields where you enter the endpoints manually.
- Authorization URL
- Token URL
- User Info URL
- Issuer
- Switch Validate Signatures on to reveal the JWKS URL field, then fill in the JWKS URL.
- Set Client authentication to Client secret sent in the request body.
- Client ID
- Client Secret
Save the provider. Keycloak now shows a Redirect URI for this Identity Provider (it looks like https://<keycloak-host>/realms/<realm>/broker/XFA/endpoint). Copy that value back into the Redirect URI field on the XFA Dashboard page and save the XFA integration.
Advanced settings
Open the provider you just created and expand the Advanced section (collapsed by default):
- Set Default Scopes to
openid email profile. - Switch Pass login_hint on so Keycloak forwards the authenticated user's email (set by the provider installed above) to XFA.
Leave the default mappers in place. XFA returns the user's email (and sub) in the signed token, which Keycloak uses to match the verification result to the already-authenticated user.
Add XFA to the Post Login Flow
XFA must run after the user has authenticated, so it is configured as a Post Login Flow on your primary authentication.
1. Create an authentication flow
In the Admin Console, navigate to Authentication > Flows and create a new flow (for example, XFA Device Verification) of type Basic flow.
Add two executions, both set to Required, in this order:
- IdP Redirector (login_hint): provided by the jar you installed. Open its Settings (the gear icon) and set Default Identity Provider to
XFA. - Identity Provider Redirector: open its Settings and set Default Identity Provider to
XFA.
2. Bind it as the Post Login Flow
Open the primary authentication that runs the first login step (for example, your Microsoft Identity Provider under Identity providers), go to its advanced settings and set Post login flow to the XFA Device Verification flow you just created.
Now, after a user completes their regular login, Keycloak redirects them to XFA to verify their device before the session is established.
Roll XFA out to more groups
Run the XFA post-login flow only for groups marked with xfa-test=true. Start with a small test group, then mark more groups after testing. Users without that attribute on their user or groups sign in without this XFA device check.
Use Keycloak 26.x with the login-hint provider installed above. The group-attribute condition is available in Keycloak 26.0; the current provider build targets 26.7.2. For a new integration, configure this scope before binding the post-login flow.
- Create a small group, such as
XFA test, under Groups. - Add the attribute
xfa-testwith valuetrueon that group's Attributes tab. - Save the group attribute with Save.
- Add a non-admin test user to the group through Users > the user > Groups > Join Group.
- Open Authentication > Flows >
XFA Device Verification. - Create a Generic sub-flow named
XFA groupswith Add sub-flow. - Set the sub-flow's Requirement to Conditional.
- Add Condition - user attribute inside that sub-flow with Add condition.
- Set the condition's Requirement to Required.
- Open the condition's Settings with the gear icon.
- Configure the condition with Alias
xfa-groups-condition, Attribute namexfa-test, Expected attribute valuetrueand Include group attributes enabled. Leave Negate output and regex disabled. - Save the condition with Save.
- Move IdP Redirector (login_hint) into the sub-flow, below the condition, using its drag handle.
- Move Identity Provider Redirector into the sub-flow, below IdP Redirector (login_hint).
- Verify that both redirectors are Required, both retain Default Identity Provider
XFA, and neither remains outside the conditional sub-flow. - Test a fresh sign-in with the non-admin group member. The user should reach XFA after their regular sign-in.
- Test a fresh sign-in with a user outside the marked groups. That user should complete sign-in without this XFA check.
- Add
xfa-test=trueto the Attributes of the next group you want to include. - Save the group attribute with Save.
- Repeat the sign-in tests before adding another group.
Keep this marker on groups only. The condition also reads user attributes, so setting the same marker directly on a user includes that user too. If your initial setup already created XFA test and the conditional sub-flow, keep them and continue at the testing steps.