In CYPEX, an Organization is the unit of multi-tenancy. Isolation is
enforced in PostgreSQL by Row-Level Security policies that read the request
JWT, not by filters in application code. Application traffic — the generated
UI, PostgREST API clients, and the backend’s end-user request path — is
subject to the same policies, so reaching the database through a different
client does not widen what a user can see.
Organizations are not an authorization system on their own. They add a
per-request data scope on top of the PostgreSQL role grants that decide
what a user may do.
Every SSO identity CYPEX has ever seen sits in sso_gateway.t_sso_user_map in exactly one of three states (sso_gateway.user_map_status): pending, active, or rejected. This page documents the full lifecycle — what moves a row between states, what each transition writes to the audit trail, and where to find evidence of a governance decision. For adding a provider and the first successful sign-in, see the OIDC setup guide.
| State | Meaning | What a repeat login does |
|---|
| Pending | IdP authentication succeeded, but no t_sso_role_mapping rule matched and (if Auto-link by email is off, the default) no admin has reviewed it yet. cypex_user_id and cypex_role are both NULL. | Refreshes the captured profile in place, stays pending. The exchange returns 403 pending_approval — “Your account is pending administrator approval.” |
| Active | An admin approved or linked the identity, or a role mapping matched automatically. cypex_user_id and cypex_role are set. | Signs in normally; mints an access/refresh token pair like any other login. |
| Rejected | An admin explicitly rejected the identity. The row is kept (not deleted) — rejected_at, rejected_by, and an optional rejection_reason (≤200 characters) are recorded. | Blocked. The exchange returns 403 user_rejected — a deliberately generic “This SSO identity has been blocked. Contact your administrator.” The real reason and who rejected it never reach the browser; they’re in the audit trail only. |
Users → Pending SSO and Users → Rejected SSO are the two admin-facing queues for the states above:
A change that affects a tenant boundary should be reconstructable afterwards.
CYPEX records part of that automatically and leaves the rest to you. This page
documents the three layers where evidence lives, in order of increasing
persistence:
- The permission audit log — queryable in PostgreSQL.
- The write path — what CYPEX captures automatically, and what it does not.
- Documentation approvals — recorded in product docs and release notes.
If you make a non-trivial decision about an Organization (split, merge, role
remap, schema revoke), keep the audit query and its output with the change
record, and add an ADR-style note under
CYPEX internals.
