init
This commit is contained in:
br committed
commit
5126decf36
4 files changed
+341
No files matched your search
@@ -0,0 +1,31 @@
|
||||
# kbcrm
|
||||
|
||||
[Kurzbeschreibung folgt – Zweck und Ziel der Applikation]
|
||||
|
||||
**Authentifizierung** vollständig an Zitadel delegiert. Lokale Datenhaltung,
|
||||
Benutzer- und Rollenverwaltung über SQLite.
|
||||
|
||||
---
|
||||
|
||||
## Technologie-Stack
|
||||
|
||||
| Komponente | Technologie |
|
||||
|---|---|
|
||||
| Backend | Python Flask 2.x |
|
||||
| OIDC-Client | Authlib |
|
||||
| Datenbank | SQLite via SQLAlchemy |
|
||||
| IdP | Zitadel |
|
||||
| Produktion | Docker / gunicorn |
|
||||
|
||||
---
|
||||
|
||||
## Lokale Entwicklung
|
||||
|
||||
```bash
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
cp .env.example .env # Zitadel-Credentials eintragen
|
||||
flask db-init # Schema initialisieren
|
||||
flask seed-db # Testdaten einspielen
|
||||
flask run # App startet auf http://localhost:5000
|
||||
@@ -0,0 +1,138 @@
|
||||
# Zitadel-Einrichtung – Schritt-für-Schritt
|
||||
|
||||
Zitadel-Instanz: **https://id.vmlx.de**
|
||||
|
||||
Ziel dieser Anleitung: Das OIDC-Projekt **kbcrm** anlegen, drei Testrollen definieren,
|
||||
drei Testnutzer erstellen, ihnen Rollen zuweisen und die Zitadel-User-IDs
|
||||
(`sub`-Werte) für das DB-Seeding ermitteln.
|
||||
|
||||
---
|
||||
|
||||
## Schritt 1 – Zitadel-Projekt anlegen
|
||||
|
||||
1. Login unter https://id.vmlx.de
|
||||
2. Linke Navigation → **Projekte** → **Neu anlegen**
|
||||
3. Name: `kbcrm` → Speichern
|
||||
4. Im Projekt-Detail unter **Einstellungen** folgende Optionen aktivieren:
|
||||
- ☑ **Assert Roles on Authentication** (Rollen werden in Token geschrieben)
|
||||
- ☑ **Check Authorization on Authentication** (Zugriff nur für zugewiesene Nutzer)
|
||||
|
||||
---
|
||||
|
||||
## Schritt 2 – Rollen anlegen
|
||||
|
||||
Im Projekt → Tab **Rollen** → drei Rollen anlegen:
|
||||
|
||||
| Anzeigename | Schlüssel (Key) |
|
||||
|---|---|
|
||||
| Admin | `Admin` |
|
||||
| Mitarbeiter | `Mitarbeiter` |
|
||||
| Kunde | `Kunde` |
|
||||
|
||||
> Der Schlüssel (Key) muss **exakt** so geschrieben sein – er erscheint so im Token-Claim.
|
||||
|
||||
---
|
||||
|
||||
## Schritt 3 – OIDC-Anwendung anlegen
|
||||
|
||||
Im Projekt → Tab **Anwendungen** → **Neu anlegen**
|
||||
|
||||
| Feld | Wert |
|
||||
|---|---|
|
||||
| Name | `kbcrm-web` |
|
||||
| Typ | **Web** |
|
||||
| Auth-Methode | **Code** (Authorization Code mit Client Secret) |
|
||||
|
||||
Nach dem Erstellen:
|
||||
- **Client-ID** und **Client-Secret** notieren → kommen in die `.env`
|
||||
- Unter **Redirect-URIs** eintragen:
|
||||
- `http://localhost:5000/auth/callback` (Lokal)
|
||||
- `https://<deine-domain>/auth/callback` (Prod, falls zutreffend)
|
||||
- Unter **Post-Logout-Redirect-URIs** eintragen:
|
||||
- `http://localhost:5000/`
|
||||
|
||||
---
|
||||
|
||||
## Schritt 4 – Testnutzer anlegen
|
||||
|
||||
Navigation: **Nutzer** (oberste Ebene, nicht innerhalb eines Projekts) → **Neu anlegen**
|
||||
|
||||
Drei Nutzer erstellen:
|
||||
|
||||
| Name | E-Mail | Passwort | Zitadel-Rolle |
|
||||
|---|---|---|---|
|
||||
| Admin Test | admin@test.local | (eigenes PW) | Admin |
|
||||
| Mitarbeiter Test | ma@test.local | (eigenes PW) | Mitarbeiter |
|
||||
| Kunde Test | kunde@test.local | (eigenes PW) | Kunde |
|
||||
|
||||
> Bei der Erstellung: **Passwort beim ersten Login ändern** deaktivieren empfohlen, damit Tests flüssig laufen.
|
||||
|
||||
---
|
||||
|
||||
## Schritt 5 – Rollen an Nutzer vergeben
|
||||
|
||||
Für jeden Nutzer:
|
||||
|
||||
1. **Nutzer** → Nutzer auswählen → Tab **Autorisierungen**
|
||||
2. → **Neu** → Projekt `kbcrm` wählen → entsprechende Rolle wählen → Speichern
|
||||
|
||||
---
|
||||
|
||||
## Schritt 6 – User-IDs (sub) ermitteln
|
||||
|
||||
Die User-ID (Zitadel-`sub`) ist die interne Zitadel-Nutzer-ID, **nicht** die E-Mail.
|
||||
|
||||
**Methode A – Zitadel-Konsole:**
|
||||
Nutzer auswählen → oben in der Detailansicht steht die **User-ID** (z. B. `236968807784841234`)
|
||||
|
||||
**Methode B – Aus dem App-Log (nach Schritt 7):**
|
||||
Nach dem ersten Login loggt die App in stdout:
|
||||
```
|
||||
OIDC Login – sub: 236968807784841234 | email: admin@test.local | roles: ['Admin']
|
||||
```
|
||||
|
||||
Alle drei Sub-Werte notieren für den nächsten Schritt.
|
||||
|
||||
---
|
||||
|
||||
## Schritt 7 – .env befüllen und DB seeden
|
||||
|
||||
`.env` aus `.env.example` kopieren und befüllen:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
```env
|
||||
ZITADEL_CLIENT_ID=<Client-ID aus Schritt 3>
|
||||
ZITADEL_CLIENT_SECRET=<Client-Secret aus Schritt 3>
|
||||
ZITADEL_DISCOVERY_URL=https://id.vmlx.de/.well-known/openid-configuration
|
||||
SECRET_KEY=<zufälliger langer String>
|
||||
```
|
||||
|
||||
Dann in `app/__init__.py` die Platzhalter in `seed_db()` mit den echten Sub-Werten ersetzen:
|
||||
|
||||
```python
|
||||
ADMIN_ID = "236968807784841234" # <-- echte Zitadel-User-ID
|
||||
MITARBEITER_ID = "..."
|
||||
KUNDE_ID = "..."
|
||||
```
|
||||
|
||||
Anschließend seeden:
|
||||
|
||||
```bash
|
||||
source venv/bin/activate
|
||||
flask seed-db
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Discovery-URL verifizieren
|
||||
|
||||
```bash
|
||||
curl https://id.vmlx.de/.well-known/openid-configuration | python3 -m json.tool
|
||||
```
|
||||
|
||||
Wenn die Antwort ein JSON mit `issuer`, `authorization_endpoint` usw. ist, ist die URL korrekt.
|
||||
Sollte die URL nicht funktionieren, alternative probieren:
|
||||
`https://id.vmlx.de/oauth/v2/.well-known/openid-configuration`
|
||||
@@ -0,0 +1,41 @@
|
||||
# AI.md — Strukturvorgaben für neue Applikation
|
||||
|
||||
**Autoren:** Björn Runden, Gerd Goldberg
|
||||
**Zweck dieses Dokuments:** Verbindliche strukturelle, betriebliche und infrastrukturelle Vorgaben für eine neue Python-Applikation. Applikationslogik, Routing und Frontend sind bewusst nicht Teil dieses Dokuments.
|
||||
|
||||
---
|
||||
|
||||
## 1. Technologie-Stack
|
||||
|
||||
| Schicht | Technologie |
|
||||
|---|---|
|
||||
| Backend-Framework | Python Flask 2.x |
|
||||
| OIDC-Authentifizierung | Authlib (gegen Zitadel als externen IdP) |
|
||||
| Datenbank / ORM | SQLite + SQLAlchemy |
|
||||
| Konfiguration | 12-Factor-App via `.env`-Datei |
|
||||
| Produktions-Server | Gunicorn |
|
||||
| Container | Docker (`python:3.11-slim`), orchestriert via `docker-compose.yml` |
|
||||
|
||||
---
|
||||
|
||||
## 2. Verzeichnisstruktur
|
||||
|
||||
```text
|
||||
.
|
||||
├── .gitignore
|
||||
├── .env
|
||||
├── .env.example
|
||||
├── requirements.txt
|
||||
├── docker-compose.yml
|
||||
├── Dockerfile
|
||||
├── wsgi.py
|
||||
├── data/ ← Datenbankverzeichnis (persistente SQLite-Datei, nicht im Image)
|
||||
└── app/
|
||||
├── __init__.py
|
||||
├── config.py
|
||||
├── database.py
|
||||
├── models.py
|
||||
├── auth.py
|
||||
├── routes.py
|
||||
├── templates/
|
||||
└── static/
|
||||
@@ -0,0 +1,131 @@
|
||||
# Strukturelle Vorgaben – Quellcode-Konventionen
|
||||
|
||||
Dieses Dokument legt verbindliche Konventionen für alle Quelldateien im Projekt fest.
|
||||
|
||||
---
|
||||
|
||||
## 1. Datei-Header
|
||||
|
||||
Jede Quelldatei beginnt mit einem standardisierten Header. Der Header dient gleichzeitig als Modul-Docstring und wird von **Sphinx** zur automatischen Dokumentationserzeugung ausgewertet (Python-Äquivalent zu JavaDoc).
|
||||
|
||||
### Python (`.py`)
|
||||
|
||||
Der Header ist ein Modul-Docstring (triple-quoted) direkt am Dateianfang. Sphinx liest ihn automatisch aus:
|
||||
|
||||
```python
|
||||
"""
|
||||
<Einzeiliger Titel des Moduls>
|
||||
|
||||
<Optionale längere Beschreibung, was dieses Modul leistet, welche
|
||||
Klassen/Funktionen es exportiert und welche Abhängigkeiten es hat.>
|
||||
|
||||
:author: Vorname Nachname <email@beispiel.de>
|
||||
:date: YYYY-MM-DD
|
||||
:version: 1.0
|
||||
"""
|
||||
```
|
||||
|
||||
Pflichtfelder: `:author:`, `:date:`
|
||||
Optionale Felder: `:version:`, `:see:`, `:note:`
|
||||
|
||||
### Jinja2 / HTML (`.html`)
|
||||
|
||||
Jinja2-Kommentare (`{# ... #}`) werden vom Browser nicht gerendert und sind deshalb die richtige Wahl für Template-Header:
|
||||
|
||||
```html
|
||||
{#
|
||||
Datei: templates/beispiel.html
|
||||
Autor: Vorname Nachname <email@beispiel.de>
|
||||
Datum: YYYY-MM-DD
|
||||
Zweck: Kurze Beschreibung, welche Seite/Komponente dieses Template rendert
|
||||
und welche Jinja2-Variablen es erwartet.
|
||||
#}
|
||||
```
|
||||
|
||||
Pflichtfelder: `Datei:`, `Autor:`, `Datum:`, `Zweck:`
|
||||
|
||||
---
|
||||
|
||||
## 2. Dokumentationserzeugung mit Sphinx
|
||||
|
||||
Python bietet mit **Sphinx** ein mächtiges Werkzeug analog zu JavaDoc. Es liest Modul-Docstrings (inkl. `:author:`/`:date:`-Felder) und erzeugt daraus eine vollständige HTML-Dokumentation.
|
||||
|
||||
### Einrichtung (einmalig)
|
||||
|
||||
```bash
|
||||
pip install sphinx
|
||||
cd docs/
|
||||
sphinx-quickstart # Interaktiver Setup-Assistent
|
||||
```
|
||||
|
||||
Im Setup-Assistenten:
|
||||
- `autodoc` aktivieren (liest Docstrings automatisch)
|
||||
- Projektname, Autor und Version eingeben
|
||||
|
||||
Anschließend in `docs/conf.py` sicherstellen:
|
||||
|
||||
```python
|
||||
extensions = [
|
||||
"sphinx.ext.autodoc",
|
||||
"sphinx.ext.viewcode", # Links zum Quellcode
|
||||
]
|
||||
```
|
||||
|
||||
### Dokumentation aus dem `app/`-Verzeichnis einlesen
|
||||
|
||||
```bash
|
||||
sphinx-apidoc -o docs/source/ app/
|
||||
```
|
||||
|
||||
Dieser Befehl scannt alle `.py`-Dateien unter `app/` und erzeugt `.rst`-Stub-Dateien, die den Modul-Docstring und alle Klassen/Funktionen einbinden.
|
||||
|
||||
### Dokumentation bauen
|
||||
|
||||
```bash
|
||||
cd docs/
|
||||
make html
|
||||
# Ergebnis liegt unter: docs/_build/html/index.html
|
||||
```
|
||||
|
||||
### Ablauf
|
||||
|
||||
```
|
||||
Modul-Docstrings → sphinx-apidoc → .rst-Dateien → make html → HTML-Doku
|
||||
```
|
||||
|
||||
> **Hinweis:** Für HTML-Templates gibt es kein Python-natives Doku-Tool. Die Header-Kommentare dienen dort als Inline-Dokumentation für Entwickler.
|
||||
|
||||
---
|
||||
|
||||
## 3. Template-Dateien
|
||||
|
||||
Im Verzeichnis [`_templates/`](_templates/) liegen Vorlagen, von denen sich der Entwickler **jederzeit eine frische Kopie ziehen** kann:
|
||||
|
||||
| Template | Verwendung |
|
||||
|---|---|
|
||||
| [`_templates/_template.py`](_templates/_template.py) | Neue Python-Quelldatei |
|
||||
| [`_templates/_template.html`](_templates/_template.html) | Neues Jinja2/HTML-Template |
|
||||
|
||||
### Workflow: neue Datei aus Template erzeugen
|
||||
|
||||
```bash
|
||||
# Python-Datei
|
||||
cp _templates/_template.py app/mein_modul.py
|
||||
|
||||
# HTML-Template
|
||||
cp _templates/_template.html app/templates/meine_seite.html
|
||||
```
|
||||
|
||||
Anschließend im kopierten File die Platzhalter (`<...>`) ersetzen.
|
||||
|
||||
---
|
||||
|
||||
## 4. Kurzreferenz – Pflichtfelder auf einen Blick
|
||||
|
||||
| Feldname | Python (Docstring) | HTML (Kommentar) | Pflicht |
|
||||
|---|---|---|---|
|
||||
| Autor | `:author:` | `Autor:` | Ja |
|
||||
| Datum | `:date:` | `Datum:` | Ja |
|
||||
| Zweck/Titel | Erste Docstring-Zeile | `Zweck:` | Ja |
|
||||
| Version | `:version:` | – | Nein |
|
||||
| Dateiname | – | `Datei:` | Ja |
|
||||
Reference in new issue
Block a user