Skip to main content

Configure XFA as an Authentication Factor on Keycloak

To make sure that every device in your organization is secure, XFA can be configured on Keycloak to verify each device after the user has authenticated. XFA runs as an extra step in the Post Login Flow of your existing authentication, acting as an external OpenID Connect Identity Provider that performs device verification. This guide walks you through configuring XFA as that extra factor and enforcing its usage.

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.

  1. Clone the provider repository and build it (or obtain the pre-built jar):

    mvn clean package

  2. Copy the resulting login-hint-idp-<version>.jar into your Keycloak providers directory:

    cp target/login-hint-idp-*.jar /opt/keycloak/providers/

  3. 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
Why this is needed

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.
Attribute mapping

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:

  1. IdP Redirector (login_hint) — provided by the jar you installed. Open its Settings (the gear icon) and set Default Identity Provider to XFA.
  2. Identity Provider Redirect — 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.

Advanced Settings​

For more advanced settings, such as limiting the factor to certain users or only triggering XFA in certain cases, use Keycloak's conditional authenticators within the XFA Device Verification flow and refer to the Keycloak documentation.