Authorisation with Policy-Based-Access-Control (PBAC)

[maximwlt]

Description

Overview

To further enhance our application, we introduce a policy-based access control approach (PBAC) to ensure fine-grained and context-aware authorization.

Our goal is to achieve a high level of security and specifically prevent Broken Access Control, which is ranked as the top security risk in modern applications according to the OWASP Top 10 in 2025.
PBAC is also necessary for our feature discussed in the idea section (see below).

To implement this, we use the Open Policy Agent (OPA) as an external policy engine. This allows us to define and evaluate access rules independently from the application logic, enabling flexible, centralized, and maintainable authorization decisions based on policies rather than hardcoded conditions.

Idea

Currently, users can view all public notes globally. Private notes are only accessible via direct link.
This approach lacks structure and does not provide sufficient isolation between different groups of users.
To improve this, we introduce teams as a logical separation layer.
Users can optionally join or create a team. This allows us to:

• scope visibility of notes
• restrict access based on team membership
• introduce hierarchical roles (leader, vice leader, member)
• enforce fine-grained policies via PBAC

Users start in a teamless state with limited permissions.

Team assignment happens via:

• joining an open team
• invitation link (only sent by leader/vice-leader)
• admin assignment
• creating a new team

A user can only be in one team at a time.

Constraints:

• A user cannot join or create a team if they are already part of another team
• A user must leave their current team before:
  • joining another team
  • creating a new team

Team Creation Model

Teams can be created by any user, with the following constraints:

• The creator automatically becomes the leader
• A user can only create a maximum of 3 teams (to prevent abuse). Number depends on created active teams
• Admins can override all team ownership and assignments

Teams can be deleted by:

• the leader of the team
• the admin (override)

Role	Limit
Leader	Exactly 1 per team
Vice Leader	At most 3 per team
Member	At most 50 per team

The visibility of documents are extended to be public, private, unlisted or protected:

• public: Accessible and visible to all teams
• protected: Accessible and visible to owners team
• unlisted: Accessible for owner teams but only visible to owner (good for link sharing)
• private: Only visible and only accessible to owner

Documents also have a status indicating if the note has been locked by a leader or vice leader

• UNLOCK: (default) - Visible and accessible based on visibility rules
• LOCK: Not visible nor accessible to anyone except team leader and vice leader (overrides visibility defined above)

Constraints:

• Only leader and vice leaders can only lock notes
• Private notes cannot be locked

Authorization Rules

User

Read

• Users can only read their own profile information
• (Optional) Admins may read all user profiles

Create

• Users can register independently of team membership, which means that team membership is not nessecary in registration

Update

• Users can update their own profile data
• Users can leave their team
• Role assignment is handled by the team leader (or admin)

Delete

• Users can delete their own account
• Additional constraint:
  • A leader must assign a new leader before deletion
  • If no successor exists:
    • the team must be deleted first

Notes

Read

• Leader, vice leader, and members can read:
  • public notes
  • protected notes within their team
  • their own unlisted and private notes
• Unlisted notes:
  • Accessible to team members only via direct link
  • Not visible in listings
• Cross-team restriction:
  • Non-public notes cannot be accessed outside the team
• Locked notes:
  • Only leader and vice leaders can read them

Create

• Leader:
  • Can create all types (public, protected, unlisted, private)
• Vice leader & members:
  • Can create protected, unlisted, and private notes
  • Cannot create public notes

Update

• Leader:
  • Can update:
    • all public notes (from team which are all created by leader only)
    • all protected notes in the team
  • Can change note status (lock/unlock)
• Vice leader:
  • Can update:
    • protected notes (optional: only if not locked, depending on strictness)
    • own unlisted/private notes
  • Can lock/unlock notes
• Member:
  • Can update:
    • only their own created notes (protected)
  • Cannot change visibility to public

Delete

• Leader:
  • Can delete:
    • all protected and unlisted notes in the team
  • Cannot delete:
    • private notes of other users
• Vice leader:
  • Cannot delete notes
  • Can lock/unlock notes
• Member:
  • Can delete only their own notes

Teams

Read

• Users can view:
  • their own team
  • public team information (e.g. name, type)
• Admin:
  • Can view all teams

Create

• Any user can create a team
• The creator becomes the leader

Constraints:

• A user can only create a team if they are currently not part of any team
• A team must have exactly one leader

Update

• Leader can:
  • update team metadata (name, description)
  • change team type:
    • open
    • invite-only
    • admin-assigned
  • manage members:
    • promote/demote (respecting role limits)
• Leader cannot leave the team unless:
  • new leader assigned
  • team ist deleted
• Admin can:
  • override all team settings
  • reassign leadership
• Members can:
  • leave the team:
    • After leaving, they return to the teamless state
  • join a team if they are currently teamless

Delete

• Leader can kick members and vice leaders from the team

• Leader can delete their own team
  Constraints:

  • When a team is deleted:
    • all members become teamless
    • notes handling must be defined:

  Possible strategies:

  • delete all team notes
  • convert notes to private
  • archive notes
  • Admin can delete any team (override)

TODOs

• Define OPA Rego policies for all permission rules above
• Define input schema for OPA (user, role, team, resource, action)
• Implement authorization middleware
• Handle edge cases (teamless users, orphan teams)
• Define note handling strategy on team deletion
• Writing integration tests covering all combinations
• Add audit logging for policy decisions

[maximwlt]

4 Steps:

1. Setup OPA Configuration (opa-java, not opa-springboot)
2. Define Input Schema
3. Migrate existing logic to PBAC with OPA policies
4. Start implementing team feature