Identity, roles and access
This guide documents the central identity-service implementation, the role-to-workspace mapping used by its API, and the security controls that must be present before the identity path is treated as production-ready.
The current open portal preview does not enforce workspace access by default. The client flag NEXT_PUBLIC_CEDA_ACCESS_ENFORCEMENT is false unless explicitly enabled at build time. The identity API is a separate server-side implementation that expects a Cloudflare D1 binding named CEDA_DB and the CEDA_BOOTSTRAP_SECRET. Do not treat descriptive role labels in preview screens as enforced permissions.
1. Role-to-workspace mapping
The identity route defines the following default workspace assignment:
| Role ID | Default workspace | Intended responsibility |
|---|---|---|
| platform_admin | admin | Platform accounts and access administration |
| funding_programme_admin | operations | Funding programme and operational administration |
| eligibility_reviewer | operations | Initial eligibility review |
| evaluator | evaluator | Independent application assessment |
| adjudicator | adjudication | Panel deliberation and decision recording |
| applicant_lead | applicant | Applicant organisation and team lead |
| applicant_team | applicant | Applicant team contribution |
| innovation_rules_manager | innovation-rules | Programme, eligibility, evidence, rubric and workflow configuration |
The API stores workspace assignments as a JSON array on the identity user row. The mapping is defined in apps/web/app/api/ceda/identity/[action]/route.ts. It is the API's default mapping, not proof that the open preview navigation is already gated by those values.
2. Identity data model
Table responsibilities
- identity_users holds the account, role, workspace assignment, status, password hash and onboarding fields.
- identity_invitations holds only a hash of the invitation or password-reset token, its purpose, status and expiry.
- identity_sessions holds only a hash of the opaque session token, expiry and revocation timestamp.
- identity_audit records the actor, action, target, metadata and event time.
- The invited_by references allow user creation and invitation activity to be attributed to an account.
The schema is created by apps/web/migrations/ceda/0001_identity.sql. Foreign-key relationships express ownership and attribution; application code must still validate allowed transitions and actor permissions.
3. Initial administrator bootstrap
The bootstrap endpoint is intended for one-time initial setup. It rejects a missing or incorrect bootstrap secret and checks whether a platform administrator already exists. Passwords are derived with PBKDF2 using SHA-256 and a per-password random salt. A successful bootstrap creates an active, role-approved platform administrator, opens a session and records an audit event.
The bootstrap secret must be a server-side secret, not a value embedded in client code or committed to the repository. Once the first administrator exists, the endpoint refuses to create another initial administrator.
4. Password login and session validation
Session implementation details in the identity route:
- Cookie name: ceda_identity_session.
- Cookie flags: HttpOnly, SameSite=Lax, path=/; Secure is enabled for HTTPS requests.
- The browser receives a random opaque token. D1 stores its SHA-256 hash, not the raw token.
- Session expiry defaults to seven days. CEDA_SESSION_DAYS can select a value from one to thirty days.
- Session lookup requires a non-revoked, non-expired session and an active user with role_approved set to 1.
- Logout revokes the matching session record and clears the cookie.
A client-side profile object is not an authorization credential. Protected endpoints must resolve the session on the server.
5. Invitation and guided onboarding
Delegated onboarding rules
- A platform administrator can invite any role in the API's declared role list.
- A non-platform administrator must have can_onboard_others enabled and can invite applicant_team only.
- The invitee must set a password before completing onboarding.
- Invitation tokens are random and one-time; only their hashes are stored.
- The current API returns the invitation token to the authenticated caller. Email delivery is not implemented by this route. A secure delivery channel and notification service must be integrated before invitations are described as automatically emailed.
The open Administration preview account form is not this identity flow. It creates descriptive browser-local sample data and must not be used to send real invitations.
6. Account and invitation state model
This diagram combines the user-account lifecycle and the related invitation lifecycle at a conceptual level. The database represents user status separately from invitation status. Invitation status is pending, completed or revoked; account status is invited, active, suspended or revoked.
A pending invitation expires based on expires_at. Expiration makes the token unusable but does not itself delete the user row. Resending rotates the token hash and resets the expiry. Suspending an active account revokes its active sessions. Password reset also revokes active sessions so the user must authenticate again.
7. API trust boundaries and guards
The POST handler rejects a supplied cross-origin Origin header when it does not match the request origin. Authenticated actions resolve the cookie against D1. Administrative actions additionally require platform_admin. The public bootstrap, login, invitation lookup and password completion actions have their own explicit token or secret checks.
Implementation rule: adding a new identity action requires an explicit decision about whether it is public-token based, authenticated-user based, or administrator-only. Do not rely on client visibility or a disabled button as the access-control mechanism.
8. Deployment requirements for the identity path
The identity route obtains its environment using getCloudflareContext and expects:
| Binding or variable | Purpose |
|---|---|
| CEDA_DB | D1 database binding used by the identity service |
| CEDA_BOOTSTRAP_SECRET | One-time initial administrator bootstrap secret |
| CEDA_SESSION_DAYS | Optional session lifetime, clamped to 1–30 days |
| NEXT_PUBLIC_CEDA_ACCESS_ENFORCEMENT | Build-time client workspace gate; false by default |
The current preview Wrangler configuration defines the Worker and static assets, but does not itself declare the CEDA_DB binding. Therefore, do not assume the deployed preview has an active identity database simply because the route exists in source code.
Related implementation files
- apps/web/app/api/ceda/identity/[action]/route.ts
- apps/web/migrations/ceda/0001_identity.sql
- apps/web/lib/ceda/access-mode.ts
- apps/web/components/ceda/CedaOnboardingWorkspace.tsx
- apps/web/components/ceda/CedaAdminWorkspace.tsx