> ## Documentation Index
> Fetch the complete documentation index at: https://aipro.placetel.de/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth-Anbieter (JWT)

> JWT OAuth-Authentifizierung für externe APIs -- Google, Microsoft und TKP.

## Was ist ein JWT OAuth-Anbieter?

Ein **JWT OAuth-Anbieter** ermöglicht es Ihrem KI-Assistenten, sich automatisch bei externen APIs zu authentifizieren. Anstatt statische API-Schlüssel zu verwenden, wird ein signiertes JWT (JSON Web Token) erstellt und gegen ein kurzlebiges Access Token eingetauscht. Abgelaufene Tokens werden automatisch erneuert.

<Info>
  **Sicherheit:** Alle gespeicherten Zugangsdaten (Private Keys, Tokens) werden verschlüsselt gespeichert und sind nur für Ihren Account zugänglich.
</Info>

**Typische Anwendungsfälle:**

* Google Cloud APIs (z.B. Google Calendar, Google Sheets)
* Microsoft Graph API (z.B. Outlook, Teams)
* TKP / soft-nrg Werkstattplanungssystem

## Wo finde ich die OAuth-Anbieter?

1. Klicken Sie unten links auf Ihren **Account**
2. Wählen Sie **OAuth-Anbieter**

Dort sehen Sie eine Liste aller konfigurierten OAuth-Anbieter und können neue erstellen.

## Wo wird der OAuth-Anbieter verwendet?

### Im API-Tool

Beim Erstellen oder Bearbeiten eines **API-Tools** finden Sie das Dropdown **"OAuth-Anbieter verknüpfen (optional)"**. Hier können Sie einen zuvor erstellten OAuth-Anbieter auswählen. Der KI-Assistent verwendet dann automatisch ein gültiges Access Token bei jedem API-Aufruf und erneuert es selbstständig, sobald es abgelaufen ist.

Unter dem Dropdown finden Sie den Link **"+ Neuen OAuth-Anbieter erstellen"**, der die OAuth-Anbieter Verwaltung in einem neuen Tab öffnet.

### In der TKP-Integration

Bei der Konfiguration der **TKP-Integration** (Werkstatttermine) ist ein JWT OAuth-Anbieter erforderlich. Wählen Sie den passenden Anbieter im Dropdown aus.

## Neuen JWT OAuth-Anbieter erstellen

1. Öffnen Sie die **OAuth-Anbieter** Seite
2. Klicken Sie auf den Dropdown **"Neuen OAuth-Anbieter erstellen"**
3. Wählen Sie **"JWT OAuth"**
4. Optional: Wählen Sie eine **Quick Start Vorlage** (Google, Microsoft oder TKP)
5. Füllen Sie die restlichen Felder aus
6. Testen Sie die Verbindung
7. Klicken Sie auf **Speichern**

## Quick Start Vorlagen

Beim Erstellen eines neuen JWT OAuth-Anbieters stehen drei vorkonfigurierte Vorlagen zur Verfügung. Diese füllen die meisten Felder automatisch aus -- Sie müssen nur noch Ihre individuellen Zugangsdaten eintragen.

| Quick Start   | Beschreibung                                   | Was wird ausgefüllt?                                                          |
| ------------- | ---------------------------------------------- | ----------------------------------------------------------------------------- |
| **Google**    | Für Google Cloud APIs (Calendar, Sheets, etc.) | Token URL, Algorithmus, Lifetime, Audience, Grant Type                        |
| **Microsoft** | Für Microsoft Graph / Azure AD                 | Token URL, Algorithmus, Lifetime, Audience, Grant Type, Client Assertion Type |
| **TKP**       | Für das soft-nrg Werkstattplanungssystem       | Token URL, Algorithmus, Lifetime, Audience, Scope, Grant Type                 |

<Info>
  **Hinweis:** Quick Start Vorlagen sind nur beim Erstellen neuer Anbieter verfügbar (nicht beim Bearbeiten). Bereits eingegebene sensible Daten (Private Key, Issuer) bleiben beim Wechsel der Vorlage erhalten.
</Info>

## Formularfelder im Detail

### Grundeinstellungen

| Feld          | Beschreibung                                      | Pflicht |
| ------------- | ------------------------------------------------- | ------- |
| **Name**      | Beschreibender Name (z.B. "Google Calendar Prod") | Ja      |
| **Token URL** | OAuth Token-Endpunkt URL (nur HTTPS)              | Ja      |

