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

# JWT-Authentifizierung

> API-Requests für System-zu-System-Integrationen mit JWT-Bearer-Tokens Ihres Identity Providers authentifizieren.

## Übersicht

Mit JWT-Authentifizierung rufen Sie die Corgea API über Bearer-Tokens auf, die Ihr Identity Provider (IdP) wie Microsoft Entra ID oder Okta direkt ausstellt. Ein benutzerspezifisches Corgea-API-Token ist dann nicht erforderlich.

Dieser Ansatz wird für **System-zu-System-Integrationen** wie CI/CD-Pipelines, automatisierte Scanner und interne Tools empfohlen:

* Tokens sind an einen Service Principal oder eine App-Registrierung statt an ein bestimmtes Benutzerkonto gebunden
* Laufzeit und Scope des Tokens werden vom IdP gesteuert
* Tokens lassen sich zentral über den IdP widerrufen, ohne Änderungen in Corgea

Ein Corgea-API-Token ist stets an einen einzelnen Benutzer gebunden. Verlässt die Person das Unternehmen oder wird ihr Konto deaktiviert, funktionieren Automatisierungen mit diesem Token nicht mehr. JWT Auth entkoppelt die Authentifizierung vollständig von Benutzerkonten.

## So funktioniert es

1. Ihr System fordert mit Client Credentials (Client-ID und Client Secret) ein Zugriffstoken vom IdP an.
2. Der IdP gibt ein signiertes JWT mit Claims wie `iss` (Issuer) und `aud` (Audience) zurück.
3. Ihr System übergibt das Token beim Aufruf der Corgea API als `Bearer`-Token im `Authorization`-Header.
4. Corgea validiert die Token-Signatur anhand der öffentlichen Schlüssel des IdP und vergleicht die Claims `iss`, `aud` und `appid`/`cid` mit der registrierten Konfiguration.

## Verwendung von JWT mit Corgea CLI

Sie können ein JWT-Access-Token direkt mit dem CLI-Login-Flow verwenden:

```bash theme={null}
corgea login YOUR_JWT_TOKEN
```

Oder es über eine Umgebungsvariable festlegen:

<CodeGroup>
  ```bash macOS / Linux theme={null}
  export CORGEA_TOKEN="your-jwt-access-token"
  corgea login
  ```

  ```powershell Windows theme={null}
  $env:CORGEA_TOKEN="your-jwt-access-token"
  corgea login
  ```
</CodeGroup>

## JWT Auth in Corgea einrichten

Öffnen Sie **Settings → Integrations** und klicken Sie im Abschnitt **JWT Auth** auf **+ Add**.

<Card>
  <img src="https://mintcdn.com/corgea/shid6yjMRFa2jrlq/images/jwt_token/corgae_jwt_token_form.png?fit=max&auto=format&n=shid6yjMRFa2jrlq&q=85&s=4e2279f885450dc9756704ae02ef498a" style={{ borderRadius: '0.5rem' }} alt="JWT-Auth-Konfigurationsformular in Corgea hinzufügen" width="2796" height="2116" data-path="images/jwt_token/corgae_jwt_token_form.png" />
</Card>

Füllen Sie die folgenden Felder aus:

| Feld                        | Beschreibung                                                                              |
| --------------------------- | ----------------------------------------------------------------------------------------- |
| **Name**                    | Ein beschreibendes Label für diese Konfiguration (z. B. `Entra CICD Pipeline`).           |
| **Issuer**                  | URL des Token-Ausstellers; muss dem Claim `iss` im Zugriffstoken entsprechen.             |
| **Audience**                | Muss dem Claim `aud` im Zugriffstoken entsprechen.                                        |
| **Allowed Application IDs** | Eine Client-ID pro Zeile; legt fest, welche Anwendung diese Konfiguration verwenden darf. |

