diff --git a/docs/waves/wave-13.md b/docs/waves/wave-13.md index fcf4f4b..479939d 100644 --- a/docs/waves/wave-13.md +++ b/docs/waves/wave-13.md @@ -105,13 +105,17 @@ unnecessarily. **Done when:** -- [ ] the client authenticates with its own credential, distinct from the OIDC +- [x] the client authenticates with its own credential, distinct from the OIDC client -- [ ] it fetches the complete Okta user list, handling pagination -- [ ] an auth failure or malformed response raises a clear, specific error + *(2026-10-16: `OKTA_API_TOKEN`, sent as `Authorization: SSWS`. `tests/okta_sync_check.py` sets a different OIDC client secret and asserts it is never sent.)* +- [x] it fetches the complete Okta user list, handling pagination + *(2026-10-16: follows `Link: rel="next"`, 200 per page, 2-page case checked. A next link to another host is refused, a chain longer than 50 pages raises instead of cutting the list off, redirects are never followed.)* +- [x] an auth failure or malformed response raises a clear, specific error rather than returning an empty list indistinguishable from "everyone was deprovisioned" — this distinction is what T13.3 depends on -- [ ] the credential is never logged or surfaced in any API response + *(2026-10-16: `OktaSyncError` for HTTP 401/403/404/429/5xx, redirects, network errors, timeouts, non-JSON, non-list, a bad item (never skipped), and an empty list. 31 failure checks. Mutation test: making the client return `[]` on an error fails 10 of them.)* +- [x] the credential is never logged or surfaced in any API response + *(2026-10-16: error messages carry the class name and HTTP status only, never the URL or a header. `describe()` has no token. Nothing is wired to an API response yet; T13.4 wires the startup log.)* --- diff --git a/server/.env.example b/server/.env.example index 93721ed..08f433a 100644 --- a/server/.env.example +++ b/server/.env.example @@ -65,6 +65,30 @@ OKTA_REDIRECT_URI=CHANGE_ME # a custom claim, …) — no code change needed, just this value. # OKTA_IDENTITY_CLAIM=preferred_username +# ── Okta deprovisioning sync (D18, wave 13) ──────────────────────────────────── +# A scheduled job asks Okta who is still active and disables local accounts +# Okta no longer shows as active. It only ever DISABLES. It never re-enables. +# If Okta cannot be reached or answers with anything unexpected, the job changes +# NOTHING that cycle and logs the failure. +# +# A read-only Okta API token, created by the person who administers the Okta +# tenant (Security > API > Tokens). This is NOT the OIDC client secret above. +# It is a different credential with a different scope. Treat it like +# AUTH_SECRET_KEY: never commit it, never log it. Leave it unset and the sync +# stays off (the startup log says so). +# OKTA_API_TOKEN=CHANGE_ME +# +# The Okta org URL that serves the Management API, e.g. https://yourorg.okta.com +# Optional. If unset, it is the scheme and host of OKTA_ISSUER. Must be https. +# OKTA_ORG_URL=https://your-org.okta.com +# +# Which Okta PROFILE attribute holds the value that matches users.username. +# Optional. By default it follows OKTA_IDENTITY_CLAIM: preferred_username reads +# profile.login, email reads profile.email, any other claim name reads the +# profile attribute of the same name. Set this only if your tenant builds the +# claim from a different attribute. +# OKTA_SYNC_PROFILE_ATTRIBUTE=login + # ── Email notifications (optional) ───────────────────────────────────────────── # WP-assignment emails are OFF by default and are turned on from the Admin # console (Notifications & email card), where the SMTP host/port/from-address diff --git a/server/okta_sync.py b/server/okta_sync.py new file mode 100644 index 0000000..ee48abc --- /dev/null +++ b/server/okta_sync.py @@ -0,0 +1,205 @@ +"""Okta Management API client - T13.2, wave 13 (D18). + +This module asks Okta one question: who is in the org, and what is each person's +status? It is the first half of the deprovisioning sync. It does not touch the +database and it does not disable anyone. T13.3 does that, using the list this +module returns. + +Trust boundary. Sign-in uses the OIDC client (OKTA_CLIENT_ID and OKTA_CLIENT_SECRET, +see okta_auth.py). This module uses a different credential, OKTA_API_TOKEN, a +read-only Okta API token. The two never mix. A rotation or a leak of one does not +touch the other. + +Failure rule (D18, decision 4). This is the most important rule in this file: +**an error is never an empty list.** If anything goes wrong, this module raises +OktaSyncError. It never returns [] to mean "the call failed". T13.3 reads an empty +list as "nobody is active", so a function that returned [] on a network error +would disable every account on an Okta outage. The cases that raise are: + + - the token or the org URL is not set + - a network error or a timeout + - any HTTP status that is not 200 (401, 403 and 429 included) + - a body that is not a JSON list, or an item that is not shaped as expected + - a user with no usable identity value + - a list with no users at all (a real org is never empty; an empty list means + the token cannot see the users) + - a page limit reached (a cut-off list would make real users look missing) + - a "next page" link that points to a different host + +The token is read from the environment each time it is used. It is never logged, +never put in an error message, and never returned to a browser. Errors carry the +exception class name and the HTTP status only. httpx exceptions can include the +request URL, so the URL is not copied into the message either. +""" +import logging +import os +from dataclasses import dataclass +from typing import Optional +from urllib.parse import urlparse + +import httpx + +from . import okta_auth + +log = logging.getLogger("wpsuite.okta_sync") + +# Okta's own page maximum for this endpoint. Asking for the maximum keeps a +# 20-odd account org to a single call. +PAGE_LIMIT = 200 +# A cut-off list is more dangerous than an error, so the loop is bounded and +# raises when the bound is reached. 50 pages of 200 is 10,000 people. +MAX_PAGES = 50 +TIMEOUT_SECONDS = 15.0 + +# Which Okta *profile attribute* matches each OIDC claim that OKTA_IDENTITY_CLAIM +# may name. The sign-in flow reads a claim from the ID token. This API returns +# the profile instead. For the default claim, preferred_username, Okta's own +# default maps it to profile.login. A claim that is not in this table is read +# from profile[] (for example a custom attribute). +# OKTA_SYNC_PROFILE_ATTRIBUTE overrides the whole table. Use it if the tenant +# builds the claim from a different attribute. +_CLAIM_TO_PROFILE = { + "preferred_username": "login", + "email": "email", +} + + +class OktaSyncError(Exception): + """The Okta user list could not be fetched with confidence. T13.3 must take no + action on any account when it sees this.""" + + +@dataclass(frozen=True) +class OktaUser: + identity: str # the value that matches users.username (lower case is NOT applied here) + status: str # Okta's status, upper case: ACTIVE, SUSPENDED, DEPROVISIONED, ... + + +# ── configuration ───────────────────────────────────────────────────────────── +def _token() -> str: + return os.getenv("OKTA_API_TOKEN", "").strip() + + +def org_url() -> str: + """The Okta org base URL, for example https://yourorg.okta.com. The Management + API lives here, not at the authorization server issuer. OKTA_ORG_URL wins if + set. Otherwise it is the scheme and host of OKTA_ISSUER.""" + explicit = os.getenv("OKTA_ORG_URL", "").strip().rstrip("/") + if explicit: + return explicit + issuer = (okta_auth.ISSUER or "").strip() + parsed = urlparse(issuer) + if parsed.scheme and parsed.netloc: + return f"{parsed.scheme}://{parsed.netloc}" + return "" + + +def is_configured() -> bool: + return bool(_token() and org_url().startswith("https://")) + + +def describe() -> str: + """One line for the startup log. Never contains the token.""" + if not _token(): + return "Okta sync DISABLED - OKTA_API_TOKEN is not set. Deprovisioning is not detected." + base = org_url() + if not base: + return "Okta sync DISABLED - no OKTA_ORG_URL and OKTA_ISSUER has no host. Deprovisioning is not detected." + if not base.startswith("https://"): + return f"Okta sync DISABLED - org URL {base!r} is not https. The token is never sent over http." + return f"Okta sync configured - org {base}, identity claim {okta_auth.IDENTITY_CLAIM!r}" + + +def _profile_attribute() -> str: + override = os.getenv("OKTA_SYNC_PROFILE_ATTRIBUTE", "").strip() + if override: + return override + claim = okta_auth.IDENTITY_CLAIM + return _CLAIM_TO_PROFILE.get(claim, claim) + + +# ── the client ──────────────────────────────────────────────────────────────── +def _fail(reason: str) -> "OktaSyncError": + # One place to build the error, so no call site can add a URL or a header by + # accident. + return OktaSyncError(f"Okta user list could not be fetched: {reason}") + + +def _same_origin(url: str, base: str) -> bool: + a, b = urlparse(url), urlparse(base) + return (a.scheme, a.netloc) == (b.scheme, b.netloc) + + +def _parse_user(item, attribute: str) -> OktaUser: + if not isinstance(item, dict): + raise _fail("a list item is not an object") + status = item.get("status") + profile = item.get("profile") + if not isinstance(status, str) or not status.strip(): + raise _fail("a user has no status") + if not isinstance(profile, dict): + raise _fail("a user has no profile") + value = profile.get(attribute) + if not isinstance(value, str) or not value.strip(): + raise _fail(f"a user has no value for profile attribute {attribute!r}") + return OktaUser(identity=value.strip(), status=status.strip().upper()) + + +def fetch_users(http: Optional[httpx.Client] = None) -> "list[OktaUser]": + """Return every user Okta lists, as OktaUser values. Raises OktaSyncError on + any problem; never returns an empty list. `http` is for tests (a client built + on httpx.MockTransport). In production it is None and a short-lived client is + made here.""" + token = _token() + base = org_url() + if not token: + raise _fail("OKTA_API_TOKEN is not set") + if not base.startswith("https://"): + raise _fail("the org URL is missing or is not https") + attribute = _profile_attribute() + + own_client = http is None + client = http if http is not None else httpx.Client(timeout=TIMEOUT_SECONDS) + headers = {"Accept": "application/json", "Authorization": f"SSWS {token}"} + url: Optional[str] = f"{base}/api/v1/users" + params: Optional[dict] = {"limit": PAGE_LIMIT} + users: "list[OktaUser]" = [] + try: + for _ in range(MAX_PAGES): + if not url: + break + try: + resp = client.get(url, params=params, headers=headers, + follow_redirects=False) + except httpx.HTTPError as exc: + # Class name only. The exception text can carry the URL. + raise _fail(f"network error ({type(exc).__name__})") from None + if resp.status_code != 200: + raise _fail(f"Okta answered HTTP {resp.status_code}") + try: + body = resp.json() + except ValueError: + raise _fail("the response is not JSON") from None + if not isinstance(body, list): + raise _fail("the response is not a list of users") + users.extend(_parse_user(item, attribute) for item in body) + + nxt = resp.links.get("next", {}).get("url") + if not nxt: + url = None + break + if not _same_origin(nxt, base): + # Never send the token to a host that the Link header names. + raise _fail("a next-page link points to a different host") + url, params = nxt, None # the next link already carries its query + else: + # The loop used every page and the last one still named a next page. + raise _fail(f"more than {MAX_PAGES} pages; the list may be cut off") + finally: + if own_client: + client.close() + + if not users: + raise _fail("Okta returned no users, which is not credible for a real org") + log.info("Okta user list fetched: %d user(s)", len(users)) + return users diff --git a/tests/okta_sync_check.py b/tests/okta_sync_check.py new file mode 100644 index 0000000..782deb5 --- /dev/null +++ b/tests/okta_sync_check.py @@ -0,0 +1,235 @@ +#!/usr/bin/env python3 +"""Does the Okta Management API client keep its promises? - D18 / T13.2. + +The one promise that matters: a failure is never an empty list. T13.3 reads an +empty list as "nobody is active", so a client that returned [] when Okta was +down would disable the whole org. Every failure below must raise OktaSyncError. + +Also checked: the client uses its own credential (never the OIDC client secret), +follows pagination, never sends the token to another host, never follows a +redirect, and never lets the token reach a log line, an error message, or +describe(). + +Self-contained: no server, no database, no network, no browser. httpx's +MockTransport stands in for Okta. +Exit 0 all passed, 1 a failure. +""" +import logging +import os +import sys + +ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +sys.path.insert(0, ROOT) + +import httpx # noqa: E402 + +from server import okta_auth, okta_sync # noqa: E402 + +TOKEN = "00tok-SECRET-api-token-xyz" +CLIENT_SECRET = "oidc-client-SECRET-abc" +ORG = "https://example.okta.com" + +fails = 0 + + +def chk(label, ok, extra=""): + global fails + print(("PASS " if ok else "FAIL ") + label + (f" [{extra}]" if (extra and not ok) else "")) + if not ok: + fails += 1 + + +class Capture(logging.Handler): + def __init__(self): + super().__init__() + self.lines = [] + + def emit(self, record): + self.lines.append(record.getMessage()) + + +cap = Capture() +logging.getLogger("wpsuite").addHandler(cap) +logging.getLogger("wpsuite").setLevel(logging.DEBUG) + + +def reset_env(): + os.environ["OKTA_API_TOKEN"] = TOKEN + os.environ["OKTA_CLIENT_SECRET"] = CLIENT_SECRET + os.environ.pop("OKTA_ORG_URL", None) + os.environ.pop("OKTA_SYNC_PROFILE_ATTRIBUTE", None) + okta_auth.ISSUER = f"{ORG}/oauth2/default" + okta_auth.IDENTITY_CLAIM = "preferred_username" + + +def user(login, status="ACTIVE", **profile): + p = {"login": login, "email": login} + p.update(profile) + return {"id": "00u" + login, "status": status, "profile": p} + + +def client(handler): + return httpx.Client(transport=httpx.MockTransport(handler)) + + +def raises(handler, label, **kw): + """Run fetch_users against `handler`; it must raise OktaSyncError, and the + message must not hold the token.""" + reset_env() + try: + out = okta_sync.fetch_users(http=client(handler)) + except okta_sync.OktaSyncError as exc: + msg = str(exc) + clean = TOKEN not in msg and CLIENT_SECRET not in msg and "example.okta.com" not in msg + chk(f"{label}: raises, message has no token or host", clean, msg) + return msg + except Exception as exc: # the wrong exception type + chk(f"{label}: raises OktaSyncError", False, f"{type(exc).__name__}: {exc}") + return "" + chk(f"{label}: raises (did NOT raise, returned {out!r})", False) + return "" + + +def ok(body): + return lambda req: httpx.Response(200, json=body) + + +# ── 1. a good fetch ─────────────────────────────────────────────────────────── +print("\n1. a good fetch") +reset_env() +seen = [] + + +def good(req): + seen.append(req) + return httpx.Response(200, json=[user("alice", "ACTIVE"), user("bob", "suspended")]) + + +users = okta_sync.fetch_users(http=client(good)) +chk("returns every user", [u.identity for u in users] == ["alice", "bob"]) +chk("status is upper case", [u.status for u in users] == ["ACTIVE", "SUSPENDED"]) +chk("asks the users endpoint of the org", str(seen[0].url).startswith(f"{ORG}/api/v1/users")) +chk("asks for the page maximum", seen[0].url.params.get("limit") == "200") +chk("authenticates with the API token (SSWS)", seen[0].headers.get("authorization") == f"SSWS {TOKEN}") +chk("never sends the OIDC client secret", CLIENT_SECRET not in str(seen[0].headers)) + +# ── 2. pagination ───────────────────────────────────────────────────────────── +print("\n2. pagination") +reset_env() +calls = [] + + +def paged(req): + calls.append(req) + if "after=p2" not in str(req.url): + return httpx.Response(200, json=[user("alice")], + headers={"Link": f'<{ORG}/api/v1/users?limit=200&after=p2>; rel="next"'}) + return httpx.Response(200, json=[user("bob")]) + + +users = okta_sync.fetch_users(http=client(paged)) +chk("follows the next link and returns both pages", [u.identity for u in users] == ["alice", "bob"]) +chk("two requests, no more", len(calls) == 2) +chk("page 2 also carries the token", calls[1].headers.get("authorization") == f"SSWS {TOKEN}") + +# ── 3. the failure rule: an error is never an empty list ────────────────────── +print("\n3. every failure raises (never returns an empty list)") +for code in (401, 403, 404, 429, 500, 502, 503): + raises(lambda req, c=code: httpx.Response(c, json={"errorCode": "x"}), f"HTTP {code}") +raises(lambda req: httpx.Response(302, headers={"Location": "https://evil.example/"}), "a redirect (never followed)") +raises(lambda req: (_ for _ in ()).throw(httpx.ConnectError("boom to https://example.okta.com/api/v1/users")), "connection error") +raises(lambda req: (_ for _ in ()).throw(httpx.ReadTimeout("slow")), "timeout") +raises(lambda req: httpx.Response(200, text="not json"), "body is not JSON") +raises(ok({"errorCode": "E0000011"}), "body is an object, not a list") +raises(ok("a string"), "body is a string") +raises(ok([]), "an empty list (not credible for a real org)") +raises(ok(["alice"]), "an item that is not an object") +raises(ok([{"profile": {"login": "a"}}]), "an item with no status") +raises(ok([{"status": "ACTIVE"}]), "an item with no profile") +raises(ok([{"status": "ACTIVE", "profile": {}}]), "an item with no login") +raises(ok([{"status": "ACTIVE", "profile": {"login": " "}}]), "an item with a blank login") +raises(ok([user("alice"), {"status": "ACTIVE", "profile": {}}]), "one bad item among good ones (never skipped)") + +# ── 4. misconfiguration raises ──────────────────────────────────────────────── +print("\n4. misconfiguration") +reset_env() +os.environ["OKTA_API_TOKEN"] = "" +try: + okta_sync.fetch_users(http=client(good)) + chk("no token raises", False) +except okta_sync.OktaSyncError: + chk("no token raises", True) +reset_env() +okta_auth.ISSUER = "" +try: + okta_sync.fetch_users(http=client(good)) + chk("no org URL raises", False) +except okta_sync.OktaSyncError: + chk("no org URL raises", True) +reset_env() +os.environ["OKTA_ORG_URL"] = "http://example.okta.com" +sent = [] +try: + okta_sync.fetch_users(http=client(lambda r: sent.append(r) or httpx.Response(200, json=[user("a")]))) + chk("an http org URL raises", False) +except okta_sync.OktaSyncError: + chk("an http org URL raises", True) +chk("...and no request was made (token never sent over http)", sent == []) + +# ── 5. never leaks the token to another host, never loops forever ───────────── +print("\n5. next-link safety") +reset_env() +hosts = [] + + +def evil_link(req): + hosts.append(req.url.host) + return httpx.Response(200, json=[user("alice")], + headers={"Link": '; rel="next"'}) + + +raises(evil_link, "a next link to another host") +chk("...the other host was never contacted", hosts == ["example.okta.com"]) + +count = [] + + +def endless(req): + count.append(1) + return httpx.Response(200, json=[user("alice")], + headers={"Link": f'<{ORG}/api/v1/users?after={len(count)}>; rel="next"'}) + + +raises(endless, "an endless next chain (page cap)") +chk(f"...stops at the cap ({okta_sync.MAX_PAGES} requests)", len(count) == okta_sync.MAX_PAGES, str(len(count))) + +# ── 6. org URL and identity attribute ───────────────────────────────────────── +print("\n6. org URL and identity attribute") +reset_env() +chk("org URL is the issuer's scheme and host", okta_sync.org_url() == ORG) +os.environ["OKTA_ORG_URL"] = "https://corp.okta.com/" +chk("OKTA_ORG_URL wins, trailing slash removed", okta_sync.org_url() == "https://corp.okta.com") +reset_env() +okta_auth.IDENTITY_CLAIM = "email" +body = [{"status": "ACTIVE", "profile": {"login": "alice", "email": "alice@x.com"}}] +chk("claim 'email' reads profile.email", okta_sync.fetch_users(http=client(ok(body)))[0].identity == "alice@x.com") +okta_auth.IDENTITY_CLAIM = "sAMAccountName" +body = [{"status": "ACTIVE", "profile": {"login": "alice@x.com", "sAMAccountName": "alice"}}] +chk("a custom claim reads profile[]", okta_sync.fetch_users(http=client(ok(body)))[0].identity == "alice") +os.environ["OKTA_SYNC_PROFILE_ATTRIBUTE"] = "login" +chk("OKTA_SYNC_PROFILE_ATTRIBUTE overrides", okta_sync.fetch_users(http=client(ok(body)))[0].identity == "alice@x.com") + +# ── 7. the token never leaks ────────────────────────────────────────────────── +print("\n7. the token never leaks") +reset_env() +chk("describe() has no token", TOKEN not in okta_sync.describe() and "configured" in okta_sync.describe()) +os.environ["OKTA_API_TOKEN"] = "" +chk("describe() says DISABLED without a token", "DISABLED" in okta_sync.describe()) +reset_env() +every_log = " ".join(cap.lines) +chk("no log line holds the API token", TOKEN not in every_log) +chk("no log line holds the client secret", CLIENT_SECRET not in every_log) + +print() +print("ALL PASSED" if not fails else f"{fails} FAILED") +sys.exit(0 if not fails else 1)