### JWT-Signierung

| Feld                  | Beschreibung                                | Standard |
| --------------------- | ------------------------------------------- | -------- |
| **Algorithmus**       | RS256, RS384, RS512, ES256, ES384, ES512    | RS256    |
| **JWT Lebensdauer**   | Gültigkeit des JWT in Sekunden              | 300      |
| **Key ID**            | Optionale Key-ID für den JWT Header ("kid") | --       |
| **Private Key (PEM)** | Ihr RSA- oder ECDSA-Schlüssel im PEM-Format | Pflicht  |

### JWT Claims (Payload)

| Feld               | Beschreibung                                                  | Pflicht |
| ------------------ | ------------------------------------------------------------- | ------- |
| **Issuer (iss)**   | Absender -- meist Client-ID oder Service-Account-E-Mail       | Ja      |
| **Subject (sub)**  | Betreff -- bei Microsoft wird der Issuer verwendet, wenn leer | Nein    |
| **Audience (aud)** | Empfänger -- meist die Token-URL                              | Ja      |
| **Scope**          | OAuth Berechtigungen, durch Leerzeichen getrennt              | Nein    |

### Antwortformat

| Feld                    | Beschreibung                       | Standard        |
| ----------------------- | ---------------------------------- | --------------- |
| **Token-Feldname**      | JSON-Feld mit dem Access Token     | access\_token   |
| **Expires-In-Feldname** | JSON-Feld mit der Token-Gültigkeit | expires\_in     |
| **Grant Type**          | OAuth 2.0 Grant-Typ                | je nach Vorlage |

### Erweiterte Optionen

| Feld                           | Beschreibung                                                       |
| ------------------------------ | ------------------------------------------------------------------ |
| **Header Extras**              | Zusätzliche JWT-Header-Felder als JSON (z.B. `{"x5t":"..."}`)      |
| **Extra Token Request Params** | Zusätzliche Parameter für den Token-Request als JSON               |
| **JWT Assertion Field Name**   | Feldname für die JWT-Assertion im POST Body                        |
| **Client Assertion Type**      | Typ der Client-Assertion (für Microsoft)                           |
| **Scope im POST Body senden**  | Erforderlich für bestimmte Client-Assertion-Flows (z.B. Microsoft) |

## Beispiel: TKP (Werkstattplanung)

<Tip>
  **Quick Start:** Klicken Sie auf **TKP** -- die meisten Felder werden automatisch ausgefüllt.
</Tip>

**Automatisch ausgefüllte Felder:**

* **Token URL:** `https://auth.soft-nrg.com/oauth/token`
* **Algorithmus:** RS256
* **JWT Lebensdauer:** 300 Sekunden
* **Audience:** `https://auth.soft-nrg.com/oauth/token`
* **Scope:** `scope.api.planning.extendedplan`
* **Grant Type:** `urn:ietf:params:oauth:grant-type:jwt-bearer`

**Was Sie noch eintragen müssen:**

1. **Name** -- z.B. "TKP Werkstatt Prod"
2. **Private Key** -- Ihren RSA Private Key im PEM-Format (erhalten Sie von soft-nrg)
3. **Key ID** -- Ihre Key-ID von soft-nrg (falls vorhanden)
4. **Issuer (iss)** -- Ihre Client-ID von soft-nrg
5. **Subject (sub)** -- falls von soft-nrg vorgegeben

**Verwendung:** Verknüpfen Sie den erstellten Anbieter anschließend in der **TKP-Integration**.

## Beispiel: Google Cloud API

<Tip>
  **Quick Start:** Klicken Sie auf **Google** -- die meisten Felder werden automatisch ausgefüllt.
</Tip>

**Automatisch ausgefüllte Felder:**

* **Token URL:** `https://oauth2.googleapis.com/token`
* **Algorithmus:** RS256
* **JWT Lebensdauer:** 3600 Sekunden (1 Stunde)
* **Audience:** `https://oauth2.googleapis.com/token`
* **Grant Type:** `urn:ietf:params:oauth:grant-type:jwt-bearer`

**Was Sie noch eintragen müssen:**

