JWT-Authentifizierung

Ü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

Ihr System fordert mit Client Credentials (Client-ID und Client Secret) ein Zugriffstoken vom IdP an.
Der IdP gibt ein signiertes JWT mit Claims wie iss (Issuer) und aud (Audience) zurück.
Ihr System übergibt das Token beim Aufruf der Corgea API als Bearer-Token im Authorization-Header.
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:

corgea login YOUR_JWT_TOKEN

Oder es über eine Umgebungsvariable festlegen:

export CORGEA_TOKEN="your-jwt-access-token"
corgea login

$env:CORGEA_TOKEN="your-jwt-access-token"
corgea login

JWT Auth in Corgea einrichten

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

JWT-Auth-Konfigurationsformular in Corgea hinzufügen

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.

Decodieren Sie vor dem Ausfüllen des Formulars ein Zugriffstoken Ihres IdP mit jwt.io und prüfen Sie die exakten Werte von iss, aud und appid/cid.

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

Eine Anwendung in Entra registrieren

Öffnen Sie im Azure-Portal Microsoft Entra ID → App registrations → New registration. Geben Sie der App einen aussagekräftigen Namen (z. B. corgea-cicd) und registrieren Sie sie.

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.

Eine API in Microsoft Entra bereitstellen

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

Client Secret erstellen

Öffnen Sie Certificates & secrets → New client secret. Geben Sie eine Beschreibung und ein Ablaufdatum an und klicken Sie auf Add.

Client Secret in Microsoft Entra hinzufügen

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

Zugriffstoken anfordern

Ihr System fordert ein Token von Entra über den Client-Credentials-Flow an:

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"

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"
  }

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

curl -H "Authorization: Bearer {access_token}" https://www.corgea.app/api/...

Invoke-RestMethod -Uri "https://www.corgea.app/api/..." `
  -Headers @{ Authorization = "Bearer {access_token}" }

Ersetzen Sie https://www.corgea.app durch https://your_instance.corgea.app, wenn Sie eine private Bereitstellung verwenden.

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.

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.

Importieren eines Curl-Befehls in Postman

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.

Anfordern eines Zugriffstokens in Postman mithilfe von Client-Anmeldeinformationen

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.

Aufrufen der Corgea-API mit einem Bearer-Token in Postman

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.

Token überprüfen

Verwenden Sie 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.

Decodieren eines JWT-Tokens auf jwt.io zur Überprüfung der iss- und aud-Ansprüche

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.

# 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

# 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

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.

Erste Schritte

Kernfunktionen

Integrationen

Werkzeuge & Hilfsprogramme

Versionshinweise

Vertrauen & Compliance

Authentifizierung

Übersicht

So funktioniert es

Verwendung von JWT mit Corgea CLI

JWT Auth in Corgea einrichten

Microsoft Entra ID-Einrichtung

Testen mit Postman

Token überprüfen

Fehlerbehebung

Netzwerkverbindungsprobleme

​Übersicht

​So funktioniert es

​Verwendung von JWT mit Corgea CLI

​JWT Auth in Corgea einrichten

​Microsoft Entra ID-Einrichtung

​Testen mit Postman

​Token überprüfen

​Fehlerbehebung

​Netzwerkverbindungsprobleme

Übersicht

So funktioniert es

Verwendung von JWT mit Corgea CLI

JWT Auth in Corgea einrichten

Microsoft Entra ID-Einrichtung

Testen mit Postman

Token überprüfen

Fehlerbehebung

Netzwerkverbindungsprobleme