Methea Framework

Methea is a plug-and-play authentication and access-management framework for Spring Boot RESTful services. It handles user authentication, role-based permission checks, and JWT/JWE token lifecycle so you don't have to.

A companion UI Management Tool is available for managing users, roles, and permissions through a browser interface (under development).

---

Features

• JWT / JWE tokens — encrypted access tokens and refresh tokens via Nimbus JOSE+JWT
• Argon2 password hashing — modern, memory-hard password encoding
• RSA key-pair encryption — 2048-bit keys loaded from PKCS12 keystores
• Role & resource-based authorization — fine-grained URI permission control
• Public URI whitelist — selectively expose endpoints without authentication
• Session management — server-side session tracking with token revocation support
• Spring Data JPA auditing — automatic createdBy / updatedBy population

---

Tech Stack

Layer	Technology
Runtime	Java 21
Framework	Spring Boot 4.0.2
Security	Spring Security 6
Token format	JWE (RSA-OAEP-256 + A256GCM)
Password hashing	Argon2id
Cryptography	BouncyCastle
Persistence	Spring Data JPA / Hibernate
Database	PostgreSQL (tested)
Build	Maven

---

Module Structure

methea/
├── core/          # Domain entities, repositories, utilities, security primitives
├── auth/          # Authentication REST API (token issue, refresh, revoke)
└── auth-app/      # Sample host application

Domain Model

Entity	Description
Account	Organisation / company
Group	Department or team within an account
User	System user with Argon2-encoded password
Role	Named role assigned to users
Resource	API endpoint URI
Permission	Binds a Role to a Resource
PublicPermission	Whitelisted (unauthenticated) URIs and their allowed HTTP methods
SessionManagement	Active token sessions — used for revocation
JWTConfig	JWT expiry and signing configuration

---

REST API

All endpoints are under /auth/** and are publicly accessible.

Method	Path	Description
POST	/auth/token	Obtain access + refresh tokens
POST	/auth/refresh/token	Exchange a refresh token for a new access token
POST	/auth/token/revoke	Revoke an active access token

Token request

POST /auth/token
{
  "username": "admin",
  "password": "secret"
}

Token response

{
  "status": 200,
  "message": "Access token generated!!!",
  "token": {
    "accessToken": "<JWE>",
    "refreshToken": "<JWE>",
    "tokenType": "Bearer ",
    "expiredIn": "1234567890"
  }
}

Pass the access token in subsequent requests:

Authorization: Bearer <JWE>

---

Getting Started

Prerequisites

• JDK 21+
• Maven 3.8+
• PostgreSQL
• KeyStore Explorer or keytool to generate PKCS12 keystores

Build

git clone https://github.com/MetheaX/Methea-Framework.git
cd Methea-Framework
mvn clean install

Integrate into your application

1. Add the dependency

<dependency>
    <groupId>io.github.metheax</groupId>
    <artifactId>auth</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

2. Configure component scan

@SpringBootApplication(scanBasePackages = {"io.github.metheax", "com.yourcompany"})
@EnableJpaRepositories(basePackages = {"io.github.metheax", "com.yourcompany"})
@EntityScan(basePackages = {"io.github.metheax", "com.yourcompany"})
public class YourApplication {
    public static void main(String[] args) {
        SpringApplication.run(YourApplication.class, args);
    }
}

3. Configure your datasource (application.yml)

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/yourdb
    username: youruser
    password: yourpassword
  jpa:
    hibernate:
      ddl-auto: update

4. Configure keystores

Generate two PKCS12 keystores — one for access tokens, one for refresh tokens — then add:

keystore-token-file: classpath:keystore/token.pfx
keystore-token-password: changeit
keystore-token-alias: token
keystore-key-token-password: changeit

keystore-refresh-token-file: classpath:keystore/refresh.pfx
keystore-refresh-token-password: changeit
keystore-refresh-token-alias: refresh
keystore-key-refresh-token-password: changeit

Place the .pfx files under src/main/resources/keystore/.

5. Seed initial data

INSERT INTO core_account VALUES ('68bcf443-1b0c-49ff-877e-8650477383e8', NOW(), 'System', 'A', NOW(), 'System',
    'Phnom Penh, Cambodia.', 'METHEA', 'methea@localhost.com', 'Methea LLC.', 'មេធា');

INSERT INTO core_group VALUES ('366a7028-b623-49b0-8988-d711647051a5', NOW(), 'System', 'A', NOW(), 'System',
    'M_SYS_ADMIN', 'System Admin', 'អេតមីនប្រព័ន្ធ', null, '68bcf443-1b0c-49ff-877e-8650477383e8');

INSERT INTO core_resource VALUES ('ad5ea55c-547a-4537-8797-e3714c64d8a3', NOW(), 'System', 'A', NOW(), 'System', '/**');

INSERT INTO core_role VALUES ('33525a14-0ebc-4a3e-ada5-bd3ef94c9495', NOW(), 'System', 'A', NOW(), 'System',
    'ROLE_ADMIN', 'Admin', 'អេតមីន');

INSERT INTO core_user VALUES ('c6eff227-d496-486c-a72c-db2f92e06faa', NOW(), 'System', 'A', NOW(), 'System',
    'admin@localhost.com', 'Admin', 'អេតមីន', 'N', '639691', 'Admin', 'អេតមីន',
    'Gp/lBVv1VTKk3DLGiENtX4Ow1xLEUqIDRBpa+zuTJWT3IIqfC4m0SB1tpVDo1+BQHFnY90XmvbJE1JAMDfRSmA$vkDevdjMM9v+/BonOi6HX/+v3Syh5mrSMXssz5707LSlOrCiIj3O7Q50bg7mLeCl6GYKhad7GGQi7CKvP1KqnbvtS2eZMFevVHsYHsQD2UeMQqiP7nAQ1z12ZHMNc5QckXZgUPMqetTzhJMzDduJ9+nOrC3HlqSo43VoMg0k+EA',
    '+85569639691', 'admin', '366a7028-b623-49b0-8988-d711647051a5');

INSERT INTO core_user_roles VALUES ('c6eff227-d496-486c-a72c-db2f92e06faa', '33525a14-0ebc-4a3e-ada5-bd3ef94c9495');

INSERT INTO core_permission VALUES ('bdee9930-cbde-4e62-96d8-91df821a698b', NOW(), 'System', 'A', NOW(), 'System',
    'ad5ea55c-547a-4537-8797-e3714c64d8a3', '33525a14-0ebc-4a3e-ada5-bd3ef94c9495');

Default credentials: admin / admin (change immediately in production).

---

Running Tests

mvn test -pl core,auth

The test suite covers 85%+ instruction coverage (enforced by JaCoCo) across both modules:

Module	Tests	Coverage
core	140	≥ 85%
auth	35	≥ 85%

---

Sample Project

See Methea-Sample-Webservice for a complete integration example.

---

Support

• Bug reports / feature requests: open a GitHub Issue
• Commercial support / customisation: kuylim.tith@outlook.com