1. **Name** -- z.B. "Google Calendar Prod"
2. **Private Key** -- aus der Google Cloud Service Account JSON-Datei (Feld `private_key`)
3. **Key ID** -- aus der JSON-Datei (Feld `private_key_id`), falls vorhanden
4. **Issuer (iss)** -- die Service Account E-Mail (z.B. `mein-service@projekt.iam.gserviceaccount.com`)
5. **Subject (sub)** -- die E-Mail des Nutzers, in dessen Namen gehandelt wird (bei Domain-weiter Delegierung)
6. **Scope** -- die benötigten Berechtigungen, z.B.:
   * Google Calendar: `https://www.googleapis.com/auth/calendar`
   * Google Sheets: `https://www.googleapis.com/auth/spreadsheets`

**Verwendung:** Verknüpfen Sie den erstellten Anbieter im **API-Tool**, das die Google API aufruft.

## Beispiel: Microsoft Graph API

<Tip>
  **Quick Start:** Klicken Sie auf **Microsoft** -- die meisten Felder werden automatisch ausgefüllt.
</Tip>

**Automatisch ausgefüllte Felder:**

* **Token URL:** `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token`
* **Algorithmus:** RS256
* **JWT Lebensdauer:** 600 Sekunden (10 Minuten)
* **Audience:** `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token`
* **Grant Type:** `client_credentials`
* **Client Assertion Type:** `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
* **Scope im POST Body senden:** Aktiviert

<Warning>
  **Wichtig:** Ersetzen Sie `{tenant}` in der Token URL und Audience durch Ihre Azure Tenant-ID!
</Warning>

**Was Sie noch eintragen müssen:**

1. **Name** -- z.B. "Microsoft Graph Prod"
2. **Token URL** -- ersetzen Sie `{tenant}` durch Ihre Azure Tenant-ID
3. **Audience** -- ersetzen Sie `{tenant}` durch Ihre Azure Tenant-ID
4. **Private Key** -- Ihr Zertifikats-Private-Key im PEM-Format
5. **Key ID** -- der Thumbprint Ihres Zertifikats
6. **Issuer (iss)** -- Ihre Azure Application (Client) ID
7. **Subject (sub)** -- Ihre Azure Application (Client) ID (bei Microsoft identisch mit Issuer)
8. **Scope** -- z.B. `https://graph.microsoft.com/.default`
9. **Header Extras** (optional) -- `{"x5t":"IHR_ZERTIFIKATS_THUMBPRINT"}` (Hex-Werte werden automatisch in Base64url konvertiert)

**Verwendung:** Verknüpfen Sie den erstellten Anbieter im **API-Tool**, das die Microsoft Graph API aufruft.

## Verbindung testen

Nach dem Ausfüllen des Formulars können Sie die Verbindung testen, **bevor** Sie den Anbieter speichern:

1. Klicken Sie auf **Verbindung testen**
2. Das System erstellt ein JWT und tauscht es gegen ein Access Token ein
3. Bei Erfolg wird das erhaltene Token angezeigt
4. Bei einem Fehler wird die Fehlermeldung des OAuth-Servers angezeigt

<Info>
  **Tipp:** Sie können die Verbindung auch testen, ohne den Anbieter zu speichern. So können Sie verschiedene Konfigurationen ausprobieren.
</Info>

## Häufige Fehler

| Fehler                   | Ursache                                               | Lösung                                                                                                            |
| ------------------------ | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Invalid key format**   | Private Key ist nicht im PEM-Format                   | Stellen Sie sicher, dass der Key mit `-----BEGIN RSA PRIVATE KEY-----` oder `-----BEGIN PRIVATE KEY-----` beginnt |
| **Token request failed** | Falsche Token URL oder Zugangsdaten                   | Überprüfen Sie Token URL, Issuer und Private Key                                                                  |
| **Invalid audience**     | Audience stimmt nicht mit dem erwarteten Wert überein | Prüfen Sie die Audience -- meist ist es die Token URL selbst                                                      |
| **Scope not permitted**  | Fehlende Berechtigungen                               | Stellen Sie sicher, dass der Service Account die benötigten Berechtigungen hat                                    |
| **{tenant} in URL**      | Platzhalter nicht ersetzt                             | Ersetzen Sie `{tenant}` durch Ihre tatsächliche Azure Tenant-ID                                                   |