Multi-Dimensional Security System

Introduction

This documentation describes a comprehensive security system for Spring Boot/JHipster applications, combining JWT-based authentication with multi-dimensional row-level authorization. The system provides:

JWT Authentication - Token-based authentication with session-backed storage (see JWT Authentication and Token Flow)
OAuth2/OIDC Authentication - External IdP integration with token exchange (see OAuth2/OIDC Authentication (Work in Progress), work in progress)
Multi-Dimensional Authorization - Fine-grained access control across organizational and personal dimensions

The authentication layer (JWT or OAuth2) proves user identity, while the authorization layer controls data access based on organization membership and person relationships.

Key Features

Multi-Organization Support: Users can belong to multiple organizations with different permission levels
Personal Data Delegation: Principals can delegate access to other persons' data (family members, team members, etc.)
Dual-Scoped Entities: Support for entities that require both organizational and personal authorization
Flexible Permissions: READ and READ_WRITE access levels for each dimension
JHipster Integration: Seamless integration with JHipster’s QueryService pattern
Performance Optimized: Caching, proper indexing, and query optimization built-in
Admin Bypass: System administrators can bypass all security restrictions
Comprehensive Testing: Full test utilities and examples for all security scenarios

Architecture Overview

The security system operates on two independent but combinable dimensions:

Dimension	Description
Organizational	Controls access to resources based on organization membership. Users can access resources from their primary organization and any linked organizations where they have been granted access.
Personal	Controls access to person-specific data based on delegation relationships. Users can access their own data and data of persons they are linked to (children, team members, etc.).

Dimension

Description

Organizational

Controls access to resources based on organization membership. Users can access resources from their primary organization and any linked organizations where they have been granted access.

Personal

Controls access to person-specific data based on delegation relationships. Users can access their own data and data of persons they are linked to (children, team members, etc.).

Entity Types

Entities in the system are classified into five security types:

Org-Scoped Only	Entities that belong to an organization (e.g., Events, Races)
Person-Scoped Only	Entities containing personal data (e.g., PersonProfile, MedicalInfo)
Dual-Scoped	Entities requiring both org and person authorization by implementing both interfaces (e.g., EventEntry, Payment)
Transitive Org-Scoped	Child entities inheriting org access from parent (e.g., Race via Event)
Transitive Person-Scoped	Child entities inheriting person access from parent

Quick Start

To implement security for a new entity:

Determine the security classification
Implement the appropriate marker interface(s): OrganisationScoped, PersonScoped, or both for composite-scoped entities
Create a QueryService extending SecuredQueryService
Override getSecurityType() and the appropriate security specification method
Add the security service to your service layer methods

Example for an org-scoped entity:

@Service
@Transactional(readOnly = true)
public class EventQueryService extends SecuredQueryService<Event> {

    @Override
    protected SecurityType getSecurityType() {
        return SecurityType.ORG_SCOPED;
    }

    @Override
    protected Specification<Event> getOrgSecuritySpec(AccessLevel accessLevel) {
        return securityService.hasOrgAccess(accessLevel);
    }

    // ... rest of implementation
}

Documentation Structure

This documentation is organized as follows:

Section	Content
Authentication: JWT	Hash-based JWT authentication with session storage, token exchange, and gateway integration
Authentication: OAuth2/OIDC	External IdP integration with token exchange (work in progress)
Security Architecture	Conceptual explanation of the security model, dimensions, and resolution algorithm
Domain Model	Entity definitions, relationships, and marker interfaces
Implementation	Complete implementation guide with code examples
Testing	Test utilities, integration tests, and security test scenarios
Performance	Optimization strategies, caching, and indexing

Section

Content

Authentication: JWT

Hash-based JWT authentication with session storage, token exchange, and gateway integration

Authentication: OAuth2/OIDC

External IdP integration with token exchange (work in progress)

Security Architecture

Conceptual explanation of the security model, dimensions, and resolution algorithm

Domain Model

Entity definitions, relationships, and marker interfaces

Implementation

Complete implementation guide with code examples