Security Requirements

1. Overview

This document defines the security requirements for the Registration Portal. For architecture and implementation details, see Security Architecture and Security Implementation.

2. Authentication Requirements

2.1. Supported Authentication Methods

The Registration Portal must support multiple authentication methods:

Method Use Case Token Refresh

Hash-Based JWT

External systems (WordPress, etc.) without OAuth2/OIDC capability

Not supported

OAuth2/OIDC

Organizations with external IdP/SSO (Keycloak, Azure AD, Entra External ID, etc.)

Required - automatic via IdP refresh tokens

Guest Mode

Quick registration, late registration at events

Not applicable

2.2. Token Storage Requirements

Requirement Description

Server-Side Storage

All JWT tokens must be stored server-side in HTTP sessions

No Frontend Exposure

Tokens must never be exposed to the Angular frontend

Trust Boundary

Security boundary exists between gateway and backend, not browser and gateway

Session Cookie

Browser authentication via session cookie only (httpOnly, secure, SameSite)

2.3. Token Exchange Requirements

For OIDC authentication, the gateway must exchange IdP tokens for backend-issued JWTs:

Requirement Description

IdP Token Exchange

Gateway must exchange IdP access_token/id_token for backend JWT after OIDC success

Backend Isolation

Backend must only validate its own JWTs, not IdP tokens directly

Multi-IdP Support

Different tenants must be able to use different IdPs without backend changes

Consistent Claims

Backend JWT must contain standardised claims regardless of which IdP authenticated the user

2.4. Token Refresh Requirements

Requirement Description

OIDC Automatic Refresh

When backend JWT expires during OIDC session, gateway must automatically refresh using IdP refresh token

Pre-Request Refresh

Gateway must detect token expiry before sending request to backend

IdP Token Refresh

If IdP access token is expired, gateway must use refresh token to obtain new tokens

Re-Exchange After Refresh

After obtaining fresh IdP tokens, gateway must exchange them for new backend JWT

Seamless User Experience

Token refresh must be transparent to the user—no interruption during normal operation

Graceful Degradation

If IdP refresh fails, redirect user to IdP login page rather than showing error

2.5. Hash-Based Authentication Requirements

Requirement Description

Fixed Validity

Hash-based tokens have fixed validity period (default 24 hours)

No Refresh

No automatic refresh capability—expired tokens require new hash from external system

401 on Expiry

Backend must return 401 when hash-based token expires

X-Token-Expired Header

Backend must include X-Token-Expired: true header when returning 401 for expired (but previously valid) tokens

Distinguish Token States

Backend must distinguish between: expired token (was valid), invalid token (bad signature/tampered), missing token

Frontend Handling

Frontend must detect X-Token-Expired header and redirect to token expiry screen; other 401s redirect to auth failure screen

2.5.1. Token State Distinction

The backend must distinguish between different token states to enable appropriate frontend handling:

State Detection Frontend Action

Token Expired

401 + X-Token-Expired: true header

Navigate to /auth-failure?reason=token_expired

Token Invalid

401 without X-Token-Expired header

Navigate to /auth-failure

Token Missing

401 without X-Token-Expired header

Navigate to /auth-failure

2.6. User Key Authorization

For anonymous registration workflows, the system must support user keys:

  • Email/SMS Registration Links - Send secure links to users

  • Temporary Access - Limited access for specific operations

  • Organisation Context - Scoped to specific organisation

  • Person Context - Associated with specific person/family

  • Hash Verification - User key alone is insufficient; requires cryptographic hash

3. Authorization Requirements

3.1. Role-Based Access Control

The system must support the following roles:

Role Access Level Capabilities

ROLE_USER

Standard user

Register self/family, view own data

ROLE_MEMBER

Organisation member

Member benefits, additional features

ROLE_ADMIN

Organisation admin

Manage organisation, view reports

ROLE_SYSTEM_ADMIN

System administrator

Full system access, all organisations

3.2. Person-Level Access Control

Access Rules:

  1. User can access persons they created (via userKey)

  2. User can access persons linked to them

  3. Organisation admins can access all persons in their org

  4. System admins can access all persons

3.3. Backend Authorization

Critical Requirement: The backend is responsible for all authorization decisions.

  • Gateway must NOT enforce endpoint-level authentication for proxied requests

  • Gateway must only relay tokens (or not relay if none present)

  • Backend determines what actions are allowed based on token presence and claims

  • Public endpoints are handled by backend returning appropriate responses

