Authentication & Authorization
Document: 18-authentication-authorization.md
Version: 1.0.0
Purpose
This document defines the authentication and authorization architecture used across all Rundown projects.
Authentication verifies the identity of a user.
Authorization determines what an authenticated user is permitted to access or modify.
These responsibilities must remain clearly separated throughout every application.
Authentication Philosophy
Authentication should only be implemented when required by the business.
Public websites should remain publicly accessible unless specific functionality requires user accounts.
Every authentication system introduces additional complexity, and should therefore provide measurable value.
Authentication vs Authorization
Authentication answers:
Who are you?
Examples:
-
Logging in
-
Password verification
-
Session validation
Authorization answers:
What are you allowed to do?
Examples:
-
Edit content
-
Delete products
-
Publish articles
-
Access reports
-
Manage users
Authentication should always occur before authorization.
Standard Authentication Provider
Rundown standardizes on Payload CMS Authentication whenever practical.
Reasons include:
-
Native integration
-
User management
-
Session handling
-
Role-based access
-
Reduced infrastructure complexity
Alternative providers should only be introduced when project requirements justify them.
Responsibilities
The authentication layer owns:
-
User identity
-
Login
-
Logout
-
Session management
-
Password reset
-
Email verification (when required)
-
Account recovery
Non-Responsibilities
Authentication should not own:
-
Business permissions
-
Application logic
-
Content management
-
UI rendering
-
Infrastructure configuration
Authentication verifies identity.
It does not determine business behaviour.
Authorization
Authorization determines access after authentication has succeeded.
Permissions should be based on:
-
User roles
-
Resource ownership
-
Business rules
Access should always follow the principle of least privilege.
Standard Roles
Typical roles include:
Administrator
Responsibilities:
-
Full system access
-
User management
-
CMS configuration
-
Content management
Editor
Responsibilities:
-
Create content
-
Edit content
-
Publish content (if permitted)
Editors should not manage system configuration.
Content Manager
Responsibilities:
-
Manage structured content
-
Upload media
-
Organize collections
Content Managers should not manage application settings.
Client
Responsibilities depend on the project.
Typical permissions include:
-
Editing website content
-
Managing products
-
Viewing reports
Clients should only access functionality relevant to their organization.
Session Management
Authenticated sessions should:
-
Expire after an appropriate period.
-
Be securely stored.
-
Be invalidated after logout.
-
Protect against unauthorized reuse.
Persistent sessions should only be enabled when justified by usability requirements.
Password Policy
Passwords should:
-
Meet minimum complexity requirements.
-
Be securely hashed.
-
Never be stored in plain text.
-
Support secure reset workflows.
Applications should never implement custom password hashing algorithms.
Multi-Factor Authentication
MFA should be supported when required by project requirements.
Recommended for:
-
Administrative accounts
-
Client dashboards
-
Sensitive business applications
Public marketing websites typically do not require MFA.
Route Protection
Protected routes should require authentication before access is granted.
Examples:
-
/admin -
/dashboard -
/orders -
/account
Public content should remain accessible without unnecessary authentication.
API Security
Protected API endpoints should:
-
Verify authentication.
-
Verify authorization.
-
Validate input.
-
Return appropriate HTTP status codes.
Authorization should never rely solely on frontend validation.
Audit Logging
Authentication events should be logged where appropriate.
Examples:
-
Successful login
-
Failed login
-
Password reset
-
Permission changes
Audit logs improve security and simplify troubleshooting.
Security Principles
Authentication systems should:
-
Use HTTPS exclusively.
-
Protect session cookies.
-
Limit login attempts where appropriate.
-
Validate all authentication requests.
-
Follow secure session management practices.
Security should prioritize protecting user identities while maintaining usability.
Engineering Decision
Authentication Strategy
Status: Accepted
Decision
Payload CMS Authentication is the standard authentication provider for Rundown applications.
Reasoning
Payload provides:
-
Native user management
-
Role-based permissions
-
Integrated authentication
-
Reduced architectural complexity
-
Strong integration with the existing technology stack
Alternative authentication providers should only be introduced when clearly justified.
Authentication Checklist
Before implementing authentication, verify:
-
Authentication is required by the business.
-
Roles have been clearly defined.
-
Permissions follow least privilege.
-
Protected routes are secured.
-
API endpoints validate authorization.
-
Sessions are securely managed.
-
Password policies meet security requirements.
Summary
Authentication establishes user identity, while authorization determines access to system resources.
By keeping these responsibilities distinct and implementing authentication only when justified, Rundown applications remain secure, maintainable, and appropriately simple.
Related Documents
Related ADRs
- ADR-001: Repository Structure