OAuth 2.0 API-Dokumentation

Gen. 24 Enterprise

Ab Build 7076 ist der schreibende und lesende Zugriff über die GraphQL-Schnittstelle in microtech büro+ möglich. Voraussetzung ist eine Gen. 24 Enterprise.

Notwendigkeit der GraphQL-Authentifizierung für Benutzer

Mit Build 7076 ist im Bereich Automatisierungs-Dienste unter Registerkarte: INFORMATIONEN - BENUTZER - BENUTZER VERWALTEN in den jeweiligen Benutzer-Datensätzen auf dem Register: FIRMENVORGABEN das Kennzeichen: "Zugriff über GraphQL erlaubt" verfügbar. Nur wenn dieses Kennzeichen aktiviert ist, ist der Benutzer berechtigt, über die Schnittstelle auf Daten zuzugreifen.

Info

Wird das Kennzeichen: "Zugriff über GraphQL erlaubt gesetzt", wird auch automatisch das Kennzeichen: "Benutzer kann sich immer anmelden" gesetzt, da dies eine Voraussetzung für den Zugriff per GraphQL ist.

1. Einführung

1.1. Was ist OAuth 2.0?

OAuth 2.0 ist ein branchenübliches Autorisierungsprotokoll, das es Anwendungen ermöglicht, sicheren und eingeschränkten Zugriff auf Benutzerkonten zu erhalten, ohne dass Passwörter direkt geteilt werden müssen.

Der wesentliche Vorteil liegt in der Trennung von Authentifizierung und Autorisierung: Benutzer authentifizieren sich direkt bei der microtech Software und erteilen dann gezielt Berechtigungen an Drittanwendungen.

1.2. OAuth 2.0 in der microtech Software

Die OAuth 2.0-Implementation in der microtech Software bietet:

Sichere API-Zugriffe: Externe Anwendungen können sicher auf die GraphQL-API zugreifen
Token-Verwaltung: Automatische Token-Rotation und Erneuerungsmechanismen
PKCE-Pflicht: Maximale Sicherheit durch obligatorisches PKCE (Proof Key for Code Exchange) für alle Clients
Duale Authentifizierung: Session-basiert für Browser, Token-basiert für APIs

Die Implementation folgt den Standards RFC 6749, RFC 7636, RFC 7009, RFC 6750 und RFC 9700 (OAuth 2.0 Security Best Current Practice).

1.3. Authentifizierung vs. Autorisierung