4. Multi-Tenant Security Requirements

4.1. Tenant Isolation

  • Each organization’s data must be completely isolated

  • Cross-tenant data access must be prevented at multiple layers

  • Tenant context must be established at the Gateway filter level

4.2. Tenant Determination

The system must support tenant identification via:

  1. URL Subdomain (Priority 1) - e.g., https://runningclub.example.com/register

  2. X-TENANT-ID Header (Priority 2) - For programmatic/API access

4.3. Organisation Scoping

  • All registration operations must be scoped to an organisation

  • Organisation context must be derived from the JWT token

  • Organisation ID must NOT be passed from frontend to backend

  • Backend must enforce organisation-scoped data access using orgId from JWT

4.4. Multi-IdP Support

  • Each tenant may have zero, one, or many IdPs configured

  • IdP configuration must be tenant-specific, stored in the Gateway database as TenantIdentityProvider entities

  • Authentication selection screen must display only configured IdPs for current tenant

  • Supported federated providers: Microsoft Entra ID, Google, Facebook, Apple, Custom OIDC

  • The Gateway must dynamically load OAuth2 client registrations based on the resolved tenant

4.5. JIT User Provisioning

Requirement Description

Auto-Provisioning

When a user authenticates via a federated IdP for the first time and no matching OrgUser record exists, the system must automatically create one (Just-In-Time provisioning)

IdP Subject Binding

OrgUser.externalUserId must be populated from the IdP sub claim (stable, unique per IdP)

Email Deduplication

Before creating a new Person record, the system must check for an existing Person with the same email in the Organisation and link to it if found

Default Permissions

JIT-provisioned users receive ROLE_USER with minimal access; admins can upgrade later

Idempotent Provisioning

Concurrent first-login requests for the same user must not create duplicate OrgUser records

Provisioning Location

JIT provisioning is performed by the admin-service during token exchange, not by the Gateway

5. Data Security Requirements

5.1. Input Validation

Frontend Validation:

  • Required fields must be validated before submission

  • Format validation for email, phone numbers, identity numbers

  • Special character restrictions where applicable

Backend Validation:

  • All input must be validated server-side

  • Entity constraints must be enforced via JPA annotations

  • Identity number format validation (e.g., SA ID: 13 digits)

5.2. Secure Communication

  • All production traffic must use HTTPS

  • HTTP Strict Transport Security (HSTS) must be enabled

  • Secure cookie flags must be set

5.3. CSRF Protection

  • CSRF tokens must be required for state-changing operations

  • Token repository must use HTTP-only cookies

  • SameSite cookie attribute must be set

5.4. CORS Configuration

  • CORS must be configured to allow only authorized origins

  • Credentials must be allowed for authenticated requests

6. Session Management Requirements

6.1. Session Configuration

Setting Requirement

Cookie Name

JSESSIONID (standard)

httpOnly

true - Prevent JavaScript access

secure

true in production - Cookie only sent over HTTPS

SameSite

strict - CSRF protection

Timeout

Configurable (default 30 minutes)

6.2. Session Storage

Attribute Content

BACKEND_JWT

The backend-issued JWT token

BACKEND_JWT_EXPIRY

Token expiry timestamp (OIDC only, not set for hash-based)

IdP Tokens

Managed by Spring Security OAuth2 client (OIDC sessions only)

6.3. Cluster Requirements

For clustered deployments:

  • Use Spring Session with Redis or similar distributed session store

  • OR use sticky sessions at ingress/load balancer level

  • Backend remains stateless—only validates JWTs

7. Audit Requirements

7.1. Security Events to Log

  • Login attempts (success/failure)

  • User key validation failures

  • Unauthorized access attempts

  • Token refresh events (success/failure)

  • IdP authentication events

  • Data modification operations

  • Admin actions

  • Process state changes

7.2. Log Content

Security logs must include:

  • Timestamp

  • Event type

  • User identifier (if available)

  • IP address

  • User agent

  • Tenant context

  • Outcome (success/failure)

8. Future Security Requirements

8.1. Multi-Factor Authentication (Planned)

  • SMS verification codes

  • Email verification links

  • TOTP authenticator apps

8.2. Rate Limiting (Planned)

  • Limit registration attempts per IP

  • Prevent brute force attacks on user keys

  • API throttling per user

9. Related Documentation