Keycloak single sign-on lab: one login, two apps, one logout

# apt update
# apt install -y openjdk-21-jre-headless python3-flask python3-jwt python3-requests curl jq
# java -version 2>&1 | head -1

...
openjdk version "21.0.12.1" 2026-08-18

# mkdir -p ~/kclab && cd ~/kclab
# curl -LO https://github.com/keycloak/keycloak/releases/download/26.8.1/keycloak-26.8.1.tar.gz
# curl -sL https://github.com/keycloak/keycloak/releases/download/26.8.1/keycloak-26.8.1.tar.gz.sha1; echo; sha1sum keycloak-26.8.1.tar.gz
# tar xzf keycloak-26.8.1.tar.gz && cd keycloak-26.8.1

f55701155746ed88e12b3e670d5fa03589e3013e
f55701155746ed88e12b3e670d5fa03589e3013e  keycloak-26.8.1.tar.gz

# export KC_BOOTSTRAP_ADMIN_USERNAME=admin KC_BOOTSTRAP_ADMIN_PASSWORD=lab-admin-pass JAVA_OPTS_APPEND=-Xmx512m
# bin/kc.sh start-dev --http-port 8080 > ~/kclab/keycloak.log 2>&1 &
# until curl -sf http://localhost:8080/realms/master > /dev/null; do sleep 3; done; echo ready
# grep -oE 'Keycloak [0-9.]+ on JVM .* started in [0-9.]+s' ~/kclab/keycloak.log

ready
Keycloak 26.8.1 on JVM (powered by Quarkus 3.40.1) started in 30.649s

# bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password lab-admin-pass
# bin/kcadm.sh create realms -s realm=sglab -s enabled=true
# bin/kcadm.sh create users -r sglab -s username=alice -s enabled=true -s firstName=Alice -s lastName=Lab -s email=alice@example.com -s emailVerified=true
# bin/kcadm.sh set-password -r sglab --username alice --new-password Lab-pass-2026
# curl -s http://localhost:8080/realms/sglab/.well-known/openid-configuration | jq '{issuer, authorization_endpoint, token_endpoint, end_session_endpoint}'

Logging into http://localhost:8080 as user admin of realm master
Created new realm with id 'sglab'
Created new user with id '68c7b294-145d-4751-99ad-9c8244d921ac'
{
  "issuer": "http://localhost:8080/realms/sglab",
  "authorization_endpoint": "http://localhost:8080/realms/sglab/protocol/openid-connect/auth",
  "token_endpoint": "http://localhost:8080/realms/sglab/protocol/openid-connect/token",
  "end_session_endpoint": "http://localhost:8080/realms/sglab/protocol/openid-connect/logout"
}

# for n in one:5001 two:5002; do app=${n%:*}; port=${n#*:}; bin/kcadm.sh create clients -r sglab -s clientId=app-$app -s secret=app-$app-secret -s "redirectUris=[\"http://localhost:$port/*\"]" -s "attributes={\"post.logout.redirect.uris\":\"http://localhost:$port/*\",\"backchannel.logout.url\":\"http://127.0.0.1:$port/backchannel-logout\"}"; done
# bin/kcadm.sh get clients -r sglab --fields clientId,publicClient,standardFlowEnabled --format csv | grep app-

"app-one",false,true
"app-two",false,true

# cd ~/kclab
# cat > app.py <<'EOF'
# app.py - a tiny OIDC web app for the StashGrid Keycloak SSO lab.
# Run two copies:  python3 app.py one 5001   and   python3 app.py two 5002
import json, secrets, sys, urllib.parse
import jwt, requests
from flask import Flask, redirect, request, session

NAME, PORT = sys.argv[1], int(sys.argv[2])
CLIENT_ID, SECRET = f"app-{NAME}", f"app-{NAME}-secret"
ISSUER = "http://localhost:8080/realms/sglab"
OIDC = f"{ISSUER}/protocol/openid-connect"
HERE = f"http://localhost:{PORT}"
jwks = jwt.PyJWKClient(f"{OIDC}/certs")
logged_out_sids = set()  # Keycloak tells us about logouts here

app = Flask(__name__)
app.secret_key = secrets.token_hex(16)
app.config["SESSION_COOKIE_NAME"] = f"sg_{CLIENT_ID}"  # one cookie per app

def check(token, **extra):  # verify signature, issuer and audience
    key = jwks.get_signing_key_from_jwt(token).key
    return jwt.decode(token, key, algorithms=["RS256"], audience=CLIENT_ID, issuer=ISSUER, **extra)