Die OAuth 2.0-Implementation in der microtech Software dient primär der Authentifizierung (Frage: "Wer ist der Benutzer?)". Die Autorisierung (Frage: "Was darf der Benutzer?") erfolgt durch die gewohnte Berechtigungsstruktur in der microtech Software.

Diese Architektur bedeutet:

OAuth identifiziert den Benutzer
Die microtech Software prüft die tatsächlichen Berechtigungen bei jeder Operation
Änderungen an Benutzerrechten werden sofort wirksam
Der OAuth-Scope graphql gewährt nur API-Zugang, nicht die Berechtigungen selbst

1.4. Voraussetzungen

microtech Software mit aktivierter GraphQL-Schnittstelle
HTTPS-fähiger Server (SSL-Zertifikat erforderlich)
Administrative Rechte zur Einrichtung von Anwendungen
Grundkenntnisse in OAuth 2.0 und REST-APIs

1.5. Authentifizierungsmethoden

Methode	Verwendung	Gültigkeit	Transport
Session	Browser, Entwickler-Werkzeuge	600 s (= 10 Min, auto-verlängernd)	HttpOnly Cookie
Bearer Token	Externe Anwendungen, APIs	3600 s (= 1 Std, konfigurierbar)	Authorization Header

Sessions haben Vollzugriff inklusive GraphQL (wenn Benutzer berechtigt).
OAuth-Tokens nur explizit gewährte Scopes.

1.6. Basis-URLs und Endpunkte

Basis-URL:

https://<server.domain>/microtech/erp/<graphql-server-pfad>/

OAuth-Endpunkte:

Endpunkt	Beschreibung
`/authorize`	Startet OAuth-Flow, zeigt Login und Consent
`/token`	Tauscht Codes gegen Tokens, erneuert Tokens
`/revoke`	Widerruft Tokens explizit
`/login`	Browser-Login für Session-basierte Authentifizierung
`/logout`	Beendet Browser-Session

API-Endpunkt:

Endpunkt	Beschreibung
`/graphql/v1`	GraphQL-API für Datenzugriff

HTTP-Methoden & Content Types:

Endpunkt	Methode	Content-Type / Beschreibung
`/authorize`	GET	Parameter in Query-String
	POST	`application/x-www-form-urlencoded`
`/token`	POST	`application/x-www-form-urlencoded`
`/revoke`	POST	`application/x-www-form-urlencoded`
`/login`	GET	HTML-Formular (Anmeldeseite)
`/logout`	GET	HTML-Seite (Logout-Bestätigung)
`/graphql/v1`	GET	HTML (interaktive Oberfläche, nur mit Session)
	POST	`application/json` (API-Zugriff)

1.7. Endpunkt-Authentifizierung

Endpunkt	Authentifizierungsmethode	Verhalten ohne Authentifizierung
`/authorize`	Session oder Basic Auth	Anmeldeformular, Parameter erhalten
`/token`	Client-Anmeldedaten	401 Unauthorized (JSON)
`/revoke`	Client-Anmeldedaten	401 Unauthorized (JSON)
`/login`	Formular-Anmeldedaten	Anmeldeformular
`/logout`	Optional: Session-Cookie	Logout-Bestätigung
`/graphql/v1`	Bearer oder Session	401 (Bearer) oder Anmeldeformular

Beachten Sie

Bei /graphql/v1 hat Bearer Token Vorrang - kein Rückfall auf Session bei ungültigem Bearer.

Info

Hinweis zu /authorize:

Falls Basic-Authentifizierung verwendet wird, erfolgt diese über Authorization: Basic <base64(username:password)> für die Benutzer-Authentifizierung.

2. Anwendung einrichten (OAuth-Client)

Pfad zum Einblenden des Registers: "Anwendungen"

Wechseln Sie in der Software MEINE FIMRA - ÜBERBLICK - Register: ÜBERBLICK - Gruppe: SYSTEMEINSTELLUNGEN - ANWENDUNGEN VERWALTEN.

Die Anwendungsverwaltung öffnet sich in einem neuen Tab und zeigt Ihnen alle registrierten Anwendungen. Beim ersten Aufrufen des Bereichs sollte die Tabelle zunächst leer sein.

2.2. Neue Anwendung erstellen

Schritt 1: Übersicht

Die Tabellenansicht zeigt:

Bezeichnung: Name der Anwendung
Client ID: Eindeutige Kennung (automatisch generiert)
Benutzernummer: Verknüpfter microtech-Benutzer (bei vertraulichen Anwendungen)
Client-Typ: Öffentlich oder Vertraulich
Redirect URI: Erste konfigurierte Rückruf-URL

Schritt 2: Neue Anwendung anlegen

Im Menüband befindet sich auf dem Register: START die Gruppe: NEU / BEARBEITEN mit den Schaltflächen: NEU, ÄNDERN, LÖSCHEN sowie WEITERE.

Klicken Sie auf die Schaltfläche: "Neu" im Menüband, um die Neuerfassung einer Anwendung aufzurufen. Es öffnet sich das Fenster: "Anwendung neu erfassen".

Schritt 3: Anwendung konfigurieren

Grundeinstellungen:

Feld	Beschreibung	Erforderlich
Bezeichnung	Name der Anwendung (wird im Zustimmungsdialog angezeigt)	Ja
Client-Typ	Öffentlich (Public) oder Vertraulich (Confidential)	Ja
Benutzer	microtech-Benutzer für Client Credentials Grant	Nur bei Vertraulich

Client-Typen im Detail:

Öffentlicher Client (Public Client):

Für Browser-Anwendungen, Mobile Apps, Desktop-Anwendungen
Kein Secret erforderlich
Automatische Token-Rotation bei Erneuerung

Vertraulicher Client (Confidential Client):

Für Server-Anwendungen und Backend-Services
Secret erforderlich und muss sicher gespeichert werden
Optionale Token-Rotation
Unterstützt Client Credentials Grant (nur mit verknüpftem microtech-Benutzer)

Technische Einstellungen:

Feld	Beschreibung	Standard	Konfigurierbar
Client-ID	512-Bit Zufallswert, Base64URL	Auto-generiert	Nein
Client-Secret	512-Bit Zufallswert, Base64URL	Auto-generiert	Nein
Redirect URIs	Eine pro Zeile, exakte Übereinstimmung	-	Ja
Code-Gültigkeit	Authorization Code Lebensdauer (Minuten)	5 Min (= 300 s)	Ja
Access-Token	API-Zugriffsdauer (Minuten)	60 Min (= 3600 s)	Ja
Refresh-Token	Gültigkeit für Token-Erneuerung (Minuten)	43200 Min (= 30 Tage = 2592000 s)	Ja

Scopes (Checkboxen):

Scope	Bedeutung	Wenn deaktiviert
Autorisierungscodes anfordern	Ermöglicht Authorization Code Flow	Nur Client Credentials Grant möglich
Zugriffstokens anfordern	Kann Access Tokens erhalten	Anwendung funktioniert nicht
Aktualisierungstokens anfordern	Erhält Refresh Tokens	Keine Refresh Token-Erneuerung möglich
GraphQL-API Zugriff	Tokens können API nutzen	API-Zugriff verweigert (401)

Schritt 4: Anmeldedaten sichern

Beachten Sie

Client-ID und Secret werden bei Neuanlage einer Anwendung von der Software automatisch ausgefüllt.

Kopieren Sie beide Werte mit den Kopier-Buttons vor dem Speichern!

Das Secret wird danach nur als Hash gespeichert und kann nicht mehr wiederhergestellt werden. Bewahren Sie deshalb beide Werte sicher auf (z. B. in einem Passwort-Manager) und geben Sie diese nicht weiter. Bei Verlust müssen neue Anmeldedaten erstellt werden.

Schritt 5: Speichern

Nach dem Sichern der Anmeldedaten bestätigen Sie das Neuerfassen der Anwendung mit Schaltfläche: "Speichern & schließen".

2.3. Anwendungen verwalten

Anwendung bearbeiten mit Schaltfläche: ÄNDERN

Auf dem Register: ANWENDUNGEN lässt sich ein Datensatz in der Tabelle über Doppelklick bzw. Auswahl + Schaltfläche: "Ändern" öffnen.
Die Client-ID und das Secret können nicht geändert werden
Alle anderen Einstellungen im Fenster: "Anwendung ändern" können jedoch angepasst werden.

Secret erneuern

Anwendung zur Bearbeitung öffnen
Im Menüband finden Sie im Bereich "Secret" die Schaltfläche: "Neu"
Mit betätigen der Schaltfläche wird ein neues Client-Secret erzeugt und angezeigt. Kopieren Sie direkt das neue Client-Secret
Speichern und schließen Sie anschließend das Fenster
Alle externen Systeme sind nun mit dem neuem Secret zu aktualisieren

info

Bestehende Tokens bleiben bis zu ihrem normalen Ablauf gültig.

Anwendung löschen

Wählen Sie auf dem Register die zu löschende App und wählen Sie im Menüband die Schaltfläche: "Löschen"

Achtung

Alle aktiven Tokens werden sofort ungültig!
Gelöschte Anwendungen können nicht wiederhergestellt werden.
Die Client-ID kann nicht wiederverwendet werden.

Anwendung sperren

Wählen Sie zunächst den gewünschten Tabelleneintrag. Im Menüband wählen Sie nun Schaltfläche: WEITERE - Sperren.

Aktivieren Sie in dem sich öffnendem Fenster im Bereich: "Sperrvermerk" das Kennzeichen "Gesperrt am". Passen Sie ggf. das Datum an, sofern zu einem abweichenden Zeitpunkt die Sperrung gültig sein soll. Speichern & schließen Sie das Fenster. Die Sperrung kann über den erneuten Aufruf des Fensters und die Deaktivierung des Kennzeichens wieder abgeschaltet werden.

Beachten Sie

Durch das Sperren der Anwendung werden alle bestehenden Tokens dieser Anwendung temporär ungültig!
Token werden durch das Sperren nicht gelöscht, sondern nur blockiert.
Nach dem Entsperren sind die Tokens wieder gültig (sofern nicht abgelaufen).
Neue Token-Anfragen werden während der Sperrung abgelehnt.

Unterschied zwischen Sperren und Scope-Entfernung: - Anwendung sperren: Temporäre Blockade aller Token-Operationen. - Scope "Autorisierungscodes anfordern" entfernen: Verhindert nur neue Authorization Codes, bestehende Tokens bleiben gültig.

2.4. Beispielkonfigurationen

Öffentliche Anwendung (Mobile App):

Bezeichnung: Mobile Verkaufs-App
Typ: Öffentlich
Redirect URI: com.microtech.sales://callback
Scopes: Alle aktiviert
Token-Gültigkeit: Standard

Vertrauliche Anwendung (Server-Integration):

Bezeichnung: E-Commerce Backend
Typ: Vertraulich
Benutzer: api-benutzer (microtech-Benutzer - im Beispiel "2 Maria Muster")
Redirect URI: https://shop.example.com/oauth/callback
Scopes: Alle aktiviert
Access-Token: 30 Min (= 1800 s)
Refresh-Token: 10080 Min (= 7 Tage = 604800 s)

3. OAuth 2.0 Flows

Welchen Flow wann verwenden?

Flow	Client-Typ	Verwendungszweck
Authorization Code mit PKCE	Öffentlich & Vertraulich	Anwendung agiert im Namen eines Endbenutzers
Client Credentials	Nur Vertraulich	Anwendung agiert eigenständig (Machine-to-Machine)
Refresh Token	Öffentlich & Vertraulich	Token-Erneuerung ohne Benutzer-Interaktion

3.1. Authorization Code Flow mit PKCE

PKCE (Proof Key for Code Exchange) ist verpflichtend für alle Anwendungen, sowohl öffentliche als auch vertrauliche. Die redirect_uri muss exakt (bitgenau) mit einer der registrierten URIs übereinstimmen.

Schritt 1: PKCE-Werte generieren

Code Verifier: Zufälliger String mit 43-128 Zeichen
Erlaubte Zeichen: [A-Z] [a-z] [0-9] - . _ ~
Beispiel: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
Code Challenge: SHA256-Hash des Verifiers
Formel: BASE64URL(SHA256(code_verifier))
Ohne Padding (= Zeichen entfernen)

Schritt 2: Autorisierungsanfrage

GET-Variante:

GET https://<server>/microtech/erp/<graphql-server-pfad>/authorize?
  response_type=code&
  client_id=<CLIENT_ID>&
  redirect_uri=<REDIRECT_URI>&
  code_challenge=<CHALLENGE>&
  code_challenge_method=S256&
  scope=graphql&
  state=<RANDOM_STATE>

POST-Variante (identische Parameter im Body):

POST /microtech/erp/<graphql-server-pfad>/authorize HTTP/1.1
Host: <server>
Content-Type: application/x-www-form-urlencoded

response_type=code&
client_id=<CLIENT_ID>&
redirect_uri=<REDIRECT_URI>&
code_challenge=<CHALLENGE>&
code_challenge_method=S256&
scope=graphql&
state=<RANDOM_STATE>

Parameter: | Parameter | Pflicht | Beschreibung | |-----------|---------|--------------| | response_type | Ja | Muss code sein | | client_id | Ja | Ihre Client-ID | | redirect_uri | Ja | Muss exakt mit einer registrierten URI übereinstimmen | | code_challenge | Ja | PKCE Challenge | | code_challenge_method | Ja | Muss S256 sein | | scope | Nein | Angeforderte Scopes (z.B. graphql) | | state | Empfohlen | CSRF-Schutz |

Beachten Sie

Exact Match: Die redirect_uri muss bitgenau mit einer der registrierten URIs übereinstimmen (exakte Zeichenketten-Übereinstimmung, inklusive Schema, Host, Port, Pfad und Query-Parameter).

Schritt 3: Benutzer-Interaktion

Anmeldung (falls nicht angemeldet)
OAuth-Parameter werden automatisch gespeichert und nach Anmeldung wiederhergestellt
Zustimmungsdialog zeigt:
Name der anfragenden Anwendung
Angeforderte Scopes
Aktuell angemeldeter Benutzer
"Nicht Sie?" Link für Benutzerwechsel
Benutzerentscheidung: Zustimmung oder Ablehnung

Antworten: - Erfolg: redirect_uri?code=<CODE>&state=<STATE> - Ablehnung: redirect_uri?error=access_denied&state=<STATE> - Fehler: redirect_uri?error=<ERROR>&error_description=<DESC>&state=<STATE>

Schritt 4: Token-Austausch

Vertrauliche Anwendung:

POST /token HTTP/1.1
Authorization: Basic <BASE64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=<AUTHORIZATION_CODE>&
redirect_uri=<REDIRECT_URI>&
code_verifier=<VERIFIER>

Beachten Sie

Wichtig: Die redirect_uri muss exakt mit der URI übereinstimmen, die in der Autorisierungsanfrage verwendet wurde.

Öffentliche Anwendung:

POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=<AUTHORIZATION_CODE>&
redirect_uri=<REDIRECT_URI>&
code_verifier=<VERIFIER>&
client_id=<CLIENT_ID>

Wichtig: Die redirect_uri muss exakt mit der URI übereinstimmen, die in der Autorisierungsanfrage verwendet wurde.

Erfolgsantwort:

{
  "access_token": "vEQzaMu0i-E-7QbDSdeI...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rW31CSnakl9kwuUB2XLC...",
  "refresh_expires_in": 2592000,
  "scope": "graphql",
  "refresh_scope": "request_access_token request_refresh_token graphql"
}

OAuth Scope-Namen:

Scope-Name	Typ	Bedeutung
`request_code`	Intern	Kann Authorization Codes anfordern (nur Session-Tokens)
`request_access_token`	Intern	Kann Access Tokens anfordern
`request_refresh_token`	Intern	Kann Refresh Tokens anfordern
`graphql`	Client	Zugriff auf GraphQL-API

Scope-Verhalten in Responses: - scope: Enthält nur Client-Scopes des Access Tokens (z.B. "graphql") - refresh_scope: Enthält Client-Scopes + interne Scopes des Refresh Tokens (z.B. "request_access_token request_refresh_token graphql") - Mehrere Scopes werden space-getrennt zurückgegeben - Interne Scopes steuern, welche Token-Operationen möglich sind

Hinweise zu nicht-standard Feldern: - refresh_expires_in: Gültigkeit des Refresh Tokens in Sekunden (Standard-OAuth spezifiziert keine Refresh Token Lebensdauer-Sichtbarkeit) - scope: Tatsächliche Berechtigungen des Access Tokens - refresh_scope: Maximale Scopes für zukünftige Token-Erneuerungen

Beachten Sie

Wichtig: Authorization Codes sind nur einmal verwendbar. Wiederverwendung führt zur sofortigen Sperrung aller abgeleiteten Tokens (Security Breach).

3.2. Client Credentials Grant

Nur für vertrauliche Anwendungen mit verknüpftem microtech-Benutzer. Dieser Benutzer bestimmt die Berechtigungen in der microtech Software.

Wann welchen Flow verwenden (Vertrauliche Clients)? - Authorization Code Flow: Wenn die Anwendung im Namen eines Endbenutzers agiert (z.B. Web-Portal wo sich verschiedene Benutzer anmelden) - Client Credentials Grant: Wenn die Anwendung eigenständig agiert (z.B. nächtliche Synchronisation, automatisierte Prozesse)

Anfrage:

POST /token HTTP/1.1
Authorization: Basic <BASE64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
scope=graphql

Antwort:

{
  "access_token": "kU9QpgL6stOLX9RNBkLA...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "graphql"
}

Wichtig: Client Credentials Grant gibt niemals ein Refresh Token zurück (RFC 6749 Section 4.4.3). Die Anwendung kann sich jederzeit mit Client-ID und Secret neu authentifizieren.

3.3. Token-Erneuerung (Refresh Token Grant)

Laufzeit bei Rotation: Neu ausgegebene Refresh Tokens erhalten die volle im Anwendungsdatensatz konfigurierte Laufzeit (Sliding TTL).

Fehlerbehandlung: Bei Fehlverwendung (z.B. Wiederverwendung eines bereits rotierten Refresh Tokens) erfolgt sofortige Invalidierung der gesamten Token-Kette. Recovery erfordert vollständige Neuauthentifizierung.

Vertrauliche Anwendung:

POST /token HTTP/1.1
Authorization: Basic <BASE64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=<REFRESH_TOKEN>&
scope=<OPTIONAL_RESTRICTED_SCOPE>

Öffentliche Anwendung:

POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=<REFRESH_TOKEN>&
client_id=<CLIENT_ID>&
scope=<OPTIONAL_RESTRICTED_SCOPE>

Scope-Verhalten bei Erneuerung: - Ohne scope Parameter: Access Token erhält alle Scopes des Refresh Tokens - Mit scope Parameter: Access Token erhält nur die angeforderten Scopes (muss Teilmenge der Refresh Token Scopes sein) - Refresh Token behält immer seine ursprünglichen Scopes (vom Authorization Code)

Token-Rotation: - Öffentliche Anwendungen: Refresh Token rotiert automatisch - das alte wird ungültig - Vertrauliche Anwendungen: Optional via rotate_refresh_token=true

Antwort mit Rotation:

{
  "access_token": "neues_access_token...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "neues_refresh_token...",
  "scope": "graphql",
  "refresh_scope": "request_access_token request_refresh_token graphql"
}

Bedeutung der Scope-Felder: - scope: Tatsächliche Scopes des Access Tokens (kann eingeschränkt sein wenn bei Anfrage angegeben) - refresh_scope: Maximale Scopes des Refresh Tokens für zukünftige Erneuerungen (unverändert vom Original)

Beachten Sie

Wichtig bei Token-Rotation:

Das neue Refresh Token muss sofort gespeichert werden
Das alte Refresh Token wird ungültig
Wiederverwendung eines rotierten Tokens führt zur Sperrung der gesamten Token-Kette

3.4. Token-Widerruf

Der /revoke Endpunkt akzeptiert alle Token-Typen (Session, Authorization Code, Access Token, Refresh Token) mit unterschiedlichen Auswirkungen.

Vertrauliche Anwendung:

POST /revoke HTTP/1.1
Authorization: Basic <BASE64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

token=<TOKEN_TO_REVOKE>

Öffentliche Anwendung:

POST /revoke HTTP/1.1
Content-Type: application/x-www-form-urlencoded

token=<TOKEN_TO_REVOKE>&
client_id=<CLIENT_ID>

Antwort: Immer HTTP 200 OK (auch wenn Token nicht existiert oder bereits ungültig)

Widerruf-Auswirkungen nach Token-Typ: - Session Token: Beendet die Browser-Session - Authorization Code: Alle abgeleiteten Access/Refresh Tokens werden ungültig - Access Token: Nur dieses Token wird ungültig - Refresh Token: Token und alle damit erneuerten Tokens werden ungültig

Kaskadierender Widerruf: Bei Authorization Codes und Refresh Tokens werden automatisch alle abgeleiteten Tokens ungültig.

3.5. Logout

Beendet die aktuelle Browser-Session.

GET /logout HTTP/1.1
Cookie: microtech_session=<SESSION_TOKEN>

Antwort: HTML-Seite mit Logout-Bestätigung. Session-Cookie wird gelöscht.

4. GraphQL-API verwenden

4.1. API-Aufruf mit Bearer Token

POST /graphql/v1 HTTP/1.1
Host: <server.domain>
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "query": "{ tblArtikel { rowsRead { fldArtNr } } }"
}