<Info>
  Decodieren Sie vor dem Ausfüllen des Formulars ein Zugriffstoken Ihres IdP mit [jwt.io](https://jwt.io) und prüfen Sie die exakten Werte von `iss`, `aud` und `appid`/`cid`.
</Info>

**Providerspezifische Werte:**

* **Entra ID Issuer**: `https://sts.windows.net/{your-tenant-id}/`
* **Entra ID Audience**: Application ID URI Ihrer App (z. B. `api://{client_id}`), festgelegt über **Expose an API** in Entra
* **Okta Issuer**: `https://{domain}.okta.com/oauth2/default`
* **Okta Audience**: `api://default` (oder die Audience des benutzerdefinierten Authorization Servers)

## Microsoft Entra ID-Einrichtung

<Steps>
  <Step title="Eine Anwendung in Entra registrieren">
    Öffnen Sie im [Azure-Portal](https://portal.azure.com) **Microsoft Entra ID → App registrations → New registration**. Geben Sie der App einen aussagekräftigen Namen (z. B. `corgea-cicd`) und registrieren Sie sie.
  </Step>

  <Step title="API verfügbar machen und Application ID URI festlegen">
    Öffnen Sie in der App-Registrierung **Expose an API**. Legen Sie die **Application ID URI** fest oder bestätigen Sie sie. Sie wird zum Claim `aud` in den für diese App ausgestellten Tokens.

    <Card>
      <img src="https://mintcdn.com/corgea/shid6yjMRFa2jrlq/images/jwt_token/entra_expose_an_api.png?fit=max&auto=format&n=shid6yjMRFa2jrlq&q=85&s=d04b83470b69fca5190511bef80e3129" style={{ borderRadius: '0.5rem' }} alt="Eine API in Microsoft Entra bereitstellen" width="6054" height="2320" data-path="images/jwt_token/entra_expose_an_api.png" />
    </Card>

    Kopieren Sie die Application ID URI (z. B. `api://5d63c8f0-c9a8-4195-90ee-a9e27e4510b8`). Tragen Sie sie in Corgea als **Audience** ein.
  </Step>

  <Step title="Client Secret erstellen">
    Öffnen Sie **Certificates & secrets → New client secret**. Geben Sie eine Beschreibung und ein Ablaufdatum an und klicken Sie auf **Add**.

    <Card>
      <img src="https://mintcdn.com/corgea/shid6yjMRFa2jrlq/images/jwt_token/entra_client_secret.png?fit=max&auto=format&n=shid6yjMRFa2jrlq&q=85&s=e09e3cdc9aed42edd27ba14d6c294a0d" style={{ borderRadius: '0.5rem' }} alt="Client Secret in Microsoft Entra hinzufügen" width="5798" height="2372" data-path="images/jwt_token/entra_client_secret.png" />
    </Card>

    Kopieren Sie den **Value** des Secrets sofort; er wird nur einmal angezeigt. Speichern Sie ihn sicher, beispielsweise im Secret Store Ihrer CI/CD-Umgebung.
  </Step>

  <Step title="Zugriffstoken anfordern">
    Ihr System fordert ein Token von Entra über den Client-Credentials-Flow an:

    <CodeGroup>
      ```bash macOS / Linux theme={null}
      curl -X POST \
        https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token \
        -d "grant_type=client_credentials" \
        -d "client_id={client-id}" \
        -d "client_secret={client-secret}" \
        -d "scope=api://{client-id}/.default"
      ```

      ```powershell Windows theme={null}
      Invoke-RestMethod -Method Post `
        -Uri "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token" `
        -Body @{
          grant_type    = "client_credentials"
          client_id     = "{client-id}"
          client_secret = "{client-secret}"
          scope         = "api://{client-id}/.default"
        }
      ```
    </CodeGroup>

    Die Response enthält ein `access_token`. Übergeben Sie es beim Aufruf von Corgea als Bearer-Token:

    <CodeGroup>
      ```bash macOS / Linux theme={null}
      curl -H "Authorization: Bearer {access_token}" https://www.corgea.app/api/...
      ```

      ```powershell Windows theme={null}
      Invoke-RestMethod -Uri "https://www.corgea.app/api/..." `
        -Headers @{ Authorization = "Bearer {access_token}" }
      ```
    </CodeGroup>

    <Note>
      Ersetzen Sie `https://www.corgea.app` durch `https://your_instance.corgea.app`, wenn Sie eine private Bereitstellung verwenden.
    </Note>
  </Step>

  <Step title="Konfiguration in Corgea registrieren">
    Geben Sie im Corgea-Formular **Add JWT Auth Configuration** Folgendes ein:

    * **Issuer**: `https://sts.windows.net/{your-tenant-id}/`
    * **Audience**: die Application-ID-URI aus Schritt 2 (z. B. `api://5d63c8f0-...`)
    * **Allowed Application IDs**: die **Application (client) ID** Ihrer App-Registrierung

    Klicken Sie zum Speichern auf **Add**.
  </Step>
</Steps>

## Testen mit Postman

Wenn Sie eine GUI statt curl bevorzugen, können Sie Token-Request und API-Aufruf direkt in Postman testen.

**Einen curl-Befehl importieren**

Postman kann jeden der obigen curl-Befehle in einen Request umwandeln. Klicken Sie oben links auf **Import**, fügen Sie den curl-Befehl ein und Postman füllt Methode, URL, Header und Body automatisch aus.

<Card>
  <img src="https://mintcdn.com/corgea/9RMZY-Ts5g1RCFSA/images/jwt_token/postman_import_curl.png?fit=max&auto=format&n=9RMZY-Ts5g1RCFSA&q=85&s=d634e6065afdb582aa09a69b9a21ff5f" style={{ borderRadius: '0.5rem' }} alt="Importieren eines Curl-Befehls in Postman" width="2026" height="1202" data-path="images/jwt_token/postman_import_curl.png" />
</Card>

**Ein Zugriffstoken anfordern**

Füllen Sie Ihre `tenant-id`, `client_id`, `client_secret` und `scope` in die Body-Felder ein und senden Sie dann die Anfrage. Kopieren Sie den `access_token`-Wert aus der Antwort.

<Card>
  <img src="https://mintcdn.com/corgea/9RMZY-Ts5g1RCFSA/images/jwt_token/postman_request_access.png?fit=max&auto=format&n=9RMZY-Ts5g1RCFSA&q=85&s=eb94f562884a32bb361dbd23206c03b7" style={{ borderRadius: '0.5rem' }} alt="Anfordern eines Zugriffstokens in Postman mithilfe von Client-Anmeldeinformationen" width="2400" height="2066" data-path="images/jwt_token/postman_request_access.png" />
</Card>

**Corgea API mit dem Token aufrufen**

Erstellen Sie einen Request an den Corgea-Endpunkt. Wählen Sie im Tab **Authorization** den Typ **Bearer Token** und fügen Sie das `access_token` ein.

<Card>
  <img src="https://mintcdn.com/corgea/9RMZY-Ts5g1RCFSA/images/jwt_token/postman_call_api_with_token.png?fit=max&auto=format&n=9RMZY-Ts5g1RCFSA&q=85&s=66c68bafb415fa42282f6225d50bcd9f" style={{ borderRadius: '0.5rem' }} alt="Aufrufen der Corgea-API mit einem Bearer-Token in Postman" width="2522" height="2462" data-path="images/jwt_token/postman_call_api_with_token.png" />
</Card>

<Note>
  Wenn Ihr Unternehmen ausgehenden Netzwerkzugriff einschränkt, müssen Sie gegebenenfalls einen Proxy konfigurieren. Öffnen Sie in Postman **Settings → Proxy** und fügen Sie den Unternehmensproxy hinzu. Setzen Sie für curl die Umgebungsvariable `HTTPS_PROXY` oder übergeben Sie `--proxy https://your-proxy:port`.
</Note>

## Token überprüfen

Verwenden Sie [jwt.io](https://jwt.io), um ein Zugriffstoken zu dekodieren, bevor Sie Corgea konfigurieren. Fügen Sie Ihr Token in den Debugger ein und überprüfen Sie die **Decoded Payload**, um die Werte von `iss`, `aud` und `appid` zu bestätigen.

<Card>
  <img src="https://mintcdn.com/corgea/shid6yjMRFa2jrlq/images/jwt_token/jwt_io.png?fit=max&auto=format&n=shid6yjMRFa2jrlq&q=85&s=d00c729ec30d74b31bd448b410e67ca0" style={{ borderRadius: '0.5rem' }} alt="Decodieren eines JWT-Tokens auf jwt.io zur Überprüfung der iss- und aud-Ansprüche" width="2776" height="2326" data-path="images/jwt_token/jwt_io.png" />
</Card>

Die hervorgehobenen Felder `aud` und `iss` werden von Corgea bei der Validierung eingehender Requests exakt geprüft.

## Fehlerbehebung

* **401 Unauthorized**: Decodieren Sie Ihr Token mit jwt.io und prüfen Sie, ob `iss`, `aud` und `appid` exakt mit den Werten in Ihrer Corgea-JWT-Auth-Konfiguration übereinstimmen.
* **Token nach Rotation abgelehnt**: Stellen Sie nach der Rotation des Client Secrets sicher, dass das neue Secret in Ihrer CI/CD-Umgebung hinterlegt ist. Die Corgea-Konfiguration muss nicht geändert werden, da sie Token-Claims und nicht das Secret validiert.
* **Mehrere Umgebungen**: Erstellen Sie eine separate JWT Auth-Konfiguration in Corgea für jede Anwendung oder Umgebung (z. B. Staging vs. Produktion) unter Verwendung verschiedener App-Registrierungen mit unterschiedlichen Client-IDs.

### Netzwerkverbindungsprobleme

Wenn die Token-Anfrage oder der API-Aufruf mit einem Verbindungsfehler fehlschlägt, verwenden Sie diese Befehle, um zu prüfen, ob eine Firewall oder ein Proxy den Datenverkehr blockiert.

<CodeGroup>
  ```bash macOS / Linux theme={null}
  # Check DNS resolution
  nslookup login.microsoftonline.com
  nslookup www.corgea.app

  # Check TCP connectivity on port 443
  nc -zv login.microsoftonline.com 443
  nc -zv www.corgea.app 443

  # Trace the network path
  traceroute login.microsoftonline.com

  # Test with verbose curl output (shows TLS handshake and redirect chain)
  curl -v https://login.microsoftonline.com

  # Test through a proxy if required
  curl -v --proxy https://your-proxy:port https://login.microsoftonline.com
  ```

  ```powershell Windows theme={null}
  # Check DNS resolution
  Resolve-DnsName login.microsoftonline.com
  Resolve-DnsName www.corgea.app

  # Check TCP connectivity on port 443
  Test-NetConnection -ComputerName login.microsoftonline.com -Port 443
  Test-NetConnection -ComputerName www.corgea.app -Port 443

  # Trace the network path
  tracert login.microsoftonline.com

  # Test with verbose curl output
  curl.exe -v https://login.microsoftonline.com

  # Test through a proxy if required
  curl.exe -v --proxy https://your-proxy:port https://login.microsoftonline.com
  ```
</CodeGroup>

Wenn der TCP-Verbindungstest fehlschlägt oder Traceroute an einem internen Hop stoppt, wenden Sie sich an Ihr Netzwerk- oder Sicherheitsteam, um ausgehendes HTTPS (Port 443) zu `login.microsoftonline.com` und `www.corgea.app` zuzulassen.