Skip to main content

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.

Preview versus identity service

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 IDDefault workspaceIntended responsibility
platform_adminadminPlatform accounts and access administration
funding_programme_adminoperationsFunding programme and operational administration
eligibility_revieweroperationsInitial eligibility review
evaluatorevaluatorIndependent application assessment
adjudicatoradjudicationPanel deliberation and decision recording
applicant_leadapplicantApplicant organisation and team lead
applicant_teamapplicantApplicant team contribution
innovation_rules_managerinnovation-rulesProgramme, 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 variablePurpose
CEDA_DBD1 database binding used by the identity service
CEDA_BOOTSTRAP_SECRETOne-time initial administrator bootstrap secret
CEDA_SESSION_DAYSOptional session lifetime, clamped to 1–30 days
NEXT_PUBLIC_CEDA_ACCESS_ENFORCEMENTBuild-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.

  • 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