4.2. Authentifizierungs-Priorität

Der GraphQL-Endpunkt akzeptiert zwei Authentifizierungsmethoden:

Bearer Token (für externe Anwendungen)
Hat Vorrang wenn Authorization: Bearer Header vorhanden
Bei ungültigem Token: 401 Unauthorized
Kein Rückfall auf Session bei Fehler
Session Cookie (für Browser-Zugriff)
Wird verwendet wenn kein Bearer Header vorhanden
Bei fehlender Session: Anmeldeformular

4.3. Berechtigungen

Die tatsächlichen Datenzugriffsrechte werden durch die Berechtigungen des authentifizierten Benutzers in der microtech Software bestimmt, nicht durch OAuth-Scopes.

5. Sicherheit

5.1. PKCE (Proof Key for Code Exchange)

Verpflichtend für alle Anwendungen (öffentlich und vertraulich)
Nur S256 (SHA256) unterstützt, plain wird abgelehnt
Verifier: 43-128 Zeichen
Schützt vor Code-Injection-Angriffen

5.2. Single-Use-Erkennung

Authorization Codes: Nur einmal verwendbar (Standard: 300 s = 5 Min gültig, konfigurierbar)
Rotierende Refresh Tokens: Nur einmal verwendbar
Security Breach Response: Komplette Token-Kette wird bei Wiederverwendung invalidiert

