Files
2026-10-05 22:19:40 +02:00

263 lines
6.5 KiB
Markdown

# triz-security-common
![Java](https://img.shields.io/badge/Java-8%2B-blue) ![JWT](https://img.shields.io/badge/JWT-RS256-green) ![JJWT](https://img.shields.io/badge/JJWT-0.12.x-orange) ![Version](https://img.shields.io/badge/1.0.0-success)
Internal Java library dedicated to the **generation** and **validation** of **JWT** tokens signed with **RSA (RS256)**, intended to be shared across applications within the **TrizTech** ecosystem.
---
## 1. Overview
`triz-security-common` is a utility Java library that allows you to:
- **generate** JWT tokens signed with **RS256**
- **validate** JWT tokens using an **RSA public key**
- **load** RSA keys from **PEM** format
---
## 2. Use Cases in the TrizTech Ecosystem
### Related Applications
- **auth-triz** — holds the **RSA private key** and generates JWT tokens
- **trizstock** — holds the **RSA public key** and validates tokens
- **trizdistribution** — holds the **RSA public key** and validates tokens
> This architecture ensures that **only `auth-triz` can issue and sign JWTs**, while consumer applications can **only verify** them using the RSA public key.
---
## 3. Features
- JWT generation signed with **RSA / RS256**
- JWT validation using an **RSA public key**
- Loading **private** and **public** RSA keys from PEM files
- Support for **custom claims**
- Simple API with `static` methods
- Compatible with **Java EE / Spring (non-Spring Boot)**
---
## 4. Project Structure
| Class | Role |
|--------|------|
| `JwtUtils` | JWT token generation and validation |
| `KeyLoader` | RSA key loading from PEM files |
---
## 6. Requirements
- Java 8+ (recommended: Java 17)
- JJWT 0.12.x
- Valid RSA keys in PEM format
- Maven 3.x
- Access to the internal Gitea server (`http://145.239.66.197:3000`)
- A valid Gitea Personal Access Token with `package` (read) permission
---
## 7. Installation / Setup
### Step 1 — Generate a Personal Access Token
1. Log in to [Gitea](http://145.239.66.197:3000)
2. Go to **Settings → Applications**
3. Under **Generate New Token**, give it a name (e.g. `maven-publish`)
4. Enable the **`package`** permission (read)
5. Click **Generate Token** and copy the value — you won't see it again
![Generate Token.](assets/token.png "Generate Token.")
---
### As i (Abderrahmane) have set the package to be public this step isnt needed anymore
```xml
### Step 2 — Configure `~/.m2/settings.xml`
Add the following to your local Maven settings file. If the file doesn't exist, create it.
**Option A — Hardcoded token (quick setup, do not commit):**
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
http://maven.apache.org/xsd/settings-1.0.0.xsd">
<servers>
<server>
<id>gitea</id>
<configuration>
<httpHeaders>
<property>
<name>Authorization</name>
<value>token YOUR_ACCESS_TOKEN</value>
</property>
</httpHeaders>
</configuration>
</server>
</servers>
<profiles>
<profile>
<id>gitea-profile</id>
<repositories>
<repository>
<id>gitea</id>
<url>http://145.239.66.197:3000/api/packages/Asma/maven</url>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>gitea-profile</activeProfile>
</activeProfiles>
</settings>
**Option B — Environment variable (recommended for teams):**
```xml
<value>token ${env.GITEA_TOKEN}</value>
```
Then set the environment variable on your machine:
```bash
# Linux / macOS
export GITEA_TOKEN=your_actual_token
# Windows
set GITEA_TOKEN=your_actual_token
```
> With Option B, the `settings.xml` contains no secrets and is safe to share across the team.
### Per-project token setup (optional)
If you need project-specific credentials, create a `settings.xml` file in the project root and run Maven with the `-s` flag:
```bash
mvn clean install -s settings.xml
```
> ⚠️ Never commit a `settings.xml` containing a real token. Add it to `.gitignore`:
>
> ```
> settings.xml
> ```
```
---
## 7. Generate RSA Key Pair with OpenSSL
### 1) Generate the private key
Run this command in Terminal / Git Bash / PowerShell:
```bash
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048
```
This creates:
* private_key.pem
Example format:
```text
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBK...
-----END PRIVATE KEY-----
```
This is exactly the format your **KeyLoader.loadPrivateKey(...)** expects:
* header: -----BEGIN PRIVATE KEY-----
### 2) Generate the public key from the private key
```bash
openssl rsa -pubout -in private_key.pem -out public_key.pem
```
This creates:
* public_key.pem
Example format:
```text
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgK...
-----END PUBLIC KEY-----
```
This is exactly the format your **KeyLoader.loadPublicKey(...)** expects:
* header: -----BEGIN PUBLIC KEY-----
---
### 8. Add Dependency
```xml
<dependencies>
<dependency>
<groupId>com.triztech</groupId>
<artifactId>triz-security-common</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
</dependencies>
```
```xml
<repositories>
<repository>
<id>gitea</id>
<url>http://145.239.66.197:3000/api/packages/Asma/maven</url>
</repository>
</repositories>
```
## 9. Publishing a new version
> Only maintainers need to follow these steps.
1. Update the `<version>` in `pom.xml`
2. Make sure `distributionManagement` is configured in the library's `pom.xml`:
```xml
<distributionManagement>
<repository>
<id>gitea</id>
<url>https://https://gitea.triztech.pro/api/packages/Asma/maven</url>
</repository>
<snapshotRepository>
<id>gitea</id>
<url>https://https://gitea.triztech.pro/api/packages/Asma/maven</url>
</snapshotRepository>
</distributionManagement>
```
3. Run:
```bash
mvn clean deploy
```
4. Verify the package appeared at:
`https://https://gitea.triztech.pro/Asma/-/packages`
---
## 10. Notes
- Versions ending in `-SNAPSHOT` are development builds and can be redeployed
- Stable releases (e.g. `1.0.0`) **cannot** be overwritten — delete the package on Gitea first
- The registry URL (`/api/packages/Asma/maven`) returns `404` in a browser — this is normal, it only speaks the Maven protocol
## 11. Author
Developed for the **TrizTech ecosystem** — to centralize and share JWT logic between `auth-triz`, `trizstock`, and `trizdistribution`.