# THECR3W-DEV — INTEGRACJA KEYCLOAK IAM (STAGE 2 ARCHITECTURE)
## Wersja: 1.0.0 | Data: 2026-10-31

---

## 1. Wymagania i Środowisko
- **Adres instancji:** `https://login.thecr3wnet.com`
- **Realm:** `master` (Wymaganie bezwzględne Właściciela Projektu)
- **Protokół:** OpenID Connect (OIDC) / OAuth 2.0
- **Flow uwierzytelniania Frontend:** Authorization Code Flow z PKCE (Proof Key for Code Exchange, S256)
- **Flow uwierzytelniania Backend:** Bearer Token JWT (walidacja sygnatury kluczami JWKS z `https://login.thecr3wnet.com/realms/master/protocol/openid-connect/certs`)

---

## 2. Minimalna Konfiguracja w Keycloak (Zasada Least Privilege)

Aby nie naruszać istniejących użytkowników i konfiguracji w realm `master`, TheCr3w-dev wymaga utworzenia wyłącznie dwóch odseparowanych klientów:

### 2.1. Klient Frontend: `thecr3w-admin-panel`
- **Client ID:** `thecr3w-admin-panel`
- **Client Protocol:** `openid-connect`
- **Access Type / Client Authentication:** `Public` (wyłączony Client Secret)
- **Standard Flow Enabled:** `ON`
- **Direct Access Grants Enabled:** `OFF`
- **Valid Redirect URIs:**
  - `https://admin.thecr3wnet.com/*`
  - `http://localhost:3000/*` (do testów lokalnych)
- **Web Origins:**
  - `https://admin.thecr3wnet.com`
  - `http://localhost:3000`
- **PKCE Code Challenge Method:** `S256`

### 2.2. Klient Backend: `thecr3w-backend`
- **Client ID:** `thecr3w-backend`
- **Client Protocol:** `openid-connect`
- **Access Type / Client Authentication:** `Confidential` (posiada Client Secret przekazywany przez `KEYCLOAK_CLIENT_SECRET`)
- **Service Accounts Enabled:** `ON` (dla operacji CI/CD i komunikacji machine-to-machine)
- **Authorization Enabled:** `ON`

---

## 3. Matryca Ról Klienta (Client Roles)

Wszystkie role tworzone są wewnątrz klienta `thecr3w-backend`, a NIE jako role realm:

| Nazwa Roli Klienta | Opis i Uprawnienia |
|---|---|
| `thecr3w:admin` | Pełna administracja całym systemem, zarządzanie serwerami zewnętrznymi, audyt. |
| `thecr3w:release-manager` | Zarządzanie wydaniami aplikacji Android i Windows, generowanie adresów uploadu, publikacja i wycofywanie wydań. |
| `thecr3w:approver` | Zatwierdzanie manifestów wdrożeń produkcyjnych. |
| `thecr3w:deployer` | Zgłaszanie manifestów wdrożeniowych, uruchamianie wdrożeń na staging/dev, synchronizacja plików. |
| `thecr3w:viewer` | Podgląd dashboardu, listy wydań, historii wdrożeń i logów audytowych. |

---

## 4. Walidacja Tokenów w ASP.NET Core Backend

Konfiguracja uwierzytelniania w `Program.cs` (.NET 9):
```csharp
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "https://login.thecr3wnet.com/realms/master";
        options.Audience = "thecr3w-backend";
        options.RequireHttpsMetadata = true;
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidIssuer = "https://login.thecr3wnet.com/realms/master",
            ValidateAudience = true,
            ValidAudience = "thecr3w-backend",
            ValidateLifetime = true,
            ClockSkew = TimeSpan.FromMinutes(1)
        };
    });
```