5.3. Token-Rotation

Automatisch für öffentliche Anwendungen
Optional für vertrauliche Anwendungen (rotate_refresh_token=true)
Altes Token wird bei Rotation sofort ungültig
Neu ausgegebene Refresh Tokens erhalten die volle konfigurierte Laufzeit
Schützt vor Token-Diebstahl

5.4. Rate Limiting

2 freie Fehlversuche pro IP
Feste Verzögerung für Versuche 3-25 (Endpunkt-spezifisch)
300 s (= 5 Min) Blockade nach 25 Fehlversuchen
Erfolgreiche Anfragen setzen den Fehlversuchs-Zähler zurück
Endpunkt-spezifische Verzögerungen:
/authorize: 100ms zwischen Anfragen
/token, /revoke: 200ms zwischen Anfragen

5.5. Session-Verwaltung

Gültigkeit: 600 s (= 10 Min) initial
Auto-Verlängerung: Bei jeder Verwendung
Cookie-Eigenschaften: HttpOnly, SameSite=Lax, Secure (bei HTTPS)
Berechtigungen: Vollzugriff für authentifizierte Benutzer

5.6. Formular-Sicherheit

HMAC-SHA256 Signatur auf allen Formularen
300 s (= 5 Min) Gültigkeit
Zeitstempel-Validierung
Parameter-Erhaltung bei Anmelde-Unterbrechung

