From ec3ebc97c734271ce7473881b86cf3c651b3f8be Mon Sep 17 00:00:00 2001 From: Asma TEHAR Date: Mon, 6 Apr 2026 14:44:28 +0100 Subject: [PATCH] README file --- README.md | 175 ++++++++++++++++++++++++++++++++++++++++++++++++++---- pom.xml | 2 +- 2 files changed, 166 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 05ca98c..e00fcb3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# TrizTech Security JWT Library +# 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/version-1.0.0-success) +![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. @@ -8,7 +8,7 @@ Internal Java library dedicated to the **generation** and **validation** of **JW ## 1. Overview -`TrizTech Security JWT Library` is a utility Java library that allows you to: +`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** @@ -24,7 +24,7 @@ Internal Java library dedicated to the **generation** and **validation** of **JW - **trizstock** — holds the **RSA public key** and validates tokens - **trizdistribution** — holds the **RSA public key** and validates tokens -> This approach ensures that **only auth-triz can sign** tokens. The other applications can only verify them. +> This architecture ensures that **only `auth-triz` can issue and sign JWTs**, while consumer applications can **only verify** them using the RSA public key. --- @@ -48,15 +48,110 @@ Internal Java library dedicated to the **generation** and **validation** of **JW --- -## 5. Requirements +## 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 --- -## 6. Generate RSA Key Pair with OpenSSL +## 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.") + +--- + +### 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):** + +```xml + + + + gitea + + + + Authorization + token YOUR_ACCESS_TOKEN + + + + + + + + + gitea-profile + + + gitea + http://145.239.66.197:3000/api/packages/Asma/maven + + + + + + + gitea-profile + + +``` + +**Option B — Environment variable (recommended for teams):** + +```xml +token ${env.GITEA_TOKEN} +``` + +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: @@ -70,7 +165,7 @@ This creates: * private_key.pem Example format: -```xml +```text -----BEGIN PRIVATE KEY----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBK... -----END PRIVATE KEY----- @@ -81,7 +176,7 @@ This is exactly the format your **KeyLoader.loadPrivateKey(...)** expects: ### 2) Generate the public key from the private key -```xml +```bash openssl rsa -pubout -in private_key.pem -out public_key.pem ``` @@ -91,7 +186,7 @@ This creates: Example format: -```xml +```text -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgK... -----END PUBLIC KEY----- @@ -103,5 +198,65 @@ This is exactly the format your **KeyLoader.loadPublicKey(...)** expects: --- -## 7. Auteur +### 8. Add Dependency + +```xml + + + com.triztech + triz-security-common + 1.0-SNAPSHOT + + +``` + + +```xml + + + gitea + http://145.239.66.197:3000/api/packages/Asma/maven + + +``` + +## 9. Publishing a new version + +> Only maintainers need to follow these steps. + +1. Update the `` in `pom.xml` +2. Make sure `distributionManagement` is configured in the library's `pom.xml`: + +```xml + + + gitea + http://145.239.66.197:3000/api/packages/Asma/maven + + + gitea + http://145.239.66.197:3000/api/packages/Asma/maven + + +``` + +3. Run: + +```bash +mvn clean deploy +``` + +4. Verify the package appeared at: + `http://145.239.66.197:3000/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`. \ No newline at end of file diff --git a/pom.xml b/pom.xml index 812cfd0..886927b 100644 --- a/pom.xml +++ b/pom.xml @@ -6,7 +6,7 @@ com.triztech triz-security-common - 1.0-SNAPSHOT + 1.0.0 jar