13.1 Identity and access

User stories

• As an admin, I want to create a new internal user with a defined role so they can access only what they need.
• As an internal user, I want to log in via SSO with MFA so I don’t need to manage a password.
• As an InfoSec officer, I want a quarterly access review report so I can revoke stale access.
• As a system, I want to revoke all access for a user the moment they leave so there is no residual risk.
• As a borrower, I want to log in via mobile OTP so I don’t need to remember a password.

API requirements

• POST /admin/users, PUT /admin/users/{id}, DELETE.
• POST /admin/roles, PUT /admin/roles/{id}/permissions.
• GET /admin/access-review?period={p}.
• POST /auth/sso/oidc/callback.
• POST /auth/borrower/otp, POST /auth/borrower/verify.

Data model

• user, role, permission, role_permission, user_role, access_review, audit_event.

UI screens

• Admin: User list, user edit, role list, role edit, permission matrix, access review queue.
• Borrower: Login (mobile OTP), MFA setup if mobile app.

Backend services

• Auth service (OIDC + borrower OTP).
• RBAC service (centralised permission check).
• Audit service (every action emits).

External integrations

• Google Workspace / Microsoft Entra ID / Okta (SSO).
• TOTP authenticator apps.
• SMS vendor for borrower OTP.

Test cases

• Successful SSO login with MFA.
• Failed MFA → block.
• Role change reflected immediately in active session.
• Leaver revocation effective within 5 min.
• Borrower mobile OTP throttling on retry abuse.

Edge cases

• SSO provider downtime → emergency local-admin path with separate audit.
• User with stale active session after role change.
• Borrower with shared mobile number.
• Mobile-OTP delivery failure (network).
• SIM-swap fraud signal.

Acceptance criteria

• All internal users on SSO + MFA.
• RBAC enforced on every API.
• Quarterly access review runs end-to-end.
• Leaver workflow ≤ 1 hour revocation.
• Borrower OTP success rate > 95%.