Nothing configures Python logging and gunicorn only configures its own loggers, so INFO lines from wpsuite.* were dropped: with the production launch command a healthy start printed no Okta lines, and an operator could not tell the sync was off from on-and-quiet. okta_sync's logger now has its own stderr handler, only when the root logger has none. Verified with real gunicorn, 2 workers, with and without a token. Other modules' output is unchanged.
480 lines
22 KiB
Python
480 lines
22 KiB
Python
"""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
|
|
|
|
T13.3 (the sync job, `run_sync` below) uses that list to disable local accounts.
|
|
Its rules are in its own docstring. In short: it only ever disables, it never
|
|
re-enables, it writes one audit row per change, and any failure means NO change.
|
|
|
|
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
|
|
import threading
|
|
import time
|
|
import uuid
|
|
from datetime import datetime, timedelta, timezone
|
|
from dataclasses import dataclass, field
|
|
from typing import Callable, Optional
|
|
from urllib.parse import urlparse
|
|
|
|
import httpx
|
|
from sqlalchemy import select, update
|
|
from sqlalchemy.exc import IntegrityError
|
|
from sqlalchemy.orm import Session
|
|
|
|
from . import models, okta_auth
|
|
|
|
log = logging.getLogger("wpsuite.okta_sync")
|
|
|
|
|
|
def _make_logs_visible() -> None:
|
|
"""Make this module's INFO lines reach `docker compose logs api`.
|
|
|
|
Nothing in this app configures Python logging, and gunicorn only configures its
|
|
own loggers. So the root logger sits at WARNING with no handler, and every
|
|
INFO line from a `wpsuite.*` logger is dropped. Found on 2026-10-16: with the
|
|
exact production launch command, `grep "Okta sync"` found nothing on a healthy
|
|
start, because "configured", "scheduled" and "done" are INFO lines. Warnings
|
|
and errors (a disable, a skipped run) showed, but the lines that say the sync
|
|
is alive did not. An operator cannot tell "off" from "on and quiet".
|
|
|
|
This adds one stderr handler to THIS module's logger only, and only when the
|
|
root logger has none, so it never doubles up if logging is configured later and
|
|
it does not change what any other module prints. (BL-028 and the general
|
|
question of app-wide logging are separate items.)"""
|
|
if log.handlers or logging.getLogger().handlers:
|
|
return
|
|
handler = logging.StreamHandler()
|
|
handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))
|
|
log.addHandler(handler)
|
|
log.setLevel(logging.INFO)
|
|
|
|
|
|
_make_logs_visible()
|
|
|
|
# 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
|
|
# The whole fetch, all pages together, must finish inside this. T13.4 relies on it:
|
|
# a run is always shorter than the shortest allowed interval, so one cycle can
|
|
# never still be running when the next is due.
|
|
TOTAL_DEADLINE_SECONDS = 120.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]" = []
|
|
started = time.monotonic()
|
|
try:
|
|
for _ in range(MAX_PAGES):
|
|
if not url:
|
|
break
|
|
if time.monotonic() - started > TOTAL_DEADLINE_SECONDS:
|
|
raise _fail(f"took longer than {int(TOTAL_DEADLINE_SECONDS)} seconds in total")
|
|
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
|
|
|
|
|
|
# ── T13.3: the sync job ───────────────────────────────────────────────────────
|
|
# Which Okta statuses mean "this person is gone or was blocked on purpose".
|
|
# Decided by Matt, 2026-10-16: a literal "anything that is not ACTIVE" would also
|
|
# catch PASSWORD_EXPIRED, LOCKED_OUT and RECOVERY, which people leave on their
|
|
# own, and because this job never re-enables, one AD password expiry would lock a
|
|
# person out of this app until an admin stepped in. A user who is MISSING from the
|
|
# list disables too (Okta's default list leaves out DEPROVISIONED users).
|
|
DISABLING_STATUSES = frozenset({"SUSPENDED", "DEPROVISIONED"})
|
|
|
|
SYNC_ACTOR = "system:okta_sync"
|
|
SYNC_ACTION = "user_deprovisioned_by_sync"
|
|
|
|
|
|
@dataclass
|
|
class SyncResult:
|
|
ok: bool # False = the run took NO action at all
|
|
error: str = "" # why, when ok is False
|
|
okta_users: int = 0 # size of the Okta list
|
|
checked: int = 0 # active local accounts looked at
|
|
disabled: "list[str]" = field(default_factory=list) # usernames disabled this run
|
|
|
|
|
|
def _gen_id(prefix: str) -> str:
|
|
# Same shape as server/app.py gen_id. Not imported: app.py will import this
|
|
# module (T13.4), and the reverse import would be circular.
|
|
return f"{prefix}_{uuid.uuid4().hex[:12]}"
|
|
|
|
|
|
def run_sync(db: Session, fetch: Optional[Callable[[], "list[OktaUser]"]] = None) -> SyncResult:
|
|
"""Compare the Okta user list to local accounts and disable the ones Okta no
|
|
longer vouches for.
|
|
|
|
The rules, none of which may be relaxed (D18):
|
|
|
|
1. FAIL CLOSED. If fetching raises ANY exception, or the answer cannot be
|
|
trusted, this function changes nothing and writes nothing. A failure is
|
|
never read as "nobody is active". The fetch happens before the database
|
|
is read, so there is no code path from a failed fetch to a change.
|
|
2. ONLY DISABLE. It sets is_active to False. No input makes it set True.
|
|
An account that is already disabled is not touched and gets no new
|
|
audit row, so a run that finds nothing new writes nothing.
|
|
3. One AuditLog row per disabled account, actor "system:okta_sync", so it
|
|
is never confused with an admin's action. Rows and changes are saved in
|
|
one transaction. If saving fails, none of it is kept.
|
|
4. Only changes are logged. A person who is still active in Okta and still
|
|
active here produces no row.
|
|
|
|
One guard beyond the rules above, inside decision 4's "anything the sync can't
|
|
confidently parse": if there are active local accounts and NONE of them
|
|
matches any Okta user, the identity attribute is almost certainly wrong (see
|
|
OKTA_SYNC_PROFILE_ATTRIBUTE). That is a setup mistake, not an offboarding of
|
|
the whole company, so the run is refused and nothing changes.
|
|
|
|
A local account matches an Okta user by username or by email, ignoring case,
|
|
the same two fields auth.find_user() uses. If the Okta list holds the same
|
|
identity twice with different statuses, the account is disabled only when
|
|
every one of them is a disabling status.
|
|
|
|
`fetch` is for tests. In production it is None and fetch_users() is used.
|
|
"""
|
|
fetch = fetch or fetch_users
|
|
|
|
# 1. The fetch. Nothing below runs unless it returned a list.
|
|
try:
|
|
okta_users = fetch()
|
|
except Exception as exc: # an error of ANY kind, not only OktaSyncError
|
|
msg = str(exc) if isinstance(exc, OktaSyncError) else f"unexpected {type(exc).__name__}"
|
|
log.error("Okta sync SKIPPED, no account was changed: %s", msg)
|
|
return SyncResult(ok=False, error=msg)
|
|
if not okta_users:
|
|
# fetch_users() already raises on an empty list. This covers a stand-in
|
|
# fetch (and any future change) that returns one: same rule.
|
|
msg = "the fetch returned no users"
|
|
log.error("Okta sync SKIPPED, no account was changed: %s", msg)
|
|
return SyncResult(ok=False, error=msg)
|
|
|
|
try:
|
|
by_identity: "dict[str, list[str]]" = {}
|
|
for u in okta_users:
|
|
by_identity.setdefault(u.identity.strip().lower(), []).append(u.status.strip().upper())
|
|
|
|
locals_ = list(db.scalars(select(models.User).where(models.User.is_active.is_(True))))
|
|
plan: "list[tuple[models.User, str]]" = []
|
|
matched = 0
|
|
for local in locals_:
|
|
statuses: "list[str]" = []
|
|
for key in {(local.username or "").strip().lower(), (local.email or "").strip().lower()}:
|
|
if key:
|
|
statuses.extend(by_identity.get(key, []))
|
|
if statuses:
|
|
matched += 1
|
|
if all(st in DISABLING_STATUSES for st in statuses):
|
|
plan.append((local, sorted(set(statuses))[0]))
|
|
else:
|
|
plan.append((local, "MISSING"))
|
|
|
|
if locals_ and matched == 0:
|
|
msg = (f"none of {len(locals_)} active local account(s) matches any of "
|
|
f"{len(okta_users)} Okta user(s); the identity attribute is probably wrong")
|
|
log.error("Okta sync SKIPPED, no account was changed: %s", msg)
|
|
return SyncResult(ok=False, error=msg, okta_users=len(okta_users), checked=len(locals_))
|
|
|
|
planned = [(local.username, status) for local, status in plan]
|
|
checked = len(locals_)
|
|
for local, status in plan:
|
|
local.is_active = False
|
|
db.add(models.AuditLog(
|
|
id=_gen_id("ev"), actor=SYNC_ACTOR, action=SYNC_ACTION,
|
|
entity_type="user", entity_id=local.id, project_id=None,
|
|
summary=local.username[:400],
|
|
detail={"okta_status": status, "via": "okta_sync"},
|
|
))
|
|
db.commit()
|
|
except Exception as exc:
|
|
db.rollback()
|
|
log.error("Okta sync FAILED, nothing was kept: unexpected %s", type(exc).__name__)
|
|
return SyncResult(ok=False, error=f"unexpected {type(exc).__name__}")
|
|
|
|
for name, status in planned:
|
|
log.warning("Okta sync disabled %r (Okta status: %s)", name, status)
|
|
log.info("Okta sync done: %d Okta user(s), %d active local account(s) checked, %d disabled",
|
|
len(okta_users), checked, len(planned))
|
|
return SyncResult(ok=True, okta_users=len(okta_users), checked=checked,
|
|
disabled=[name for name, _ in planned])
|
|
|
|
|
|
# ── T13.4: running it on a schedule ───────────────────────────────────────────
|
|
# The api container runs gunicorn with 2 workers, and a later deploy may run more
|
|
# than one container. Each worker starts its own timer thread below. Without a
|
|
# gate, all of them would call Okta every cycle and write overlapping changes.
|
|
# The gate is one row in app_settings (key "okta_sync"). Its updated_at is "when
|
|
# the last run was claimed". A worker claims a run with ONE atomic conditional
|
|
# UPDATE: it succeeds only if the last claim is older than the interval. Exactly
|
|
# one worker wins each cycle, on SQLite and on Postgres, with no lock held.
|
|
#
|
|
# The row survives a restart, so a restart inside the interval does not start a
|
|
# second run. A slow run cannot overlap the next: a fetch is bounded to
|
|
# TOTAL_DEADLINE_SECONDS (120) and the interval can never be set below
|
|
# INTERVAL_MIN_SECONDS (300). Inside one process the timer thread runs one cycle at
|
|
# a time, so cycles cannot stack there either.
|
|
CLAIM_KEY = "okta_sync"
|
|
INTERVAL_DEFAULT_SECONDS = 900 # 15 minutes (D18, proposed, not confirmed)
|
|
INTERVAL_MIN_SECONDS = 300
|
|
TICK_SECONDS = 60 # how often each worker checks if a run is due
|
|
START_DELAY_SECONDS = 10 # let the app finish starting first
|
|
|
|
|
|
def interval_seconds() -> int:
|
|
"""OKTA_SYNC_INTERVAL_SECONDS, default 900. A value that is not a number uses
|
|
the default. A value under 300 is raised to 300 (see above for why)."""
|
|
raw = os.getenv("OKTA_SYNC_INTERVAL_SECONDS", "").strip()
|
|
if not raw:
|
|
return INTERVAL_DEFAULT_SECONDS
|
|
try:
|
|
value = int(raw)
|
|
except ValueError:
|
|
log.warning("OKTA_SYNC_INTERVAL_SECONDS=%r is not a whole number; using %d",
|
|
raw, INTERVAL_DEFAULT_SECONDS)
|
|
return INTERVAL_DEFAULT_SECONDS
|
|
if value < INTERVAL_MIN_SECONDS:
|
|
log.warning("OKTA_SYNC_INTERVAL_SECONDS=%d is under the minimum; using %d",
|
|
value, INTERVAL_MIN_SECONDS)
|
|
return INTERVAL_MIN_SECONDS
|
|
return value
|
|
|
|
|
|
def claim(db: Session, interval: int, now: Optional[datetime] = None) -> bool:
|
|
"""Try to claim this cycle. True for exactly one caller per interval."""
|
|
now = now or datetime.now(timezone.utc)
|
|
cutoff = now - timedelta(seconds=interval)
|
|
try:
|
|
row = db.get(models.AppSetting, CLAIM_KEY)
|
|
if row is None:
|
|
db.add(models.AppSetting(key=CLAIM_KEY, value={}, updated_at=now))
|
|
db.commit() # the insert is the claim
|
|
return True
|
|
except IntegrityError:
|
|
db.rollback() # another worker inserted first: it won
|
|
return False
|
|
db.rollback() # end the read; the UPDATE starts fresh
|
|
result = db.execute(
|
|
update(models.AppSetting)
|
|
.where(models.AppSetting.key == CLAIM_KEY, models.AppSetting.updated_at <= cutoff)
|
|
.values(updated_at=now)
|
|
)
|
|
db.commit()
|
|
return result.rowcount == 1
|
|
|
|
|
|
def run_if_due(session_factory: Callable[[], Session],
|
|
fetch: Optional[Callable[[], "list[OktaUser]"]] = None,
|
|
now: Optional[datetime] = None) -> Optional[SyncResult]:
|
|
"""One timer tick: claim the cycle, and if it is ours, run the sync. Returns
|
|
the SyncResult, or None when the cycle was not ours (or could not be claimed).
|
|
Nothing here can turn a failure into a change: run_sync() owns that rule, and
|
|
anything that goes wrong around it is logged and ends the tick."""
|
|
try:
|
|
with session_factory() as db:
|
|
if not claim(db, interval_seconds(), now=now):
|
|
return None
|
|
with session_factory() as db:
|
|
return run_sync(db, fetch=fetch)
|
|
except Exception as exc:
|
|
log.error("Okta sync tick failed, no account was changed: unexpected %s", type(exc).__name__)
|
|
return None
|
|
|
|
|
|
def start_scheduler(session_factory: Callable[[], Session]) -> "Optional[threading.Event]":
|
|
"""Start the timer thread. Returns a stop Event (set it to end the thread), or
|
|
None when the sync is off because OKTA_API_TOKEN or the org URL is missing.
|
|
Logs one line either way, so an operator can see it in `docker compose logs api`."""
|
|
log.info(describe())
|
|
if not is_configured():
|
|
return None
|
|
stop = threading.Event()
|
|
|
|
def loop():
|
|
if stop.wait(START_DELAY_SECONDS):
|
|
return
|
|
while not stop.is_set():
|
|
run_if_due(session_factory)
|
|
if stop.wait(TICK_SECONDS):
|
|
return
|
|
|
|
threading.Thread(target=loop, name="okta-sync", daemon=True).start()
|
|
log.info("Okta sync scheduled: every %d seconds (checked each %d s by every worker; "
|
|
"one wins each cycle)", interval_seconds(), TICK_SECONDS)
|
|
return stop
|