@app.route("/")
def home():
    c = session.get("claims")
    if c and c.get("sid") in logged_out_sids:
        session.clear(); c = None
    if not c:
        return f'<h1>App {NAME}</h1><p>Not logged in.</p><a href="/login">Log in</a>'
    return (f'<h1>App {NAME}</h1><p>Hello {c["preferred_username"]}, you are logged in.</p>'
            f'<a href="/logout">Log out</a><h2>ID token claims</h2><pre>{json.dumps(c, indent=2)}</pre>')

@app.route("/login")
def login():
    session["state"], session["nonce"] = secrets.token_urlsafe(16), secrets.token_urlsafe(16)
    q = {"client_id": CLIENT_ID, "response_type": "code", "scope": "openid profile email",
         "redirect_uri": f"{HERE}/callback", "state": session["state"], "nonce": session["nonce"]}
    return redirect(f"{OIDC}/auth?" + urllib.parse.urlencode(q))

@app.route("/callback")
def callback():
    if request.args.get("state") != session.pop("state", None):
        return "State mismatch, login refused.", 400
    tok = requests.post(f"{OIDC}/token", auth=(CLIENT_ID, SECRET), data={
        "grant_type": "authorization_code", "code": request.args["code"],
        "redirect_uri": f"{HERE}/callback"}).json()
    claims = check(tok["id_token"])
    if claims.get("nonce") != session.pop("nonce", None):
        return "Nonce mismatch, login refused.", 400
    session["claims"], session["id_token"] = claims, tok["id_token"]
    return redirect("/")

@app.route("/logout")
def logout():
    hint = session.get("id_token", "")
    session.clear()
    q = {"id_token_hint": hint, "post_logout_redirect_uri": f"{HERE}/"}
    return redirect(f"{OIDC}/logout?" + urllib.parse.urlencode(q))

@app.route("/backchannel-logout", methods=["POST"])
def backchannel_logout():
    claims = check(request.form["logout_token"], options={"require": ["sid"]})
    logged_out_sids.add(claims["sid"])
    print(f"app-{NAME}: Keycloak says session {claims['sid'][:8]}... logged out", flush=True)
    return "", 200

app.run(host="127.0.0.1", port=PORT)
EOF
# python3 app.py one 5001 > app-one.log 2>&1 &
# python3 app.py two 5002 > app-two.log 2>&1 &
# until curl -s http://localhost:5002/ > /dev/null; do sleep 1; done; curl -s http://localhost:5001/; echo; curl -s http://localhost:5002/; echo

<h1>App one</h1><p>Not logged in.</p><a href="/login">Log in</a>
<h1>App two</h1><p>Not logged in.</p><a href="/login">Log in</a>

# cd ~/kclab/keycloak-26.8.1
# USER_ID=$(bin/kcadm.sh get users -r sglab -q username=alice --fields id --format csv --noquotes); echo $USER_ID
# bin/kcadm.sh get users/$USER_ID/sessions -r sglab | jq '.[] | {username, ipAddress, clients}'

68c7b294-145d-4751-99ad-9c8244d921ac
{
  "username": "alice",
  "ipAddress": "127.0.0.1",
  "clients": {
    "09730fe3-8ef2-458f-a773-bd1835e246fa": "app-one",
    "e0ba130f-c149-48e1-af18-70d825746600": "app-two"
  }
}

{
  "acr": "0",
  "at_hash": "_J4IJPiJBN4WTv9C8ox5SA",
  "aud": "app-two",
  "auth_time": 1793845905,
  "azp": "app-two",
  "email": "alice@example.com",
  "email_verified": true,
  "exp": 1793846205,
  "family_name": "Lab",
  "given_name": "Alice",
  "iat": 1793845905,
  "iss": "http://localhost:8080/realms/sglab",
  "jti": "1b3b2373-37cb-9a1b-7a5c-6b3179af9ec0",
  "name": "Alice Lab",
  "nonce": "_XmhaYQLvlQ1aKz6p8e5pQ",
  "preferred_username": "alice",
  "sid": "3pgvFvELgsBkVY6fTyyfr1g1",
  "sub": "68c7b294-145d-4751-99ad-9c8244d921ac",
  "typ": "ID"
}

# grep -h Keycloak ~/kclab/app-*.log
# bin/kcadm.sh get users/$USER_ID/sessions -r sglab | jq length

app-one: Keycloak says session 3pgvFvEL... logged out
app-two: Keycloak says session 3pgvFvEL... logged out
0

# bin/kcadm.sh update users/$USER_ID -r sglab -s 'requiredActions=["CONFIGURE_TOTP"]'

# bin/kcadm.sh update users/$USER_ID -r sglab -s 'requiredActions=[]'
# bin/kcadm.sh get users/$USER_ID -r sglab --fields username,requiredActions

{
  "username" : "alice",
  "requiredActions" : [ ]
}

# pkill -f 'app.py (one|two)'
# pkill -f 'kclab/keycloak-26.8.1'
# sleep 5; cd ~ && rm -rf ~/kclab
# exit