Skip to main content

Adding Humifortis to Keycloak: Step-by-Step Integration

· 4 min read
Humifortis Team
Identity Security

This guide walks through adding Humifortis adaptive authentication to an existing Keycloak installation. By the end, every login through your realm will be evaluated for risk and challenged or blocked automatically when the score warrants it.

Prerequisites​

  • Keycloak 21+ running (self-hosted or containerized)
  • Humifortis engine running and reachable from Keycloak (see Self-Hosted Deployment)
  • An API key from the Humifortis dashboard — Apps & Keys → New App

Step 1 — Download the Connector JAR​

Download the latest humifortis-keycloak-connector.jar from the GitHub releases page.

Step 2 — Install the JAR​

Place the JAR in Keycloak's providers directory so Keycloak picks it up on the next restart.

Bare-metal:

cp humifortis-keycloak-connector.jar /opt/keycloak/providers/

Docker / Docker Compose:

keycloak:
  image: quay.io/keycloak/keycloak:26.1
  volumes:
    - ./humifortis-keycloak-connector.jar:/opt/keycloak/providers/humifortis-keycloak-connector.jar:ro
  environment:
    HUMIFORTIS_API_KEY: "your-api-key-here"
    HUMIFORTIS_API_URL: "http://humifortis:8080/api/v1"
    HUMIFORTIS_FALLBACK_ALLOW: "true"

Step 3 — Set the Environment Variables​

HUMIFORTIS_API_KEY=your-api-key-here          # required
HUMIFORTIS_API_URL=https://demo.humifortis.com # default; change for self-hosted
HUMIFORTIS_TIMEOUT_MS=5000                     # optional, default 5000ms
HUMIFORTIS_FALLBACK_ALLOW=true                 # optional, fail-open by default

Step 4 — Restart Keycloak​

Keycloak must be restarted (or rebuilt) to load the new JAR.

# Docker Compose
docker compose restart keycloak

# Bare-metal
/opt/keycloak/bin/kc.sh build
/opt/keycloak/bin/kc.sh start

After restart, the Humifortis authenticators will appear in Authentication → Executions in the Keycloak admin console.

Step 5 — Configure the Authentication Flow​

  1. Go to Authentication in your realm
  2. Duplicate the built-in browser flow (never modify the built-in directly)
  3. In your copy, add these executions in order:
ExecutionPlacementRequirement
HumifortisDeviceCollectorAfter password form, before risk evalREQUIRED
HumifortisRiskAuthenticatorAfter credentialsREQUIRED
Conditional sub-flowAfter HumifortisRiskAuthenticatorCONDITIONAL
→ HumifortisHighCondition (condition)Inside sub-flowREQUIRED
→ HumifortisStepUpRouter (execution)Inside sub-flowREQUIRED
  1. Bind your new flow to the Browser Flow binding for the realm

Step 6 — Add the Event Listener​

The event listener captures background events (logout, password change, MFA updates) and sends them asynchronously to Humifortis for risk scoring.

  1. Go to Events → Config in your realm
  2. Under Event listeners, add humifortis
  3. Save

Step 7 — Test It​

Trigger a test login. In the Humifortis dashboard under Entities, find your test user — you should see a new event and an updated risk score.

To simulate a risk escalation without real traffic, use the API directly:

# Send a few failed logins for a test user
for i in {1..6}; do
  curl -s -X POST https://your-humifortis-instance/api/v1/events \
    -H "X-API-Key: your-api-key" \
    -H "Content-Type: application/json" \
    -d "{\"event\":{\"event_id\":\"test-$i\",\"entity_id\":\"user:keycloak:myrealm:test-user-id\",\"entity_type\":\"user\",\"event_type\":\"auth.login.failed\",\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"metadata\":{\"ip_address\":\"203.0.113.42\"}}}"
done

# Query the risk score
curl https://your-humifortis-instance/api/v1/risk/user:keycloak:myrealm:test-user-id \
  -H "X-API-Key: your-api-key"

On the next login from that user, the connector will call POST /evaluate, receive CHALLENGE_MFA (or BLOCK if the score is CRITICAL), and enforce accordingly.

What Happens at Login​

Once installed, every login through the flow goes through:

  1. HumifortisDeviceCollector — silently gathers 40+ device signals in the background
  2. HumifortisRiskAuthenticator — sends the full login context to POST /evaluate, receives ALLOW, CHALLENGE_MFA, or BLOCK
  3. If CHALLENGE_MFA — HumifortisHighCondition triggers HumifortisStepUpRouter, which selects the best available MFA method and challenges the user
  4. The event listener records the outcome and sends it back to the engine for the next evaluation

That's it. No changes to your applications, no new login pages, no user-visible friction unless the risk score warrants it.

Next Steps​