263 lines
6.5 KiB
Markdown
263 lines
6.5 KiB
Markdown
# triz-security-common
|
|
|
|
   
|
|
|
|
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
|
|
|
|

|
|
|
|
---
|
|
### 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`. |