5.7. Token-Formate

Access und Refresh Tokens sind opaque (512-Bit kryptographisch sicher)
Base64URL-kodiert für Transport
Ausschließlich zur internen Verwendung
Keine Introspection-Endpoints verfügbar

6. Fehlerbehandlung

6.1. OAuth-Fehlercodes

Fehlercode	HTTP Status	Bedeutung
`invalid_request`	400	Fehlende oder ungültige Parameter
`invalid_client`	401	Client-Authentifizierung fehlgeschlagen
`invalid_grant`	400	Authorization Code oder Token ungültig/abgelaufen
`unauthorized_client`	400	Client nicht für diesen Grant Type autorisiert
`unsupported_grant_type`	400	Grant Type nicht unterstützt
`invalid_scope`	400	Ungültiger oder nicht erlaubter Scope
`access_denied`	400	Benutzer hat Zugriff verweigert
`unsupported_response_type`	400	Response Type nicht unterstützt
`invalid_token`	401	Bearer Token ungültig (RFC 6750)
`server_error`	500	Interner Serverfehler
`temporarily_unavailable`	503	Service temporär nicht verfügbar

6.2. Antwort-Formate

JSON-Fehlerantwort (OAuth-Fehler):

{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid, expired, or revoked"
}

401 Unauthorized mit WWW-Authenticate (RFC 6750):

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="GraphQL API"
Content-Type: application/json

