Adaptive and Risk-Based Authentication

mkdir -p ~/ib-labs/ib-risk-engine
cd ~/ib-labs/ib-risk-engine
python3.11 -m venv .venv
source .venv/bin/activate

cat > requirements.txt <<'EOF'
flask==3.0.3
redis==5.0.4
gunicorn==22.0.0
EOF

pip install -r requirements.txt

# geo_data.py
# Purpose: a small, fully reproducible IP-to-location table for lab use.
# Real production risk engines use a licensed GeoIP database (for example
# MaxMind GeoLite2 or GeoIP2); this lab intentionally avoids that licensing
# and connectivity dependency, and the mapping below covers only the
# addresses this lab's test scripts actually use.

DEMO_IP_LOCATIONS = {
    "51.36.10.20":  {"city": "Manchester, UK",  "lat": 53.4808, "lon": -2.2426},
    "51.36.10.21":  {"city": "Manchester, UK",  "lat": 53.4808, "lon": -2.2426},
    "197.210.55.9": {"city": "Lagos, Nigeria",  "lat": 6.5244,  "lon": 3.3792},
    "203.0.113.44": {"city": "Singapore",       "lat": 1.3521,  "lon": 103.8198},
}

# IP ranges/addresses treated as known-bad for this lab. In production this
# would be sourced from a threat intelligence feed, refreshed regularly.
DEMO_BAD_REPUTATION_IPS = {
    "198.51.100.66",
}


def lookup(ip):
    return DEMO_IP_LOCATIONS.get(ip)


def is_bad_reputation(ip):
    return ip in DEMO_BAD_REPUTATION_IPS

# risk_logic.py
# Purpose: compute a risk score from impossible travel velocity, new
# device/IP combinations, and IP reputation.

import json
import math
import time
import redis
import geo_data

r = redis.Redis(host="ib-redis", port=6379, decode_responses=True)
HISTORY_TTL_SECONDS = 3600


def _haversine_km(lat1, lon1, lat2, lon2):
    radius_km = 6371.0
    phi1, phi2 = math.radians(lat1), math.radians(lat2)
    d_phi = math.radians(lat2 - lat1)
    d_lambda = math.radians(lon2 - lon1)
    a = math.sin(d_phi / 2) ** 2 + math.cos(phi1) * math.cos(phi2) * math.sin(d_lambda / 2) ** 2
    return 2 * radius_km * math.asin(math.sqrt(a))


def _history_key(username):
    return f"login-history:{username}"


def score_login(username, source_ip, user_agent):
    factors = []
    score = 0

    history_raw = r.get(_history_key(username))
    current_location = geo_data.lookup(source_ip)
    now = time.time()

    if history_raw:
        history = json.loads(history_raw)
        previous_location = geo_data.lookup(history["ip"])

        if current_location and previous_location:
            distance_km = _haversine_km(
                previous_location["lat"], previous_location["lon"],
                current_location["lat"], current_location["lon"],
            )
            elapsed_hours = max((now - history["timestamp"]) / 3600.0, 0.01)
            velocity_kmh = distance_km / elapsed_hours

            # Commercial airline cruising speed is roughly 900 km/h; anything
            # meaningfully above that between two logins is not physically
            # plausible travel by the same person.
            if velocity_kmh > 900:
                score += 60
                factors.append(
                    f"impossible_travel: {distance_km:.0f}km in "
                    f"{elapsed_hours*60:.0f} minutes ({velocity_kmh:.0f} km/h)"
                )

        seen_before = (history["ip"] == source_ip and history["user_agent"] == user_agent)
        if not seen_before:
            score += 20
            factors.append("new_device_or_network")
    else:
        # First login ever seen for this user carries a small, non-blocking
        # amount of risk since there is no baseline to compare against.
        score += 10
        factors.append("no_prior_history")

    if geo_data.is_bad_reputation(source_ip):
        score += 40
        factors.append("known_bad_reputation_ip")

    r.setex(
        _history_key(username),
        HISTORY_TTL_SECONDS,
        json.dumps({"ip": source_ip, "user_agent": user_agent, "timestamp": now}),
    )

    return {"score": min(score, 100), "factors": factors}

# app.py
import os
from flask import Flask, request, jsonify
import risk_logic

app = Flask(__name__)
BEARER_TOKEN = os.environ.get("RISK_ENGINE_BEARER_TOKEN", "change-me-in-production")


@app.before_request
def check_auth():
    if request.path == "/healthz":
        return
    auth = request.headers.get("Authorization", "")
    if auth != f"Bearer {BEARER_TOKEN}":
        return jsonify({"error": "unauthorised"}), 401


@app.get("/healthz")
def healthz():
    return jsonify({"status": "ok"})


@app.post("/score")
def score():
    body = request.get_json(force=True)
    result = risk_logic.score_login(
        username=body["username"],
        source_ip=body["sourceIp"],
        user_agent=body.get("userAgent", "unknown"),
    )
    return jsonify(result)


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8090)

# Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py risk_logic.py geo_data.py .
EXPOSE 8090
CMD ["gunicorn", "--bind", "0.0.0.0:8090", "--workers", "2", "app:app"]

  ib-redis:
    image: redis:7.2-alpine
    container_name: ib-redis
    networks:
      - ib-lab-net

  ib-risk-engine:
    build: ./ib-risk-engine
    container_name: ib-risk-engine
    networks:
      - ib-lab-net
    environment:
      RISK_ENGINE_BEARER_TOKEN: "REPLACE_WITH_STRONG_TOKEN"
    ports:
      - "8090:8090"
    depends_on:
      - ib-redis

docker compose up -d --build ib-redis ib-risk-engine

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>uk.co.identitybytes</groupId>
  <artifactId>risk-based-authenticator</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

  <properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <keycloak.version>24.0.5</keycloak.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.keycloak</groupId>
      <artifactId>keycloak-server-spi</artifactId>
      <version>${keycloak.version}</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.keycloak</groupId>
      <artifactId>keycloak-server-spi-private</artifactId>
      <version>${keycloak.version}</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.keycloak</groupId>
      <artifactId>keycloak-services</artifactId>
      <version>${keycloak.version}</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>
</project>

package uk.co.identitybytes.risk;

import org.keycloak.authentication.Authenticator;
import org.keycloak.authentication.AuthenticationFlowContext;
import org.keycloak.authentication.AuthenticationFlowError;
import org.keycloak.models.KeycloakSession;
import org.keycloak.models.RealmModel;
import org.keycloak.models.UserModel;
import org.keycloak.events.EventType;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.Map;
import java.util.HashMap;
import javax.json.Json;
import javax.json.JsonObject;

// Calls the ib-risk-engine service after password validation and decides
// whether to continue the flow, force step-up MFA, or deny the login.
public class RiskBasedAuthenticator implements Authenticator {

    private static final Duration TIMEOUT = Duration.ofSeconds(2);

    @Override
    public void authenticate(AuthenticationFlowContext context) {
        RealmModel realm = context.getRealm();
        UserModel user = context.getUser();
        String riskEngineUrl = realm.getAttribute("risk-engine-url");
        String bearerToken = realm.getAttribute("risk-engine-bearer-token");

        String sourceIp = context.getConnection().getRemoteAddr();
        String userAgent = context.getHttpRequest().getHttpHeaders()
                .getRequestHeaders().getFirst("User-Agent");

        try {
            JsonObject requestBody = Json.createObjectBuilder()
                    .add("username", user.getUsername())
                    .add("sourceIp", sourceIp)
                    .add("userAgent", userAgent != null ? userAgent : "unknown")
                    .build();

            HttpClient client = HttpClient.newBuilder().connectTimeout(TIMEOUT).build();
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(riskEngineUrl + "/score"))
                    .timeout(TIMEOUT)
                    .header("Authorization", "Bearer " + bearerToken)
                    .header("Content-Type", "application/json")
                    .POST(HttpRequest.BodyPublishers.ofString(requestBody.toString()))
                    .build();

            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            JsonObject result = Json.createReader(new java.io.StringReader(response.body())).readObject();
            int score = result.getInt("score");

            applyDecision(context, score, result.getJsonArray("factors").toString());

        } catch (Exception e) {
            // Fail closed: if the risk engine is unreachable or returns an
            // error, treat the login as high risk rather than allowing it
            // through unchecked.
            raiseAdminEvent(context, 100, "risk_engine_unreachable: " + e.getMessage());
            context.getEvent().error("risk_engine_unreachable");
            context.challenge(context.form()
                    .setError("Unable to verify login risk. Please contact IT support.")
                    .createErrorPage(javax.ws.rs.core.Response.Status.SERVICE_UNAVAILABLE));
            context.failure(AuthenticationFlowError.INTERNAL_ERROR);
        }
    }

    private void applyDecision(AuthenticationFlowContext context, int score, String factors) {
        if (score < 30) {
            context.success();
        } else if (score < 70) {
            raiseAdminEvent(context, score, factors);
            // Marks the session so the subsequent OTP execution in the flow
            // (built in Lab 05) is required rather than skipped, even for
            // a user who might otherwise be within their OTP "remember me"
            // window.
            context.getAuthenticationSession().setAuthNote("force_otp_step_up", "true");
            context.attempted();
        } else {
            raiseAdminEvent(context, score, factors);
            context.getEvent().error("risk_denied_high_score");
            context.challenge(context.form()
                    .setError("This login was blocked for security review. Contact IT support.")
                    .createErrorPage(javax.ws.rs.core.Response.Status.FORBIDDEN));
            context.failure(AuthenticationFlowError.ACCESS_DENIED);
        }
    }

    private void raiseAdminEvent(AuthenticationFlowContext context, int score, String factors) {
        context.getEvent()
                .event(EventType.CUSTOM_REQUIRED_ACTION)
                .detail("risk_score", String.valueOf(score))
                .detail("risk_factors", factors)
                .success();
    }

    @Override
    public void action(AuthenticationFlowContext context) {
        // No user-facing form for this authenticator; it acts purely on
        // the previous step's credential and the risk engine's response.
    }

    @Override
    public boolean requiresUser() {
        return true;
    }

    @Override
    public boolean configuredFor(KeycloakSession session, RealmModel realm, UserModel user) {
        return true;
    }

    @Override
    public void setRequiredActions(KeycloakSession session, RealmModel realm, UserModel user) {
    }

    @Override
    public void close() {
    }
}

