> ## 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 providers (JWT)

> JWT OAuth authentication for external APIs -- Google, Microsoft, and TKP.

## What is a JWT OAuth provider?

A **JWT OAuth provider** lets your AI assistant authenticate automatically against external APIs. Instead of using static API keys, a signed JWT (JSON Web Token) is created and exchanged for a short-lived access token. Expired tokens are renewed automatically.

<Info>
  **Security:** All stored credentials (private keys, tokens) are stored encrypted and are only accessible to your account.
</Info>

**Typical use cases:**

* Google Cloud APIs (e.g. Google Calendar, Google Sheets)
* Microsoft Graph API (e.g. Outlook, Teams)
* TKP / soft-nrg workshop planning system

## Where do I find the OAuth providers?

1. Click your **Account** in the bottom left
2. Select **OAuth providers**

There you see a list of all configured OAuth providers and can create new ones.

## Where is the OAuth provider used?

### In the API tool

When creating or editing an **API tool**, you will find the dropdown **"Link OAuth provider (optional)"**. Here you can select a previously created OAuth provider. The AI assistant then automatically uses a valid access token for every API call and renews it on its own as soon as it expires.

Below the dropdown you will find the link **"+ Create new OAuth provider"**, which opens the OAuth provider management in a new tab.

### In the TKP integration

When configuring the **TKP integration** (workshop appointments), a JWT OAuth provider is required. Select the matching provider from the dropdown.

## Create a new JWT OAuth provider

1. Open the **OAuth providers** page
2. Click the dropdown **"Create new OAuth provider"**
3. Select **"JWT OAuth"**
4. Optional: choose a **Quick Start template** (Google, Microsoft, or TKP)
5. Fill in the remaining fields
6. Test the connection
7. Click **Save**

## Quick Start templates

When creating a new JWT OAuth provider, three preconfigured templates are available. They fill in most fields automatically -- you only need to enter your individual credentials.

| Quick Start   | Description                                    | What gets filled in?                                                        |
| ------------- | ---------------------------------------------- | --------------------------------------------------------------------------- |
| **Google**    | For Google Cloud APIs (Calendar, Sheets, etc.) | Token URL, algorithm, lifetime, audience, grant type                        |
| **Microsoft** | For Microsoft Graph / Azure AD                 | Token URL, algorithm, lifetime, audience, grant type, client assertion type |
| **TKP**       | For the soft-nrg workshop planning system      | Token URL, algorithm, lifetime, audience, scope, grant type                 |

<Info>
  **Note:** Quick Start templates are only available when creating new providers (not when editing). Sensitive data you have already entered (private key, issuer) is preserved when switching templates.
</Info>

## Form fields in detail

### Basic settings

| Field         | Description                                    | Required |
| ------------- | ---------------------------------------------- | -------- |
| **Name**      | Descriptive name (e.g. "Google Calendar Prod") | Yes      |
| **Token URL** | OAuth token endpoint URL (HTTPS only)          | Yes      |

### JWT signing

| Field                 | Description                                | Default  |
| --------------------- | ------------------------------------------ | -------- |
| **Algorithm**         | RS256, RS384, RS512, ES256, ES384, ES512   | RS256    |
| **JWT lifetime**      | Validity of the JWT in seconds             | 300      |
| **Key ID**            | Optional key ID for the JWT header ("kid") | --       |
| **Private key (PEM)** | Your RSA or ECDSA key in PEM format        | Required |

### JWT claims (payload)

| Field              | Description                                              | Required |
| ------------------ | -------------------------------------------------------- | -------- |
| **Issuer (iss)**   | Sender -- usually the client ID or service account email | Yes      |
| **Subject (sub)**  | Subject -- for Microsoft, the issuer is used when empty  | No       |
| **Audience (aud)** | Recipient -- usually the token URL                       | Yes      |
| **Scope**          | OAuth permissions, separated by spaces                   | No       |

### Response format

| Field                     | Description                              | Default             |
| ------------------------- | ---------------------------------------- | ------------------- |
| **Token field name**      | JSON field containing the access token   | access\_token       |
| **Expires-in field name** | JSON field containing the token validity | expires\_in         |
| **Grant type**            | OAuth 2.0 grant type                     | depends on template |

### Advanced options

