Keycloak ​

The QuantAuth Keycloak SPI approves Keycloak logins through the QuantAuth mobile app. It can be used after a password as a second factor or after username discovery as a password replacement.

The provider makes all QuantAuth requests server-side and verifies the signed QuantAuth response before completing the Keycloak authentication flow.

Compatibility ​

• Keycloak 26.7.1
• Java 21
• QuantAuth API https://api.quantauth.app/

Keycloak's Authenticator SPI is internal. Use the documented Keycloak version and test the provider before upgrading Keycloak.

Download ​

Download the latest released provider JAR:

curl --fail --location \
  https://get.quantauth.com/esaqa/quantauth/quantauth-keycloak-spi/latest/quantauth-keycloak-spi.jar \
  --output quantauth-keycloak-spi.jar

The release SBOM is available at:

https://get.quantauth.com/esaqa/quantauth/quantauth-keycloak-spi/latest/sbom.json

Versioned releases use the same filenames below a tag directory such as v1.0.0 instead of latest.

Install in a Keycloak container ​

Add the JAR before running Keycloak's build command:

FROM quay.io/keycloak/keycloak:26.7.1 AS builder

COPY --chown=keycloak:keycloak quantauth-keycloak-spi.jar \
    /opt/keycloak/providers/quantauth-keycloak-spi.jar

RUN touch -m --date=@1743465600 \
        /opt/keycloak/providers/quantauth-keycloak-spi.jar && \
    /opt/keycloak/bin/kc.sh build --db=postgres

FROM quay.io/keycloak/keycloak:26.7.1

COPY --from=builder /opt/keycloak/ /opt/keycloak/
ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]

Build and deploy this image using the same Keycloak build options as your production environment. Start optimized installations with start --optimized.

Install in an existing Keycloak installation ​

Copy the JAR into the provider directory and rebuild Keycloak:

cp quantauth-keycloak-spi.jar /opt/keycloak/providers/
touch -m --date=@1743465600 \
  /opt/keycloak/providers/quantauth-keycloak-spi.jar
/opt/keycloak/bin/kc.sh build

Restart Keycloak after the build. The QuantAuth execution should then be available under Authentication > Flows.

User requirements ​

The Keycloak user must have:

• an email address enrolled with QuantAuth;
• a verified Keycloak email when Require verified Keycloak email is enabled;
• a unique email address when password replacement is used.

Password replacement refuses to run in realms that allow duplicate email addresses because a QuantAuth identity must map to exactly one Keycloak user.

Configure second factor ​

1. Open Authentication > Flows in the Keycloak Admin Console.
2. Copy the built-in Browser flow.
3. Add the QuantAuth execution after Username Password Form.
4. Set both executions to REQUIRED.
5. Open the QuantAuth execution's configuration and select SECOND_FACTOR mode.

The relevant section of the flow should look like this:

Username Password Form    REQUIRED
QuantAuth                 REQUIRED

The user first proves the Keycloak password and then approves the login in the QuantAuth app.

Configure password replacement ​

Use Keycloak's Username Form, not Username Password Form:

Username Form             REQUIRED
QuantAuth                 REQUIRED

Configure the QuantAuth execution with PASSWORD_REPLACEMENT mode. The username form resolves the Keycloak user before QuantAuth reads the user's verified email.

Authenticator settings ​

An API key is not required. Without one, the provider uses QuantAuth's public email-request flow and public rate limit. If an API key is configured, Keycloak stores it as secret authenticator configuration and requests use the registered application's configured quota.

Do not commit realm exports containing an API key. Restrict access to realm administration, Keycloak database backups, and exports.

Enable QuantAuth for selected users or groups ​

Add this attribute to selected users or groups:

quantauth-required=true

Place QuantAuth in a CONDITIONAL subflow with Keycloak's built-in Condition - user attribute execution:

Conditional QuantAuth subflow    CONDITIONAL
  Condition - user attribute     REQUIRED
  QuantAuth                       REQUIRED

Configure the condition with:

Attribute name: quantauth-required
Expected value: true
Include group attributes: On
Negate output: Off

For conditional password replacement, add a second conditional subflow with the same condition, Negate output: On, and a required Password Form fallback:

Username Form                          REQUIRED
Conditional QuantAuth subflow          CONDITIONAL
  Condition - user attribute           REQUIRED (negate Off)
  QuantAuth                             REQUIRED
Conditional password fallback subflow  CONDITIONAL
  Condition - user attribute           REQUIRED (negate On)
  Password Form                         REQUIRED

Never configure conditional password replacement without the password fallback. A non-matching user must still prove a credential.

Bind the flow ​

Bind the custom flow either realm-wide under Authentication > Bindings or as a browser-flow override for a specific client.

Do not place Cookie before a client-specific QuantAuth branch when every login must require fresh approval. An existing Keycloak SSO session could otherwise satisfy the cookie execution and bypass QuantAuth.

Development overrides ​

Production uses https://api.quantauth.app/ and the built-in production authority public key. Developers can override these fixed process environment variables when testing against a local QuantAuth environment:

QUANTAUTH_API_URL=http://localhost:8000/
QUANTAUTH_AUTHORITY_PUBLIC_KEY=<development-64-character-hex-public-key>

Do not override either value in production.

Update or remove the provider ​

To update, replace the existing JAR with the new release, run kc.sh build with your production build options, and restart Keycloak.

To remove the provider, remove its JAR, rebuild Keycloak, and remove QuantAuth executions from authentication flows before restarting.

Troubleshooting ​

• If QuantAuth is missing from the execution list, confirm the JAR is in /opt/keycloak/providers/, run kc.sh build, and restart Keycloak.
• If no mobile request appears, verify that the Keycloak email matches an email enrolled with QuantAuth.
• If the flow rejects a user immediately, check email verification and duplicate email settings.
• If signature verification fails, remove development authority-key overrides and confirm that the provider can reach https://api.quantauth.app/.