Stefan Mogeritsch
c692a2395c
Added a detailed guide (`jwt-in-docker.md`) to address JWT validation challenges in Docker environments (Split Horizon issue). Refactored Keycloak realm configuration (`meldestelle-realm.json`) with updated roles, clients, and improved infrastructure clarity. Updated `.env` variables for streamlined token validation. Adjusted Docker Compose services (`dc-backend.yaml`) to use revised Keycloak environment variables.
167 lines
5.5 KiB
Markdown
167 lines
5.5 KiB
Markdown
---
|
|
type: Guide
|
|
status: ACTIVE
|
|
owner: Backend Developer
|
|
tags: [testing, postman, backend, api]
|
|
---
|
|
|
|
# 🧪 Testanleitung: Ping-Service & Gateway mit Postman
|
|
|
|
Diese Anleitung beschreibt, wie die Backend-Services (Gateway, Ping-Service) und die Infrastruktur (Keycloak, DB) isoliert vom Frontend getestet werden können.
|
|
|
|
**Voraussetzungen:**
|
|
1. **Infrastruktur läuft:** `docker compose --profile infra up -d` (Postgres, Keycloak, Redis, Consul).
|
|
2. **Backend läuft:** `docker compose --profile backend up -d` (Gateway, Ping-Service).
|
|
3. **Postman** ist installiert.
|
|
|
|
---
|
|
|
|
## 1. Vorbereitung: Keycloak User & Client
|
|
|
|
Damit wir testen können, brauchen wir einen User und einen Client in Keycloak, um uns ein Token zu holen.
|
|
|
|
* **URL:** `http://localhost:8180` (oder Port aus `docker-compose logs keycloak`)
|
|
* **Admin Login:** `kc-admin` / `kc-password`
|
|
* **Realm:** Wähle oben links `meldestelle` aus (wurde beim Start importiert).
|
|
|
|
**Check:**
|
|
* **User:** Der Standard-Admin User `admin` hat bereits die notwendige Rolle `MELD_USER`.
|
|
* **Client:** Es gibt einen dedizierten Test-Client `postman-client`.
|
|
* Client ID: `postman-client`
|
|
* Client Secret: `postman-secret-123`
|
|
* Access Type: `confidential`
|
|
* Direct Access Grants: `Enabled`
|
|
|
|
---
|
|
|
|
## 2. Postman Collection einrichten
|
|
|
|
Erstelle eine neue Collection "Meldestelle Ping Test".
|
|
|
|
### A. Variablen (Environment)
|
|
Setze folgende Variablen in Postman (Environment "Local Docker"):
|
|
* `gateway_url`: `http://localhost:8081`
|
|
* `auth_url`: `http://localhost:8180/realms/meldestelle/protocol/openid-connect/token`
|
|
* `client_id`: `postman-client`
|
|
* `client_secret`: `postman-secret-123`
|
|
* `username`: `admin`
|
|
* `password`: `Change_Me_In_Production!`
|
|
|
|
---
|
|
|
|
## 3. Test-Szenarien
|
|
|
|
Wir testen nun die verschiedenen Endpunkte und Sicherheitsstufen.
|
|
|
|
### Szenario 1: Public Endpoints (Ohne Login)
|
|
*Diese Requests müssen **ohne** Token funktionieren.*
|
|
|
|
**1.1 Simple Ping**
|
|
* **Method:** `GET`
|
|
* **URL:** `{{gateway_url}}/api/ping/simple`
|
|
* **Auth:** No Auth
|
|
* **Erwartetes Ergebnis:**
|
|
* Status: `200 OK`
|
|
* Body: `{"status": "pong", "service": "ping-service", ...}`
|
|
* *Bedeutung:* Gateway routet korrekt, Service ist erreichbar, DB-Schreibzugriff (Simple Ping speichert was) klappt.
|
|
|
|
**1.2 Health Check**
|
|
* **Method:** `GET`
|
|
* **URL:** `{{gateway_url}}/api/ping/health`
|
|
* **Auth:** No Auth
|
|
* **Erwartetes Ergebnis:**
|
|
* Status: `200 OK`
|
|
* Body: `{"status": "up", "healthy": true, ...}`
|
|
|
|
**1.3 Public Ping**
|
|
* **Method:** `GET`
|
|
* **URL:** `{{gateway_url}}/api/ping/public`
|
|
* **Auth:** No Auth
|
|
* **Erwartetes Ergebnis:** `200 OK`
|
|
|
|
---
|
|
|
|
### Szenario 2: Security Check (Negativ-Test)
|
|
*Wir versuchen, auf geschützte Bereiche zuzugreifen, ohne eingeloggt zu sein.*
|
|
|
|
**2.1 Secure Ping (Unauthenticated)**
|
|
* **Method:** `GET`
|
|
* **URL:** `{{gateway_url}}/api/ping/secure`
|
|
* **Auth:** No Auth
|
|
* **Erwartetes Ergebnis:**
|
|
* Status: `401 Unauthorized`
|
|
* *Bedeutung:* Gateway oder Service blockt den Request korrekt ab.
|
|
|
|
**2.2 Sync Ping (Unauthenticated)**
|
|
* **Method:** `GET`
|
|
* **URL:** `{{gateway_url}}/api/ping/sync`
|
|
* **Auth:** No Auth
|
|
* **Erwartetes Ergebnis:**
|
|
* Status: `401 Unauthorized` (sofern Sync auch geschützt ist).
|
|
|
|
---
|
|
|
|
### Szenario 3: Authenticated Endpoints (Mit Token)
|
|
*Jetzt holen wir uns ein Token und testen die geschützten Bereiche.*
|
|
|
|
**3.1 Token holen (Login)**
|
|
* In Postman: Tab "Authorization" -> Type "OAuth 2.0".
|
|
* Grant Type: `Password Credentials`
|
|
* Access Token URL: `{{auth_url}}`
|
|
* Client ID: `{{client_id}}`
|
|
* Client Secret: `{{client_secret}}`
|
|
* Username: `{{username}}`
|
|
* Password: `{{password}}`
|
|
* Klick auf "Get New Access Token".
|
|
* Klick auf "Use Token".
|
|
|
|
**3.2 Secure Ping (Authenticated)**
|
|
* **Method:** `GET`
|
|
* **URL:** `{{gateway_url}}/api/ping/secure`
|
|
* **Auth:** Inherit from parent (oder OAuth 2.0 mit dem Token).
|
|
* **Erwartetes Ergebnis:**
|
|
* Status: `200 OK`
|
|
* Body: `{"status": "secure-pong", ...}`
|
|
* *Bedeutung:* Token ist gültig, Signatur passt, Rolle `MELD_USER` wurde erkannt.
|
|
|
|
**3.3 Sync Ping (Authenticated)**
|
|
* **Method:** `GET`
|
|
* **URL:** `{{gateway_url}}/api/ping/sync?lastSyncTimestamp=0`
|
|
* **Auth:** OAuth 2.0 (Token)
|
|
* **Erwartetes Ergebnis:**
|
|
* Status: `200 OK`
|
|
* Body: `[ ... Liste von Events ... ]`
|
|
* *Bedeutung:* Delta-Sync funktioniert.
|
|
|
|
---
|
|
|
|
### Szenario 4: Resilience (Circuit Breaker)
|
|
|
|
**4.1 Enhanced Ping (Normal)**
|
|
* **Method:** `GET`
|
|
* **URL:** `{{gateway_url}}/api/ping/enhanced`
|
|
* **Erwartetes Ergebnis:** `200 OK`
|
|
|
|
**4.2 Enhanced Ping (Simulation Failure)**
|
|
* **Method:** `GET`
|
|
* **URL:** `{{gateway_url}}/api/ping/enhanced?simulate=true`
|
|
* **Wiederhole:** Sende den Request mehrmals schnell hintereinander.
|
|
* **Erwartetes Ergebnis:**
|
|
* Manchmal `500 Error` (Simulation).
|
|
* Nach einigen Fehlern: `200 OK` aber mit `status: "fallback"` und `circuitBreakerState: "OPEN"`.
|
|
* *Bedeutung:* Resilience4j hat den Fehler erkannt und den Circuit Breaker geöffnet -> Fallback-Methode greift.
|
|
|
|
---
|
|
|
|
## Zusammenfassung der Checkliste
|
|
|
|
| Test | URL | Auth | Erwartet |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **Connectivity** | `/api/ping/simple` | Nein | 200 OK |
|
|
| **Health** | `/api/ping/health` | Nein | 200 OK |
|
|
| **Security Block** | `/api/ping/secure` | Nein | 401 Unauthorized |
|
|
| **Auth Login** | (Keycloak Token) | - | Token erhalten |
|
|
| **Security Access** | `/api/ping/secure` | Ja (Token) | 200 OK |
|
|
| **Sync** | `/api/ping/sync` | Ja (Token) | 200 OK (Liste) |
|
|
| **Resilience** | `/api/ping/enhanced?simulate=true` | Nein | Fallback Response |
|