152 lines
4.0 KiB
Markdown
152 lines
4.0 KiB
Markdown
# Rust GraphQL Zitadel
|
|
|
|
Kleines Lernprojekt für eine geschützte GraphQL-API mit Rust, Actix-Web,
|
|
async-graphql und Zitadel sowie einer Vue/Vite-SPA als Frontend.
|
|
|
|
## Architektur
|
|
|
|
```text
|
|
Vue SPA (Vite, :5173)
|
|
|
|
|
| OIDC Authorization Code + PKCE
|
|
v
|
|
Zitadel
|
|
|
|
|
| Access Token (JWT)
|
|
v
|
|
Rust API (Actix-Web, :8080)
|
|
|
|
|
| JWT-Signatur, Issuer, Audience und Ablaufzeit prüfen
|
|
v
|
|
async-graphql
|
|
```
|
|
|
|
Das Frontend führt den Login bei Zitadel durch. Die Rust-Anwendung führt
|
|
keinen Login durch, sondern arbeitet als OAuth-Resource-Server: Jede
|
|
GraphQL-Anfrage muss ein gültiges Access Token im `Authorization`-Header
|
|
enthalten.
|
|
|
|
## Verzeichnisstruktur
|
|
|
|
```text
|
|
src/
|
|
├── main.rs # Konfiguration laden und Actix-Server starten
|
|
├── config.rs # config.toml in typisierte Settings laden
|
|
├── auth.rs # OIDC Discovery, JWKS und JWT-Validierung
|
|
└── graphql.rs # GraphQL-Schema und geschützter Handler
|
|
|
|
web/src/
|
|
├── App.vue # Seitenfluss und Zusammenspiel der Module
|
|
├── auth/oidc.ts # OIDC-Client und Zitadel-Redirects
|
|
├── auth/useAuth.ts # Authentifizierungszustand im Vue-Lifecycle
|
|
├── graphql/client.ts # GraphQL-Request mit Bearer Token
|
|
└── components/ # Login- und Ergebnisdarstellung
|
|
```
|
|
|
|
## Konfiguration
|
|
|
|
Backend-Konfiguration:
|
|
|
|
```bash
|
|
cp config.example.toml config.toml
|
|
```
|
|
|
|
`config.toml` wird absichtlich nicht versioniert. Die wichtigsten Werte sind:
|
|
|
|
```toml
|
|
[server]
|
|
host = "127.0.0.1"
|
|
port = 8080
|
|
|
|
[zitadel]
|
|
issuer_url = "https://deine-instanz.zitadel.cloud"
|
|
audience = "deine-api-audience"
|
|
```
|
|
|
|
`issuer_url` ist die Zitadel-Instanz. `audience` muss einem Wert im `aud`-
|
|
Claim des Access Tokens entsprechen, für dieses Projekt normalerweise der
|
|
Zitadel-Project-ID.
|
|
|
|
Frontend-Konfiguration:
|
|
|
|
```bash
|
|
cp web/.env.example web/.env.local
|
|
```
|
|
|
|
```env
|
|
VITE_ZITADEL_AUTHORITY=https://deine-instanz.zitadel.cloud
|
|
VITE_ZITADEL_CLIENT_ID=deine-spa-client-id
|
|
VITE_ZITADEL_PROJECT_ID=deine-projekt-id
|
|
```
|
|
|
|
Die SPA muss in Zitadel als Single-Page Application angelegt sein. Für die
|
|
lokale Entwicklung werden diese Redirect-URIs benötigt:
|
|
|
|
```text
|
|
http://localhost:5173/callback
|
|
http://localhost:5173/
|
|
```
|
|
|
|
Die erste URI ist die Login-Callback-URI, die zweite die Post-Logout-URI.
|
|
Wenn die Anwendung über `127.0.0.1` geöffnet wird, müssen die entsprechenden
|
|
URIs mit `127.0.0.1` ebenfalls in Zitadel eingetragen werden.
|
|
|
|
Der Access-Token-Typ der Zitadel-Anwendung muss auf **JWT** stehen. Ein
|
|
opaker beziehungsweise verschlüsselter Token kann nicht mit den öffentlichen
|
|
JWKS-Schlüsseln lokal validiert werden; dafür wäre stattdessen Token
|
|
Introspection erforderlich.
|
|
|
|
## Lokale Entwicklung
|
|
|
|
Mit Devenv werden Backend und Frontend gemeinsam gestartet:
|
|
|
|
```bash
|
|
devenv up
|
|
```
|
|
|
|
Alternativ einzeln:
|
|
|
|
```bash
|
|
# Repository-Root
|
|
cargo run
|
|
|
|
# web/
|
|
```
|
|
|
|
Der Vite-Entwicklungsserver proxied `/graphql` an das Rust-Backend. Dadurch
|
|
ruft der Browser `/graphql` auf Port `5173` auf, während die Anfrage intern an
|
|
`http://127.0.0.1:8080/graphql` weitergeleitet wird.
|
|
|
|
## Request-Fluss
|
|
|
|
1. Die SPA startet den Authorization-Code-Flow mit PKCE.
|
|
2. Zitadel authentifiziert den Benutzer und leitet zu `/callback` zurück.
|
|
3. `oidc-client-ts` tauscht den Code gegen Tokens und speichert die Session
|
|
in `sessionStorage`.
|
|
4. Das Frontend sendet das Access Token als `Bearer`-Token an `/graphql`.
|
|
5. Actix-Web validiert Signatur, Issuer, Audience und Ablaufzeit.
|
|
6. Erst danach wird die GraphQL-Abfrage ausgeführt.
|
|
|
|
## Prüfungen
|
|
|
|
Backend aus dem Repository-Root:
|
|
|
|
```bash
|
|
cargo fmt --check
|
|
cargo check
|
|
cargo test
|
|
cargo clippy -- -D warnings
|
|
```
|
|
|
|
Frontend aus `web/`:
|
|
|
|
```bash
|
|
pnpm build
|
|
```
|
|
|
|
## Häufige Fehler
|
|
|
|
- `redirect_uri is missing`: Die exakte Callback-URI fehlt in der Zitadel-SPA-Anwendung.
|
|
- `401 Unauthorized`: Das Access Token fehlt, ist abgelaufen oder Issuer/Audience stimmen nicht.
|
|
- `Base64 error` mit fünf Token-Teilen: Zitadel liefert keinen normalen signierten JWT; den Access-Token-Typ auf JWT stellen oder Introspection implementieren.
|