| Field                          | Description                                                  |
| ------------------------------ | ------------------------------------------------------------ |
| **Header extras**              | Additional JWT header fields as JSON (e.g. `{"x5t":"..."}`)  |
| **Extra token request params** | Additional parameters for the token request as JSON          |
| **JWT assertion field name**   | Field name for the JWT assertion in the POST body            |
| **Client assertion type**      | Type of the client assertion (for Microsoft)                 |
| **Send scope in POST body**    | Required for certain client assertion flows (e.g. Microsoft) |

## Example: TKP workshop planning

<Tip>
  **Quick Start:** Click **TKP** -- most fields are filled in automatically.
</Tip>

**Automatically filled fields:**

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

**What you still need to enter:**

1. **Name** -- e.g. "TKP Werkstatt Prod"
2. **Private key** -- your RSA private key in PEM format (provided by soft-nrg)
3. **Key ID** -- your key ID from soft-nrg (if available)
4. **Issuer (iss)** -- your client ID from soft-nrg
5. **Subject (sub)** -- if specified by soft-nrg

**Usage:** Afterwards, link the created provider in the **TKP integration**.

## Example: Google Cloud API

<Tip>
  **Quick Start:** Click **Google** -- most fields are filled in automatically.
</Tip>

**Automatically filled fields:**

* **Token URL:** `https://oauth2.googleapis.com/token`
* **Algorithm:** RS256
* **JWT lifetime:** 3600 seconds (1 hour)
* **Audience:** `https://oauth2.googleapis.com/token`
* **Grant type:** `urn:ietf:params:oauth:grant-type:jwt-bearer`

**What you still need to enter:**

1. **Name** -- e.g. "Google Calendar Prod"
2. **Private key** -- from the Google Cloud service account JSON file (field `private_key`)
3. **Key ID** -- from the JSON file (field `private_key_id`), if available
4. **Issuer (iss)** -- the service account email (e.g. `mein-service@projekt.iam.gserviceaccount.com`)
5. **Subject (sub)** -- the email of the user on whose behalf the assistant acts (with domain-wide delegation)
6. **Scope** -- the required permissions, e.g.:
   * Google Calendar: `https://www.googleapis.com/auth/calendar`
   * Google Sheets: `https://www.googleapis.com/auth/spreadsheets`

**Usage:** Link the created provider in the **API tool** that calls the Google API.

## Example: Microsoft Graph API

<Tip>
  **Quick Start:** Click **Microsoft** -- most fields are filled in automatically.
</Tip>

**Automatically filled fields:**

* **Token URL:** `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token`
* **Algorithm:** RS256
* **JWT lifetime:** 600 seconds (10 minutes)
* **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`
* **Send scope in POST body:** Enabled

<Warning>
  **Important:** Replace `{tenant}` in the token URL and audience with your Azure tenant ID!
</Warning>

**What you still need to enter:**

1. **Name** -- e.g. "Microsoft Graph Prod"
2. **Token URL** -- replace `{tenant}` with your Azure tenant ID
3. **Audience** -- replace `{tenant}` with your Azure tenant ID
4. **Private key** -- your certificate's private key in PEM format
5. **Key ID** -- the thumbprint of your certificate
6. **Issuer (iss)** -- your Azure application (client) ID
7. **Subject (sub)** -- your Azure application (client) ID (identical to the issuer for Microsoft)
8. **Scope** -- e.g. `https://graph.microsoft.com/.default`
9. **Header extras** (optional) -- `{"x5t":"YOUR_CERTIFICATE_THUMBPRINT"}` (hex values are automatically converted to Base64url)

**Usage:** Link the created provider in the **API tool** that calls the Microsoft Graph API.

## Test the connection

After filling in the form, you can test the connection **before** saving the provider:

1. Click **Test connection**
2. The system creates a JWT and exchanges it for an access token
3. On success, the received token is displayed
4. On failure, the OAuth server's error message is displayed

<Info>
  **Tip:** You can also test the connection without saving the provider. This lets you try out different configurations.
</Info>

## Common errors

| Error                    | Cause                                      | Solution                                                                                         |
| ------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| **Invalid key format**   | Private key is not in PEM format           | Make sure the key starts with `-----BEGIN RSA PRIVATE KEY-----` or `-----BEGIN PRIVATE KEY-----` |
| **Token request failed** | Wrong token URL or credentials             | Check the token URL, issuer, and private key                                                     |
| **Invalid audience**     | Audience does not match the expected value | Check the audience -- it is usually the token URL itself                                         |
| **Scope not permitted**  | Missing permissions                        | Make sure the service account has the required permissions                                       |
| **{tenant} in URL**      | Placeholder not replaced                   | Replace `{tenant}` with your actual Azure tenant ID                                              |