Authorisation — RBAC Model - PensionsPortal.ie

PensionsPortal.ie enforces a role-based access control (RBAC) model with four roles and mandatory tenant scoping. Every API route checks both the user’s role and their brokerId / employerId before returning or mutating data.

Role Definitions

Role (DB)	Session Role	Description
`SuperAdmin`	`admin`	Full platform access. No broker or employer scope restriction. Reserved for platform operators.
`BrokerAdmin`	`broker`	Full access within their `brokerId`. Manages schemes, members, compliance tasks for their clients.
`BrokerUser`	`broker`	Same data scope as BrokerAdmin. UI may restrict specific administrative actions.
`Trustee`	`employer`	Scoped to their `employerId`. Can view scheme data and submit required information.

member role is defined in the type system for future member-portal use but is not currently active in the application UI.

Tenant Scoping

Multi-tenancy is enforced structurally, not just by convention. Every database query that returns scheme, member, or employer data includes a brokerId or employerId filter derived from the authenticated session:

// Example: broker can only see schemes belonging to their brokerId
const schemes = await db
  .select()
  .from(schemesTable)
  .where(eq(schemesTable.brokerId, session.user.brokerId))

A broker user cannot access another broker’s data, even if they know the scheme or member ID — the WHERE clause makes cross-tenant access structurally impossible at the query level.

Role Mapping

The application maps database role names to session role values in src/lib/auth.ts:

const roleMap: Record<string, UserRole> = {
  SuperAdmin:  "admin",
  BrokerAdmin: "broker",
  BrokerUser:  "broker",
  Trustee:     "employer",
}

This mapping is applied at login and embedded in the JWT. Changes to a user’s role in the database take effect at next login.

Session Claims

Every authenticated session carries:

interface PensionsUser {
  id: string
  email: string
  role: UserRole        // "admin" | "broker" | "employer" | "member"
  brokerId: string | null
  employerId: string | null
}

These claims are used by API route handlers and React Server Components to gate access.

API Enforcement Pattern

Extract session

const session = await auth() — retrieves the validated JWT session server-side.

Check authentication

If !session?.user, return 401 Unauthorized.

Check role

If the route requires a specific role (e.g., broker or admin), check session.user.role. Return 403 Forbidden if insufficient.

Scope the query

Append brokerId or employerId to every database query using the session claim.

Audit Trail

All material actions — regardless of role — are written to the append-only audit_logs table, recording the actorId, actorType, action performed, previous state, and new state. See Audit Logging for schema details.

AI Change Proposals

AI-generated suggestions never bypass RBAC. The changeProposals table enforces:

Proposals are scoped to a brokerId (and optionally schemeId, memberId)
Only an authorised broker user can approve or reject a proposal
Required attestations must be completed before approval is permitted
Proposals auto-expire if not acted upon

This ensures AI capability cannot exceed human-authorised permissions.

Regulatory Frameworks

Security

Compliance

AI Governance

Authorisation — RBAC Model

Role Definitions

Tenant Scoping

Role Mapping

Session Claims

API Enforcement Pattern

Audit Trail

AI Change Proposals

​Role Definitions

​Tenant Scoping

​Role Mapping

​Session Claims

​API Enforcement Pattern

​Audit Trail

​AI Change Proposals

Role Definitions

Tenant Scoping

Role Mapping

Session Claims

API Enforcement Pattern

Audit Trail

AI Change Proposals