Identity and Access Model (SSO + RBAC)

This document describes how CepatEdge should integrate with an institution’s Identity Provider (IdP) and how identities map into our RBAC roles. It is design-first: the goal is to have a clear model before wiring code.

---

1. OIDC vs SAML – Which to Use First?

OIDC (OpenID Connect) and SAML 2.0 are both standard ways to implement SSO.

• OIDC
  • Built on top of OAuth 2.0; JSON/HTTP/REST friendly.
  • Works very naturally with SPAs and APIs (access tokens, ID tokens).
  • Most modern IdPs (Azure AD, Okta, Auth0, Keycloak) support it very well.
• SAML
  • XML-based; older but still very common in universities.
  • Often the “default” for legacy on‑prem IdPs and many existing SSO integrations.

Recommendation for CepatEdge:

• Prioritise OIDC as the first implementation (cleaner with Workers + SPA + API).
• Be prepared to support SAML later if the university’s IdP team strongly prefers it.

For this design, we assume OIDC with an enterprise IdP (e.g. Azure AD).

---

2. IdP → CepatEdge Role Mapping

We assume the IdP exposes either:

• Groups (e.g. MAINT-EMPLOYEE, MAINT-HOD, MAINT-TECH), or
• Role claims (e.g. maintenanceRole: "employee").

2.1 Core roles in CepatEdge

• employee – can create and manage their own maintenance requests.
• technician – can see and work on assigned requests.
• department_head – can approve and assign within their department.
• admin – can manage users, see everything, and configure the system.

2.2 Example group → role mapping (Azure AD style)

IdP group / attribute	CepatEdge role
MAINT-EMPLOYEE	employee
MAINT-TECHNICIAN	technician
MAINT-HOD	department_head
MAINT-ADMIN	admin

Rules:

• If a user is in multiple groups, apply a deterministic priority:
  • admin > department_head > technician > employee.
• Role mapping is computed at login based on IdP claims and stored in:
  • The session, and
  • A Neon user/roles table for auditing and offline checks.

---

3. High-Level Login / Logout Flows

We keep this simple and align with a modern OIDC flow.

3.1 Login (happy path)

1. User hits CepatEdge SPA and clicks “Login with University SSO”.
2. SPA redirects to IdP (OIDC authorization endpoint).
3. User authenticates with IdP (password/MFA/etc.).
4. IdP redirects back with an authorization code.
5. Backend (Workers) exchanges code for ID token + access token from IdP.
6. Backend verifies the ID token (signature, issuer, audience, expiry).
7. Backend reads user identifier + groups/roles from token claims.
8. Backend:
   • Creates/updates user in Neon (including mapped CepatEdge role).
   • Issues CepatEdge access token (short-lived) and refresh token.
9. SPA stores the CepatEdge tokens (e.g. HttpOnly cookies) and proceeds.

3.2 Logout

1. User clicks “Logout” in SPA.
2. Backend:
   • Invalidates the current session / refresh token (see token lifecycle doc).
   • Optionally calls IdP’s logout endpoint (front-channel/back-channel).
3. SPA clears any local state and returns to a logged-out view.

The detailed token lifetime and revocation model is described in
token-lifecycle-and-revocation.md.