> ## Documentation Index
> Fetch the complete documentation index at: https://app.miyon.ai/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.

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

**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 |

> [!NOTE]
>
> **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.

## 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.

**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.

**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.

**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!

**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

> [!NOTE]
>
> **Tipp:** Sie können die Verbindung auch testen, ohne den Anbieter zu speichern. So können Sie verschiedene Konfigurationen ausprobieren.

## 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.