{
  "error": "authentication_required",
  "message": "Bearer token is missing, invalid or expired"
}

GraphQL-Berechtigungsfehler (HTTP 200):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": null,
  "errors": [
    {
      "message": "Validation error: Field 'tblGeheim' not found in type 'Query'",
      "extensions": {"code": "VALIDATION_ERROR"}
    }
  ]
}

Hinweis: Mit gültigem Token erreicht die Anfrage immer den GraphQL-Server (HTTP 200). Berechtigungsprüfungen erfolgen dann auf GraphQL-Ebene: - Schema-Validierung: Nicht erlaubte Felder/Tabellen sind gar nicht im Schema sichtbar - Ausführungsfehler: Fehlende Rechte für spezifische Operationen werden als GraphQL-Fehler zurückgegeben

Ein HTTP 401 erscheint nur bei fehlendem oder ungültigem Bearer Token.

Umleitungs-Fehler:

https://app.example.com/callback?
  error=access_denied&
  error_description=The%20user%20denied%20access&
  state=<STATE>

6.3. Rate Limiting Antworten

HTTP/1.1 429 Too Many Requests
Retry-After: 300
Content-Type: application/json

{
  "error": "too_many_requests",
  "error_description": "Rate limit exceeded. Retry after 300 seconds."
}

