From b0db1f400a3f77027eb193ab938650320a1b9c2b Mon Sep 17 00:00:00 2001 From: Bruce Weygandt Date: Tue, 17 Nov 2026 14:29:09 -0700 Subject: [PATCH] feat(keycloak): add keycloak category and keycloak_realm_security fetcher --- CHANGELOG.md | 6 + fetchers/_categories/keycloak.yaml | 41 ++++ fetchers/keycloak/README.md | 22 ++ fetchers/keycloak/_shared/keycloak_client.py | 98 ++++++++ fetchers/keycloak/realm_security/fetcher.py | 200 ++++++++++++++++ fetchers/keycloak/realm_security/fetcher.yaml | 93 ++++++++ tests/test_keycloak_realm_security.py | 214 ++++++++++++++++++ 7 files changed, 674 insertions(+) create mode 100644 fetchers/_categories/keycloak.yaml create mode 100644 fetchers/keycloak/README.md create mode 100644 fetchers/keycloak/_shared/keycloak_client.py create mode 100644 fetchers/keycloak/realm_security/fetcher.py create mode 100644 fetchers/keycloak/realm_security/fetcher.yaml create mode 100644 tests/test_keycloak_realm_security.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 01dee889..35492b29 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,12 @@ schemas and the `paramify` CLI — not the internal code. ### Added +- **`keycloak` category and `keycloak_realm_security` fetcher.** Reads a Keycloak realm through the Admin REST API with a + read-only service-account client: session and token lifetimes, brute-force lockout, password policy, the browser + and reset-credentials flows with each step's effective requirement (so a phishing-resistant authenticator counts + only when every sign-in must pass it), required actions such as terms and conditions, identity providers, user + federation, and login and admin event logging. Client secrets and bind credentials are never written to the + evidence, and an unreadable section leaves its fields null rather than empty. - `paramify upload --no-waf-check` turns off the check that drops a file holding `../`, `/etc/passwd`, `/bin/sh`, `/bin/bash` or `- + Keycloak identity provider, read through the Keycloak Admin REST API. Realm sign-in, session, lockout, + password and event settings, authentication flows, required actions, and federation. One service-account + client per Keycloak instance. + +requires: + python_packages: + - requests + - python-dotenv + +# Shared by every keycloak fetcher. The runner injects these env vars for any fetcher with category: keycloak. +config_schema: + base_url: + type: string + required: true + env: KEYCLOAK_BASE_URL + description: >- + Keycloak base URL, such as https://keycloak.admin.example.com. Include the /auth path for Keycloak + versions that still serve it. + realm: + type: string + default: uds + env: KEYCLOAK_REALM + description: The realm to read (uds is the default realm in UDS Core). + auth_realm: + type: string + env: KEYCLOAK_AUTH_REALM + description: >- + The realm that holds the service-account client, when it is not the realm being read (for example master). + Defaults to realm. + +secrets: + - name: client_id + env: KEYCLOAK_CLIENT_ID + description: >- + Client ID of a confidential client with service accounts enabled. Its service account needs the realm-management + client roles view-realm, view-identity-providers and view-events, and nothing else. + - name: client_secret + env: KEYCLOAK_CLIENT_SECRET + description: Client secret of that client. diff --git a/fetchers/keycloak/README.md b/fetchers/keycloak/README.md new file mode 100644 index 00000000..965c3118 --- /dev/null +++ b/fetchers/keycloak/README.md @@ -0,0 +1,22 @@ +# Keycloak fetchers + +Read-only evidence from the Keycloak Admin REST API. Every fetcher in this category signs in with the OAuth2 +client-credentials grant as a dedicated service-account client, then issues only GET requests under +`/admin/realms/{realm}`. The shared client is `_shared/keycloak_client.py`. + +## Setup + +1. In the realm to read (or in `master`, then set `auth_realm`), create a confidential OpenID Connect client with + **Client authentication** and **Service accounts roles** on, and every other flow off. +2. Give its service account the `realm-management` client roles `view-realm`, `view-identity-providers` and + `view-events`. No manage-* role is needed. +3. Set `KEYCLOAK_BASE_URL`, `KEYCLOAK_REALM` (default `uds`), optionally `KEYCLOAK_AUTH_REALM`, and the + `KEYCLOAK_CLIENT_ID` and `KEYCLOAK_CLIENT_SECRET` secrets. The fetcher must run from a network that can reach the + Keycloak admin endpoint. + +| Fetcher | Evidence set | Shows | +| --- | --- | --- | +| `realm_security` | `EVD-KEYCLOAK-REALM-SECURITY` | Sessions, lockout, password policy, browser and recovery flows, required actions, federation, event logging | + +Client secrets in identity provider configs and bind credentials in user federation configs are never written to +the evidence. diff --git a/fetchers/keycloak/_shared/keycloak_client.py b/fetchers/keycloak/_shared/keycloak_client.py new file mode 100644 index 00000000..c9703ed8 --- /dev/null +++ b/fetchers/keycloak/_shared/keycloak_client.py @@ -0,0 +1,98 @@ +#!/usr/bin/env python3 +"""Read-only Keycloak Admin REST API client shared by the keycloak fetchers. + +Authenticates with the OAuth2 client-credentials grant against the auth realm's token endpoint, then issues GETs +under /admin/realms/{realm}. Only GET is exposed: the fetchers read configuration and never change it. + +Collection-failure convention (docs/authoring_fetcher_guide.md, step 3): a failed GET is recorded in `api_failures` +and returns None, so one bad endpoint does not lose the rest of the evidence; the fetcher exits non-zero when +`api_failures` is non-empty. A failed token request raises, since nothing can be read without a token. +""" + +import logging +import os +import time +from typing import Any, Dict, List, Optional +from urllib.parse import quote + +import requests + +RETRY_STATUS = frozenset({429, 500, 502, 503, 504}) +MAX_RETRIES = 3 +TIMEOUT = 30 +CODES = {401: "auth_failed", 403: "not_authorized", 429: "rate_limited"} + +logger = logging.getLogger("keycloak_client") + + +class KeycloakAuthError(RuntimeError): + def __init__(self, message: str, code: str): + super().__init__(message) + self.code = code + + +def settings_from_env() -> Dict[str, str]: + """base_url, realm and auth_realm from the category config; client credentials from the declared secrets.""" + missing = [n for n in ("KEYCLOAK_BASE_URL", "KEYCLOAK_CLIENT_ID", "KEYCLOAK_CLIENT_SECRET") if not os.environ.get(n)] + if missing: + raise KeycloakAuthError(f"Missing required setting: {', '.join(missing)}", "bad_config") + realm = os.environ.get("KEYCLOAK_REALM") or "uds" + return {"base_url": os.environ["KEYCLOAK_BASE_URL"].rstrip("/"), "realm": realm, + "auth_realm": os.environ.get("KEYCLOAK_AUTH_REALM") or realm} + + +class KeycloakClient: + def __init__(self, base_url: str, realm: str, auth_realm: str, client_id: str, client_secret: str, session: Any = None): + self.base_url, self.realm, self.auth_realm = base_url.rstrip("/"), realm, auth_realm + self._client_id, self._client_secret = client_id, client_secret + self.session = session or requests.Session() + self.api_failures: List[Dict[str, Any]] = [] + self.failure_codes: List[str] = [] + self._token: Optional[str] = None + self._expires = 0.0 + + def _authenticate(self) -> str: + if self._token and time.time() < self._expires - 30: + return self._token + url = f"{self.base_url}/realms/{quote(self.auth_realm, safe='')}/protocol/openid-connect/token" + try: + response = self.session.post(url, data={"grant_type": "client_credentials", "client_id": self._client_id, + "client_secret": self._client_secret}, timeout=TIMEOUT) + except requests.RequestException as exc: + raise KeycloakAuthError(f"Keycloak token request failed: {type(exc).__name__}", "target_unreachable") from exc + if response.status_code != 200: + raise KeycloakAuthError(f"Keycloak token request answered {response.status_code}", CODES.get(response.status_code, "auth_failed")) + body = response.json() + self._token, self._expires = body["access_token"], time.time() + float(body.get("expires_in") or 60) + return self._token + + def get(self, operation: str, path: str, params: Optional[Dict[str, str]] = None) -> Any: + """GET /admin/realms/{realm}{path}; None (and a recorded failure) when it cannot be read.""" + url = f"{self.base_url}/admin/realms/{quote(self.realm, safe='')}{path}" + response = None + for attempt in range(MAX_RETRIES + 1): + try: + response = self.session.get(url, params=params, timeout=TIMEOUT, allow_redirects=False, + headers={"Authorization": f"Bearer {self._authenticate()}", "Accept": "application/json"}) + except requests.RequestException as exc: + if attempt == MAX_RETRIES: + return self._fail(operation, type(exc).__name__, str(exc), "target_unreachable") + time.sleep(min(2 ** attempt, 30)) + continue + if response.status_code in RETRY_STATUS and attempt < MAX_RETRIES: + time.sleep(min(2 ** attempt, 30)) + continue + break + if response.status_code != 200: + return self._fail(operation, f"HTTP {response.status_code}", (response.text or "")[:300], + CODES.get(response.status_code, "partial_failure")) + return response.json() + + def flow_executions(self, alias: str) -> Optional[List[Dict[str, Any]]]: + return self.get(f"authentication flow executions ({alias})", f"/authentication/flows/{quote(alias, safe='')}/executions") + + def _fail(self, operation: str, kind: str, message: str, code: str) -> None: + self.api_failures.append({"operation": operation, "type": kind, "message": message}) + self.failure_codes.append(code) + logger.error("%s failed: %s", operation, kind) + return None diff --git a/fetchers/keycloak/realm_security/fetcher.py b/fetchers/keycloak/realm_security/fetcher.py new file mode 100644 index 00000000..fd9290ac --- /dev/null +++ b/fetchers/keycloak/realm_security/fetcher.py @@ -0,0 +1,200 @@ +#!/usr/bin/env python3 +"""Keycloak realm security settings: sessions, lockout, password policy, the browser and reset-credentials flows, +required actions, federation and event logging, read from the Keycloak Admin REST API.""" + +import json +import logging +import os +import re +import sys +from datetime import datetime, timezone +from pathlib import Path +from typing import Any, Dict, List, Optional + +from dotenv import load_dotenv + +SCRIPT_DIR = Path(__file__).resolve().parent +sys.path.insert(0, str(SCRIPT_DIR.parents[1] / "_lib")) +sys.path.insert(0, str(SCRIPT_DIR.parent / "_shared")) +from fetcher_status import report_failure # noqa: E402 +from keycloak_client import KeycloakAuthError, KeycloakClient, settings_from_env # noqa: E402 + +NAME = "keycloak_realm_security" +OUTPUT = "keycloak_realm_security.json" +logger = logging.getLogger(NAME) + +# Authenticators that bind sign-in to the origin or to a key the user holds: WebAuthn (security keys, passkeys) +# and X.509 client certificates such as a CAC or PIV card. +PHISHING_RESISTANT = frozenset({"webauthn-authenticator", "webauthn-authenticator-passwordless", "auth-x509-client-username-form", + "direct-grant-auth-x509-username"}) +TERMS_ACTION = "terms_and_conditions" +USER_STORAGE = "org.keycloak.storage.UserStorageProvider" + + +# --- pure transforms --- + +def effective_requirements(executions: List[Dict[str, Any]]) -> List[Dict[str, Any]]: + """Each execution with `always`: True when it and every subflow above it are REQUIRED, so every sign-in through the + flow must pass it. Keycloak lists executions depth first, with `level` giving the nesting.""" + out, stack = [], [] # stack holds (level, always) for the enclosing subflows + for e in executions or []: + level = int(e.get("level") or 0) + while stack and stack[-1][0] >= level: + stack.pop() + parent_always = all(a for _, a in stack) + req = (e.get("requirement") or "").upper() + always = parent_always and req == "REQUIRED" + out.append({"provider": e.get("providerId"), "alias": e.get("displayName") or e.get("alias"), "level": level, + "requirement": req, "subflow": bool(e.get("authenticationFlow")), "always": always}) + if e.get("authenticationFlow"): + stack.append((level, always)) + return out + + +def password_rules(policy: Optional[str]) -> Dict[str, Optional[int]]: + """Keycloak's passwordPolicy string, such as "length(15) and passwordHistory(24)", as rule -> number (None when the + rule takes no number).""" + rules: Dict[str, Optional[int]] = {} + for part in re.split(r"\s+and\s+", policy or ""): + found = re.match(r"\s*([A-Za-z]+)(?:\((\d*)\))?", part) + if found and found.group(1): + rules[found.group(1)] = int(found.group(2)) if found.group(2) else None + return rules + + +def _minutes(seconds: Any) -> Optional[float]: + return round(int(seconds) / 60, 1) if isinstance(seconds, (int, float)) else None + + +def summarize(realm: Optional[Dict[str, Any]], browser: Optional[List[Dict[str, Any]]], reset: Optional[List[Dict[str, Any]]], + actions: Optional[List[Dict[str, Any]]], idps: Optional[List[Dict[str, Any]]], + storage: Optional[List[Dict[str, Any]]], events: Optional[Dict[str, Any]]) -> Dict[str, Any]: + """What is configured, never a verdict. Each group is null when the call behind it could not be read.""" + r = realm or {} + rules = password_rules(r.get("passwordPolicy")) if realm is not None else {} + flow = effective_requirements(browser) if browser is not None else None + steps = [e for e in flow or [] if not e["subflow"] and e["requirement"] != "DISABLED"] + by_alias = {(a.get("alias") or "").lower(): a for a in actions or []} + terms = by_alias.get(TERMS_ACTION) + rs = realm is not None + + def realm_value(value): + return value if rs else None + + return { + "realm_enabled": realm_value(bool(r.get("enabled"))), + "ssl_required": realm_value(r.get("sslRequired")), + "registration_allowed": realm_value(bool(r.get("registrationAllowed"))), + # Sessions + "sso_session_idle_timeout_minutes": realm_value(_minutes(r.get("ssoSessionIdleTimeout"))), + "sso_session_max_lifespan_minutes": realm_value(_minutes(r.get("ssoSessionMaxLifespan"))), + "access_token_lifespan_minutes": realm_value(_minutes(r.get("accessTokenLifespan"))), + "remember_me_enabled": realm_value(bool(r.get("rememberMe"))), + # Lockout + "brute_force_protected": realm_value(bool(r.get("bruteForceProtected"))), + "lockout_failure_threshold": realm_value(r.get("failureFactor") if r.get("bruteForceProtected") else None), + "permanent_lockout": realm_value(bool(r.get("permanentLockout")) if r.get("bruteForceProtected") else None), + "lockout_max_wait_minutes": realm_value(_minutes(r.get("maxFailureWaitSeconds")) if r.get("bruteForceProtected") else None), + # Passwords + "password_policy_rules": realm_value(sorted(rules)), + "password_min_length": realm_value(rules.get("length")), + "password_history": realm_value(rules.get("passwordHistory")), + "password_expiry_days": realm_value(rules.get("forceExpiredPasswordChange")), + # Browser flow + "browser_flow": realm_value(r.get("browserFlow")), + "browser_flow_always_required_authenticators": sorted({e["provider"] for e in steps if e["always"]}) if flow is not None else None, + "browser_flow_phishing_resistant_always_required": (any(e["always"] and e["provider"] in PHISHING_RESISTANT for e in steps) + if flow is not None else None), + "browser_flow_alternative_authenticators": sorted({e["provider"] for e in steps if e["requirement"] == "ALTERNATIVE"}) + if flow is not None else None, + "browser_flow_conditional_authenticators": sorted({e["provider"] for e in steps if (e["provider"] or "").startswith("conditional-")}) + if flow is not None else None, + "reset_credentials_authenticators": sorted({e["provider"] for e in effective_requirements(reset) + if not e["subflow"] and e["requirement"] != "DISABLED"}) if reset is not None else None, + # Required actions + "terms_and_conditions_enabled": bool(terms and terms.get("enabled")) if actions is not None else None, + "terms_and_conditions_default_action": bool(terms and terms.get("enabled") and terms.get("defaultAction")) if actions is not None else None, + "default_required_actions": sorted(a.get("alias") for a in actions or [] if a.get("enabled") and a.get("defaultAction")) + if actions is not None else None, + # Federation + "identity_providers_enabled": sum(1 for i in idps or [] if i.get("enabled")) if idps is not None else None, + "identity_provider_types": sorted({i.get("providerId") for i in idps or [] if i.get("enabled")}) if idps is not None else None, + "user_federation_providers": len(storage) if storage is not None else None, + # Events + "login_events_enabled": bool((events or {}).get("eventsEnabled")) if events is not None else None, + "login_events_expiration_days": (round(int(events["eventsExpiration"]) / 86400, 1) if events and events.get("eventsExpiration") else None) + if events is not None else None, + "admin_events_enabled": bool((events or {}).get("adminEventsEnabled")) if events is not None else None, + "admin_events_details_enabled": bool((events or {}).get("adminEventsDetailsEnabled")) if events is not None else None, + "event_listeners": sorted((events or {}).get("eventsListeners") or []) if events is not None else None, + } + + +REALM_KEYS = ("realm", "enabled", "sslRequired", "registrationAllowed", "verifyEmail", "loginWithEmailAllowed", "rememberMe", + "ssoSessionIdleTimeout", "ssoSessionMaxLifespan", "ssoSessionIdleTimeoutRememberMe", "ssoSessionMaxLifespanRememberMe", + "offlineSessionIdleTimeout", "accessTokenLifespan", "revokeRefreshToken", "bruteForceProtected", "failureFactor", + "permanentLockout", "maxFailureWaitSeconds", "waitIncrementSeconds", "minimumQuickLoginWaitSeconds", + "passwordPolicy", "otpPolicyType", "otpPolicyAlgorithm", "otpPolicyDigits", "browserFlow", "resetCredentialsFlow", + "directGrantFlow", "firstBrokerLoginFlow") + + +def collect(client: KeycloakClient) -> Dict[str, Any]: + realm = client.get("realm settings", "") + browser_alias = (realm or {}).get("browserFlow") or "browser" + reset_alias = (realm or {}).get("resetCredentialsFlow") or "reset credentials" + browser = client.flow_executions(browser_alias) + reset = client.flow_executions(reset_alias) + actions = client.get("required actions", "/authentication/required-actions") + idps = client.get("identity providers", "/identity-provider/instances") + storage = client.get("user federation providers", "/components", {"type": USER_STORAGE}) + events = client.get("events configuration", "/events/config") + results = { + "realm_settings": {k: realm.get(k) for k in REALM_KEYS} if realm is not None else None, + "browser_flow": {"alias": browser_alias, "executions": effective_requirements(browser) if browser is not None else None}, + "reset_credentials_flow": {"alias": reset_alias, "executions": effective_requirements(reset) if reset is not None else None}, + "required_actions": [{k: a.get(k) for k in ("alias", "name", "enabled", "defaultAction", "priority")} for a in actions] + if actions is not None else None, + # Identity provider and user federation configs hold client secrets and bind credentials: never copied. + "identity_providers": [{k: i.get(k) for k in ("alias", "displayName", "providerId", "enabled", "trustEmail", "firstBrokerLoginFlowAlias")} + for i in idps] if idps is not None else None, + "user_federation_providers": [{"name": c.get("name"), "provider": c.get("providerId"), + "edit_mode": ((c.get("config") or {}).get("editMode") or [None])[0], + "enabled": ((c.get("config") or {}).get("enabled") or [None])[0]} for c in storage] + if storage is not None else None, + "events_configuration": {k: events.get(k) for k in ("eventsEnabled", "eventsExpiration", "eventsListeners", "enabledEventTypes", + "adminEventsEnabled", "adminEventsDetailsEnabled")} if events is not None else None, + } + return {"results": results, "summary": summarize(realm, browser, reset, actions, idps, storage, events)} + + +def main() -> int: + logging.basicConfig(level=os.environ.get("LOG_LEVEL", "INFO"), format="%(asctime)s %(levelname)s %(name)s %(message)s") + load_dotenv() + out_dir = Path(os.environ.get("EVIDENCE_DIR", "./evidence")) + out_dir.mkdir(parents=True, exist_ok=True) + metadata: Dict[str, Any] = {"datetime": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), "api_failures": []} + code, evidence = None, {"results": {}, "summary": summarize(None, None, None, None, None, None, None)} + try: + settings = settings_from_env() + metadata.update(realm=settings["realm"], base_url=settings["base_url"]) + client = KeycloakClient(settings["base_url"], settings["realm"], settings["auth_realm"], + os.environ["KEYCLOAK_CLIENT_ID"], os.environ["KEYCLOAK_CLIENT_SECRET"]) + evidence = collect(client) + metadata["api_failures"] = client.api_failures + code = client.failure_codes[0] if client.failure_codes else None + except KeycloakAuthError as exc: + metadata["api_failures"] = [{"operation": "authenticate", "type": "KeycloakAuthError", "message": str(exc)}] + code = exc.code + metadata["partial_failure"] = bool(metadata["api_failures"]) + path = out_dir / OUTPUT + path.write_text(json.dumps({"metadata": metadata, **evidence}, indent=2, sort_keys=True)) + logger.info("Evidence saved to %s", path) + if metadata["api_failures"]: + first = metadata["api_failures"][0] + report_failure(f"Keycloak {first['operation']} failed: {first['type']}", code) + return 1 + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/fetchers/keycloak/realm_security/fetcher.yaml b/fetchers/keycloak/realm_security/fetcher.yaml new file mode 100644 index 00000000..c2f253e3 --- /dev/null +++ b/fetchers/keycloak/realm_security/fetcher.yaml @@ -0,0 +1,93 @@ +name: keycloak_realm_security +version: 0.1.0 +description: >- + Shows whether a Keycloak realm enforces session timeouts, account lockout, password rules and phishing-resistant sign-in, and whether federation, sign-in notices and event logging are configured. +category: keycloak + +supports_targets: false + +runtime: + type: python + entry: fetcher.py + +output: + type: json + path: keycloak_realm_security.json + +secrets: [] # client_id and client_secret come from the category (fetchers/_categories/keycloak.yaml) + +ksis: + - KSI-IAM-APM # phishing-resistant authenticators in the browser flow, fallback and recovery methods, federation + - KSI-IAM-SUS # brute-force detection and lockout + - KSI-IAM-ELP # conditional authenticators in the browser flow + - KSI-MLA-LET # login and admin event logging + +evidence_set: + reference_id: EVD-KEYCLOAK-REALM-SECURITY + name: Keycloak Realm Security + instructions: | + Script: keycloak/realm_security/fetcher.py + + Access: A Keycloak client with service accounts enabled whose service account holds the realm-management client roles view-realm, view-identity-providers and view-events, reached from a network that can call the Keycloak admin endpoint. Without view-events the event settings read as null; without view-identity-providers the identity providers read as null. + + Commands Executed: + - POST /realms/{auth realm}/protocol/openid-connect/token — a client-credentials token for the service account + - GET /admin/realms/{realm} — session, token, lockout, password policy, SSL and flow bindings + - GET /admin/realms/{realm}/authentication/flows/{browser flow}/executions — every step of the browser sign-in flow with its requirement + - GET /admin/realms/{realm}/authentication/flows/{reset credentials flow}/executions — every step of account recovery + - GET /admin/realms/{realm}/authentication/required-actions — required actions, including terms and conditions + - GET /admin/realms/{realm}/identity-provider/instances — external identity providers + - GET /admin/realms/{realm}/components (type UserStorageProvider) — user federation providers such as LDAP + - GET /admin/realms/{realm}/events/config — login and admin event logging + + Output: keycloak_realm_security.json — the realm's sign-in, session, lockout, password and event settings, each browser and reset-credentials flow step with its effective requirement, required actions, identity providers and user federation providers, without any client secret or bind credential. + + Summary fields: + + Which realm was read? + - realm_enabled — True if the realm is enabled; false if it is disabled; null if the realm could not be read, as is every realm setting below + - ssl_required — Whether HTTPS is required for requests to the realm: all, external (all but private addresses) or none + - registration_allowed — True if users can register themselves on the sign-in page; false if accounts are created only by administrators or federation + + Do sessions end? + - sso_session_idle_timeout_minutes — Minutes a sign-in session may sit idle before it ends + - sso_session_max_lifespan_minutes — Minutes a sign-in session may last in total before the user signs in again + - access_token_lifespan_minutes — Minutes an access token stays valid + - remember_me_enabled — True if the sign-in page offers remember me, which keeps sessions under their own longer timeouts + + Are repeated failed sign-ins locked out? + - brute_force_protected — True if brute-force detection is on; false if failed sign-ins never lock an account + - lockout_failure_threshold — Number of failed sign-ins that locks an account; null while brute-force detection is off + - permanent_lockout — True if a locked account stays locked until an administrator unlocks it; false if it unlocks after a wait; null while brute-force detection is off + - lockout_max_wait_minutes — Minutes of the longest temporary lockout; null while brute-force detection is off + + Which password rules apply? + - password_policy_rules — List of the password policy's rule names, such as length or passwordHistory + - password_min_length — Number of characters a password must have at least; null when the policy sets no length + - password_history — Number of previous passwords that cannot be reused; null when the policy sets no history + - password_expiry_days — Days before a password must be changed; null when passwords do not expire + + How does a person sign in? + - browser_flow — Alias of the authentication flow bound to browser sign-in + - browser_flow_always_required_authenticators — List of the authenticators every browser sign-in must pass: REQUIRED, and inside subflows that are themselves REQUIRED (always required); null if the flow could not be read + - browser_flow_phishing_resistant_always_required — True if a phishing-resistant authenticator (WebAuthn security key or passkey, or an X.509 client certificate such as a CAC or PIV card) is always required in the browser flow; false if a sign-in can complete without one; null if the flow could not be read + - browser_flow_alternative_authenticators — List of the authenticators marked ALTERNATIVE in the browser flow, where any one of them is enough (the fallback paths); null if the flow could not be read + - browser_flow_conditional_authenticators — List of the conditions (conditional- authenticators) in the browser flow that decide whether a subflow runs; null if the flow could not be read + - reset_credentials_authenticators — List of the enabled authenticators in the reset-credentials flow, the recovery path used to restore access; null if the flow could not be read + + What must a user do at sign-in? + - terms_and_conditions_enabled — True if the terms and conditions required action is enabled; false if it is not; null if the required actions could not be read + - terms_and_conditions_default_action — True if terms and conditions is also a default action, so every new user must accept it; false if it is not; null if the required actions could not be read + - default_required_actions — List of the enabled required actions every new user must complete, such as CONFIGURE_TOTP or webauthn-register; null if the required actions could not be read + + Where do identities come from? + - identity_providers_enabled — Number of enabled external identity providers (OIDC or SAML brokers); null if they could not be read + - identity_provider_types — List of the types of the enabled identity providers, such as oidc or saml + - user_federation_providers — Number of user federation providers, such as LDAP or Kerberos; null if they could not be read + + Are sign-ins and admin changes logged? + - login_events_enabled — True if Keycloak stores login events; false if it does not; null if the event settings could not be read + - login_events_expiration_days — Days stored login events are kept; null when they are kept until removed or the settings could not be read + - admin_events_enabled — True if Keycloak stores admin events (changes made through the admin console or API); false if it does not; null if the event settings could not be read + - admin_events_details_enabled — True if admin events include the full representation of what changed; false if they do not; null if the event settings could not be read + - event_listeners — List of the event listeners that receive events, such as jboss-logging (the server log); null if the event settings could not be read diff --git a/tests/test_keycloak_realm_security.py b/tests/test_keycloak_realm_security.py new file mode 100644 index 00000000..eb4dbad2 --- /dev/null +++ b/tests/test_keycloak_realm_security.py @@ -0,0 +1,214 @@ +"""keycloak_realm_security: effective flow requirements, password policy parsing, null-not-zero summaries, secrets kept out +of the evidence, and full runs against synthetic Keycloak Admin REST API responses. No network.""" + +from __future__ import annotations + +import importlib.util +import json +import sys +from pathlib import Path +from urllib.parse import unquote, urlparse + +import pytest + +REPO_ROOT = Path(__file__).resolve().parent.parent +FETCHER = REPO_ROOT / "fetchers" / "keycloak" / "realm_security" / "fetcher.py" +_spec = importlib.util.spec_from_file_location("keycloak_realm_security_under_test", FETCHER) +kc = importlib.util.module_from_spec(_spec) +_spec.loader.exec_module(kc) +client_mod = sys.modules["keycloak_client"] + +BASE = "https://keycloak.admin.example.com" + + +def ex(provider, requirement, level=0, subflow=False, name=None): + return {"providerId": provider, "requirement": requirement, "level": level, "authenticationFlow": subflow, + "displayName": name or provider} + + +# A browser flow shaped like a typical hardened realm: cookie OR a forms subflow; the forms subflow requires a +# username form, then a conditional MFA subflow, plus an X.509 certificate step. +BROWSER = [ + ex("auth-cookie", "ALTERNATIVE"), + ex(None, "ALTERNATIVE", subflow=True, name="forms"), + ex("auth-username-password-form", "REQUIRED", level=1), + ex(None, "CONDITIONAL", level=1, subflow=True, name="mfa"), + ex("conditional-user-configured", "REQUIRED", level=2), + ex("auth-otp-form", "ALTERNATIVE", level=2), + ex("webauthn-authenticator", "ALTERNATIVE", level=2), +] +STRICT = [ex("auth-x509-client-username-form", "REQUIRED"), ex(None, "REQUIRED", subflow=True, name="second factor"), + ex("webauthn-authenticator", "REQUIRED", level=1), ex("auth-otp-form", "DISABLED", level=1)] +RESET = [ex("reset-credentials-choose-user", "REQUIRED"), ex("reset-credential-email", "REQUIRED"), ex("reset-otp", "DISABLED")] +REALM = {"realm": "uds", "enabled": True, "sslRequired": "all", "registrationAllowed": False, "rememberMe": False, + "ssoSessionIdleTimeout": 900, "ssoSessionMaxLifespan": 36000, "accessTokenLifespan": 60, + "bruteForceProtected": True, "failureFactor": 3, "permanentLockout": True, "maxFailureWaitSeconds": 900, + "passwordPolicy": "length(15) and passwordHistory(24) and notUsername(undefined) and forceExpiredPasswordChange(60)", + "browserFlow": "UDS Authentication", "resetCredentialsFlow": "reset credentials"} +ACTIONS = [{"alias": "TERMS_AND_CONDITIONS", "name": "Terms and Conditions", "enabled": True, "defaultAction": True}, + {"alias": "webauthn-register", "name": "Webauthn Register", "enabled": True, "defaultAction": True}, + {"alias": "CONFIGURE_TOTP", "name": "Configure OTP", "enabled": True, "defaultAction": False}] +IDPS = [{"alias": "azure-ad", "providerId": "oidc", "enabled": True, "config": {"clientSecret": "s3cr3t-value", "clientId": "abc"}}, + {"alias": "old-saml", "providerId": "saml", "enabled": False, "config": {}}] +STORAGE = [{"name": "corp-ldap", "providerId": "ldap", "config": {"editMode": ["READ_ONLY"], "enabled": ["true"], "bindCredential": ["ldap-pw"]}}] +EVENTS = {"eventsEnabled": True, "eventsExpiration": 7776000, "eventsListeners": ["jboss-logging"], + "adminEventsEnabled": True, "adminEventsDetailsEnabled": True, "enabledEventTypes": ["LOGIN", "LOGIN_ERROR"]} + + +# --- pure transforms --- + +def test_only_steps_inside_required_subflows_are_always_required(): + flow = {e["alias"]: e for e in kc.effective_requirements(BROWSER)} + # forms is ALTERNATIVE to the cookie, so nothing inside it is required on every sign-in. + assert not flow["auth-username-password-form"]["always"] and not flow["webauthn-authenticator"]["always"] + strict = {e["alias"]: e for e in kc.effective_requirements(STRICT)} + assert strict["auth-x509-client-username-form"]["always"] and strict["webauthn-authenticator"]["always"] + + +def test_password_policy_string_becomes_rules(): + assert kc.password_rules(REALM["passwordPolicy"]) == {"length": 15, "passwordHistory": 24, "notUsername": None, + "forceExpiredPasswordChange": 60} + assert kc.password_rules(None) == {} and kc.password_rules("") == {} + + +def test_summary_reads_sessions_lockout_passwords_and_the_browser_flow(): + s = kc.summarize(REALM, BROWSER, RESET, ACTIONS, IDPS, STORAGE, EVENTS) + assert (s["sso_session_idle_timeout_minutes"], s["sso_session_max_lifespan_minutes"], s["access_token_lifespan_minutes"]) == (15.0, 600.0, 1.0) + assert (s["brute_force_protected"], s["lockout_failure_threshold"], s["permanent_lockout"]) == (True, 3, True) + assert (s["password_min_length"], s["password_history"], s["password_expiry_days"]) == (15, 24, 60) + assert s["browser_flow_phishing_resistant_always_required"] is False # WebAuthn is one ALTERNATIVE among OTP + assert s["browser_flow_alternative_authenticators"] == ["auth-cookie", "auth-otp-form", "webauthn-authenticator"] + assert s["browser_flow_conditional_authenticators"] == ["conditional-user-configured"] + assert s["reset_credentials_authenticators"] == ["reset-credential-email", "reset-credentials-choose-user"] + assert (s["terms_and_conditions_enabled"], s["terms_and_conditions_default_action"]) == (True, True) + assert (s["identity_providers_enabled"], s["identity_provider_types"], s["user_federation_providers"]) == (1, ["oidc"], 1) + assert (s["login_events_enabled"], s["login_events_expiration_days"], s["admin_events_details_enabled"]) == (True, 90.0, True) + + +def test_a_required_certificate_and_security_key_count_as_phishing_resistant(): + s = kc.summarize(REALM, STRICT, RESET, ACTIONS, IDPS, STORAGE, EVENTS) + assert s["browser_flow_phishing_resistant_always_required"] is True + assert s["browser_flow_always_required_authenticators"] == ["auth-x509-client-username-form", "webauthn-authenticator"] + assert "auth-otp-form" not in s["browser_flow_alternative_authenticators"] # DISABLED steps are left out + + +def test_lockout_details_are_null_while_brute_force_detection_is_off(): + s = kc.summarize({**REALM, "bruteForceProtected": False}, BROWSER, RESET, ACTIONS, IDPS, STORAGE, EVENTS) + assert (s["brute_force_protected"], s["lockout_failure_threshold"], s["permanent_lockout"], s["lockout_max_wait_minutes"]) == (False, None, None, None) + + +def test_each_group_is_null_not_empty_when_its_call_failed(): + s = kc.summarize(REALM, None, None, None, None, None, None) + assert s["sso_session_idle_timeout_minutes"] == 15.0 + for field in ("browser_flow_phishing_resistant_always_required", "reset_credentials_authenticators", "terms_and_conditions_enabled", + "identity_providers_enabled", "user_federation_providers", "login_events_enabled", "admin_events_enabled"): + assert s[field] is None, field + assert kc.summarize(None, None, None, None, None, None, None)["realm_enabled"] is None + + +# --- full runs against synthetic Keycloak responses --- + +class _Resp: + def __init__(self, status, body): + self.status_code, self._body, self.text = status, body, json.dumps(body) + + def json(self): + return self._body + + +class _Keycloak: + """requests.Session for one Keycloak: a client-credentials token, then the realm's admin GETs.""" + + def __init__(self, token_status=200, refused=(), browser=None): + self.token_status, self.refused, self.browser = token_status, set(refused), browser or STRICT + self.posts, self.gets = [], [] + + def post(self, url, data=None, timeout=None): + self.posts.append((url, dict(data or {}))) + return _Resp(self.token_status, {"access_token": "tok", "expires_in": 300} if self.token_status == 200 else {"error": "unauthorized_client"}) + + def get(self, url, params=None, timeout=None, allow_redirects=True, headers=None): + path = unquote(urlparse(url).path) + self.gets.append((path, dict(params or {}))) + assert path.startswith("/admin/realms/uds") + tail = path[len("/admin/realms/uds"):] + for key in self.refused: + if tail.startswith(key): + return _Resp(403, {"error": "unknown_error"}) + bodies = {"": REALM, "/authentication/flows/UDS Authentication/executions": self.browser, + "/authentication/flows/reset credentials/executions": RESET, "/authentication/required-actions": ACTIONS, + "/identity-provider/instances": IDPS, "/components": STORAGE, "/events/config": EVENTS} + return _Resp(200, bodies[tail]) if tail in bodies else _Resp(404, {"error": "not found"}) + + +@pytest.fixture +def keycloak(monkeypatch, tmp_path): + def serve(**kwargs): + session = _Keycloak(**kwargs) + monkeypatch.setattr(client_mod.requests, "Session", lambda: session) + return session + + monkeypatch.setattr(client_mod.time, "sleep", lambda s: None) + monkeypatch.setenv("EVIDENCE_DIR", str(tmp_path)) + monkeypatch.setenv("FETCHER_STATUS_FILE", str(tmp_path / "status.json")) + monkeypatch.setenv("KEYCLOAK_BASE_URL", BASE + "/") + monkeypatch.setenv("KEYCLOAK_CLIENT_ID", "paramify-reader") + monkeypatch.setenv("KEYCLOAK_CLIENT_SECRET", "client-secret-value") + monkeypatch.delenv("KEYCLOAK_REALM", raising=False) + monkeypatch.delenv("KEYCLOAK_AUTH_REALM", raising=False) + return serve + + +def _evidence(tmp_path): + return json.loads((tmp_path / "keycloak_realm_security.json").read_text()) + + +def test_main_reads_the_realm_and_writes_the_summary(keycloak, tmp_path, assert_summary_documented): + session = keycloak() + assert kc.main() == 0 + ev = _evidence(tmp_path) + assert ev["summary"]["browser_flow_phishing_resistant_always_required"] is True + assert ev["metadata"]["partial_failure"] is False and ev["metadata"]["realm"] == "uds" + assert session.posts[0][0] == f"{BASE}/realms/uds/protocol/openid-connect/token" + assert session.posts[0][1]["grant_type"] == "client_credentials" + assert ("/admin/realms/uds/components", {"type": kc.USER_STORAGE}) in session.gets + assert_summary_documented("keycloak/realm_security", ev["summary"]) + + +def test_no_client_secret_or_bind_credential_reaches_the_evidence(keycloak, tmp_path): + keycloak() + assert kc.main() == 0 + text = (tmp_path / "keycloak_realm_security.json").read_text() + for secret in ("s3cr3t-value", "ldap-pw", "client-secret-value", "tok"): + assert f'"{secret}"' not in text, secret + + +def test_an_unreadable_section_fails_the_run_and_leaves_only_that_section_null(keycloak, tmp_path): + keycloak(refused=("/events/config",)) + assert kc.main() == 1 + ev = _evidence(tmp_path) + assert (ev["summary"]["login_events_enabled"], ev["summary"]["admin_events_enabled"]) == (None, None) + assert ev["summary"]["brute_force_protected"] is True and ev["metadata"]["partial_failure"] is True + assert json.loads((tmp_path / "status.json").read_text())["code"] == "not_authorized" + + +def test_a_refused_token_fails_the_run_as_auth_failed(keycloak, tmp_path): + keycloak(token_status=401) + assert kc.main() == 1 + assert _evidence(tmp_path)["summary"]["realm_enabled"] is None + assert json.loads((tmp_path / "status.json").read_text())["code"] == "auth_failed" + + +def test_missing_settings_fail_the_run_as_bad_config(keycloak, tmp_path, monkeypatch): + keycloak() + monkeypatch.delenv("KEYCLOAK_BASE_URL") + assert kc.main() == 1 + assert json.loads((tmp_path / "status.json").read_text())["code"] == "bad_config" + + +def test_a_separate_auth_realm_is_used_only_for_the_token(keycloak, tmp_path, monkeypatch): + monkeypatch.setenv("KEYCLOAK_AUTH_REALM", "master") + session = keycloak() + assert kc.main() == 0 + assert session.posts[0][0] == f"{BASE}/realms/master/protocol/openid-connect/token" + assert all(path.startswith("/admin/realms/uds") for path, _ in session.gets)