package uk.co.identitybytes.risk;

import org.keycloak.Config;
import org.keycloak.authentication.Authenticator;
import org.keycloak.authentication.AuthenticatorFactory;
import org.keycloak.models.AuthenticationExecutionModel;
import org.keycloak.models.KeycloakSession;
import org.keycloak.models.KeycloakSessionFactory;
import org.keycloak.provider.ProviderConfigProperty;

import java.util.List;

public class RiskBasedAuthenticatorFactory implements AuthenticatorFactory {

    public static final String PROVIDER_ID = "risk-based-authenticator";
    private static final RiskBasedAuthenticator SINGLETON = new RiskBasedAuthenticator();

    @Override
    public String getId() {
        return PROVIDER_ID;
    }

    @Override
    public String getDisplayType() {
        return "Risk-Based Step-Up (Identity Bytes)";
    }

    @Override
    public String getReferenceCategory() {
        return "risk";
    }

    @Override
    public boolean isConfigurable() {
        return true;
    }

    @Override
    public AuthenticationExecutionModel.Requirement[] getRequirementChoices() {
        return new AuthenticationExecutionModel.Requirement[]{
                AuthenticationExecutionModel.Requirement.REQUIRED,
                AuthenticationExecutionModel.Requirement.DISABLED,
        };
    }

    @Override
    public boolean isUserSetupAllowed() {
        return false;
    }

    @Override
    public String getHelpText() {
        return "Scores login risk via an external engine and forces step-up MFA or denies access based on the result.";
    }

    @Override
    public List<ProviderConfigProperty> getConfigProperties() {
        return List.of();
    }

    @Override
    public Authenticator create(KeycloakSession session) {
        return SINGLETON;
    }

    @Override
    public void init(Config.Scope config) {
    }

    @Override
    public void postInit(KeycloakSessionFactory factory) {
    }

    @Override
    public void close() {
    }
}

# src/main/resources/META-INF/services/org.keycloak.authentication.AuthenticatorFactory
uk.co.identitybytes.risk.RiskBasedAuthenticatorFactory

cd ~/ib-labs/risk-based-authenticator
mvn clean package

# Copy the JAR to both nodes' providers directory
docker cp target/risk-based-authenticator-1.0.0.jar ib-keycloak-1:/opt/keycloak/providers/
docker cp target/risk-based-authenticator-1.0.0.jar ib-keycloak-2:/opt/keycloak/providers/

# Rebuild the Keycloak distribution inside each container so the new
# provider is registered, one node at a time so ib-lb keeps routing
# traffic to the other node throughout.
docker exec -it ib-keycloak-1 /opt/keycloak/bin/kc.sh build
docker restart ib-keycloak-1

# Wait for ib-keycloak-1 to report healthy before touching the second node
until curl -sk https://localhost:8443/health/ready | grep -q UP; do sleep 3; done

docker exec -it ib-keycloak-2 /opt/keycloak/bin/kc.sh build
docker restart ib-keycloak-2

docker exec -it ib-keycloak-1 /opt/keycloak/bin/kcadm.sh update realms/northgate \
  -s 'attributes."risk-engine-url"=http://ib-risk-engine:8090' \
  -s 'attributes."risk-engine-bearer-token"=REPLACE_WITH_STRONG_TOKEN'

# Duplicate the existing browser flow so the original remains available
# as a rollback path
docker exec -it ib-keycloak-1 /opt/keycloak/bin/kcadm.sh create \
  authentication/flows/browser/copy -r northgate \
  -s newName="browser-risk-based"

# Add the new execution to the copied flow
docker exec -it ib-keycloak-1 /opt/keycloak/bin/kcadm.sh create \
  authentication/flows/browser-risk-based/executions/execution -r northgate \
  -s provider=risk-based-authenticator

# Set it to REQUIRED and position it after password validation, before OTP.
# In the Admin Console: Authentication, browser-risk-based, drag
# "Risk-Based Step-Up (Identity Bytes)" to sit directly beneath
# "Username Password Form" and above the Lab 05 "OTP Form" execution,
# then set its requirement to Required.

# Bind the new flow as the realm's active browser flow
docker exec -it ib-keycloak-1 /opt/keycloak/bin/kcadm.sh update \
  realms/northgate -s browserFlow=browser-risk-based