7. Token-Lebenszyklus

Token-Typ	Standard	Konfigurierbar	Verwendung
Authorization Code	300 s (= 5 Min)	Ja*	Einmaliger Austausch gegen Tokens
Access Token	3600 s (= 1 Std)	Ja*	API-Zugriff via Bearer
Refresh Token	2592000 s (= 30 Tage)	Ja*	Token-Erneuerung
Session Token	600 s (= 10 Min, auto-verlängernd)	Nein	Browser-Zugriff

*Konfigurierbar pro Anwendung in der Anwendungsverwaltung

Hinweise: - Eingabe in der Anwendungsverwaltung erfolgt in Minuten - API-Responses geben Zeiten in Sekunden zurück

8. Best Practices

8.1. Sicherheitsempfehlungen

HTTPS zwingend in Produktivumgebungen
State-Parameter immer für CSRF-Schutz verwenden (mindestens 128 Bit Entropie)
Token-Speicherung:
Niemals in LocalStorage
Verwenden: In-Memory, SessionStorage oder sichere Backend-Speicherung
Kurze Access-Token-Laufzeiten (maximal 1 Stunde empfohlen)
Minimale Scopes anfordern (Principle of Least Privilege)
Token-Widerruf bei Logout implementieren

8.2. Wahl der Authentifizierungsmethode

