T13.2: Okta Management API client (D18)

New server/okta_sync.py: lists every Okta user and status with its own
read-only credential (OKTA_API_TOKEN, SSWS), separate from the OIDC client.
Follows pagination. Every failure raises OktaSyncError; an error is never an
empty list, because T13.3 reads an empty list as "nobody is active".

Also refuses: a next-page link to another host (token never leaves the org),
a redirect, a chain over 50 pages (a cut-off list looks like missing users),
a bad item among good ones (never skipped), and an empty list.

tests/okta_sync_check.py: 52 checks, self-contained (httpx MockTransport).
Not wired into app.py yet. T13.3 uses it; T13.4 starts it on a schedule.
This commit is contained in:
2026-10-16 11:28:57 -07:00
parent da1325c8a1
commit 2f7de6e33b
4 changed files with 472 additions and 4 deletions

View File

@@ -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.)*
---

View File

@@ -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

205
server/okta_sync.py Normal file
View File

@@ -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[<claim>] (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

235
tests/okta_sync_check.py Normal file
View File

@@ -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="<html>not json</html>"), "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": '<https://evil.example/steal>; 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[<claim>]", 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)