Session-basiert verwenden für: - Browser-basierte Verwaltungswerkzeuge - Entwicklung und Tests - Interne Web-Anwendungen

Bearer Token verwenden für: - Externe Anwendungen - Mobile Apps - Server-zu-Server-Kommunikation - API-Automatisierung

8.3. Fehlerbehandlung

Implementieren Sie Retry-Logik mit exponentieller Verzögerung
Beachten Sie Retry-After Header bei 429-Fehlern
Erneuern Sie Tokens proaktiv vor Ablauf
Behandeln Sie Token-Rotation-Fehler durch komplette Neuauthentifizierung

8.4. Token-Verwaltung

Speichern Sie Ablaufzeiten und erneuern Sie proaktiv
Bei Token-Rotation: Neues Token sofort speichern, altes verwerfen
Implementieren Sie Fallback zu Neuauthentifizierung
Single-Use-Violations führen zu sofortiger Token-Sperrung (Security Breach)

Anhang A: Glossar

Begriff	Beschreibung
Access Token	Kurzlebiges Token für API-Zugriff
Authorization Code	Einmaliger Code für Token-Austausch
Bearer Token	Token-Typ für API-Zugriff via HTTP Authorization Header
Client Credentials	Client-ID und Client-Secret
Code Challenge	SHA256-Hash des Code Verifiers (PKCE)
Code Verifier	Zufälliger String für PKCE
Grant Type	OAuth-Flow-Typ (authorization_code, refresh_token, etc.)
PKCE	Proof Key for Code Exchange - Sicherheitserweiterung
Redirect URI	Rückruf-URL nach Autorisierung
Refresh Token	Langlebiges Token zur Token-Erneuerung
Scope	Berechtigungsbereich (z.B. `graphql`)
Secret	Client-Secret für vertrauliche Anwendungen
Single-Use	Token/Code kann nur einmal verwendet werden
State	CSRF-Schutz-Parameter
Token Rotation	Automatischer Austausch bei Erneuerung

OAuth 2.0 API-Dokumentation

1. Einführung

1.1. Was ist OAuth 2.0?

1.2. OAuth 2.0 in der microtech Software

1.3. Authentifizierung vs. Autorisierung

1.4. Voraussetzungen

1.5. Authentifizierungsmethoden

1.6. Basis-URLs und Endpunkte

1.7. Endpunkt-Authentifizierung

2. Anwendung einrichten (OAuth-Client)

2.1. Navigation zur Anwendungsverwaltung

2.2. Neue Anwendung erstellen

Schritt 1: Übersicht

Schritt 2: Neue Anwendung anlegen

Schritt 3: Anwendung konfigurieren

Schritt 4: Anmeldedaten sichern

Schritt 5: Speichern

2.3. Anwendungen verwalten

Anwendung bearbeiten mit Schaltfläche: ÄNDERN

Secret erneuern

Anwendung löschen

Anwendung sperren

2.4. Beispielkonfigurationen

3. OAuth 2.0 Flows

3.1. Authorization Code Flow mit PKCE

Schritt 1: PKCE-Werte generieren

Schritt 2: Autorisierungsanfrage

Schritt 3: Benutzer-Interaktion

Schritt 4: Token-Austausch

3.2. Client Credentials Grant

3.3. Token-Erneuerung (Refresh Token Grant)

3.4. Token-Widerruf

3.5. Logout

4. GraphQL-API verwenden

4.1. API-Aufruf mit Bearer Token

4.2. Authentifizierungs-Priorität

4.3. Berechtigungen

5. Sicherheit

5.1. PKCE (Proof Key for Code Exchange)

5.2. Single-Use-Erkennung

5.3. Token-Rotation

5.4. Rate Limiting

5.5. Session-Verwaltung

5.6. Formular-Sicherheit

5.7. Token-Formate

6. Fehlerbehandlung

6.1. OAuth-Fehlercodes

6.2. Antwort-Formate

6.3. Rate Limiting Antworten

7. Token-Lebenszyklus

8. Best Practices

8.1. Sicherheitsempfehlungen

8.2. Wahl der Authentifizierungsmethode

8.3. Fehlerbehandlung

8.4. Token-Verwaltung

Anhang A: Glossar

Anhang B: Referenzen