APP Authentifizierung OIDC

Mit der neuen OpenID Connect (OIDC) / OAuth 2.0‑Authentifizierung können Partner ihre eigenen Anwendungen sicher gegen Evalanche anbinden. In diesem Artikel erfahren Sie, wie Sie eine Applikation anlegen, die erhaltenen Zugangsdaten korrekt verwenden und wie der grundlegende OIDC/OAuth2‑Ablauf funktioniert.

Basisinformationen zu OpenID Connect (OIDC):
https://openid.net/specs/openid-connect-core-1_0.html

Voraussetzungen

• Sie verfügen über einen Evalanche‑Account mit dem Recht „Partner Apps" zur Anlage von Applikationen.
• Sie haben Zugriff auf die Konfiguration Ihrer Partner‑Applikation (z.B. Backend, IdP‑Konfiguration oder „OAuth/OIDC Settings").
• Ihnen sind die Redirect‑URLs Ihrer Anwendung bekannt, auf die nach erfolgreichem Login zurückgeleitet werden soll.

Applikation in Evalanche anlegen

• Navigieren Sie in der neuen Evalanche‑GUI zu Einstellungen → Applikationen und Zugänge.
• Legen Sie eine neue Applikation vom Typ Authentifizierung (OIDC) an.
• Vergeben Sie einen Namen, damit Sie die Applikation später eindeutig zuordnen können.
• Tragen Sie alle Redirect‑URLs Ihrer Anwendung ein, auf die Evalanche nach erfolgreicher Authentifizierung zurückleiten darf.
  • Beispiel: https://partner-app.example.com/oauth/callback
  • Mehrere Redirect‑URLs sind möglich, sofern sie exakt konfiguriert sind.
• Speichern Sie die Applikation.

Nach dem Speichern erzeugt Evalanche automatisch die technischen Zugangsdaten für Ihre Applikation.

Client ID und Client Secret

Nach Anlage der Applikation werden Ihnen im UI einmalig die folgenden Daten angezeigt:

• Client ID
• Client Secret

Diese Daten werden nur ein einziges Mal angezeigt. Sie müssen:

• die Client ID und das Client Secret vollständig kopieren,
• sie sicher speichern (z.B. in einem Secrets‑Manager, verschlüsselten Config‑Store oder Passwort‑Safe),
• sie vertraulich behandeln und nicht öffentlich zugänglich machen (z.B. nicht im Frontend‑Code einer Browser‑App im Klartext einbinden).

Falls Sie das Client Secret verlieren oder vergessen, müssen Sie in Evalanche ein neues Secret generieren bzw. eine neue Applikation anlegen. Ein späteres erneutes Anzeigen des ursprünglichen Secrets ist aus Sicherheitsgründen nicht möglich.

Initiale Autorisierung

Der Autorisierungsablauf folgt dem standardmäßigen OAuth 2.0 Authorization Code Flow:

Schritt 1: Benutzer zur Autorisierung weiterleiten

Leiten Sie den Benutzer auf die folgende URL weiter, damit er sich bei Evalanche anmeldet und Ihrer Applikation den Zugriff gewährt:

GET https://<ihre-evalanche-domain>/auth/oidc/authorize?state=<STATE>&client_id=<CLIENT-ID>&redirect_uri=<REDIRECT-URI>

Parameter:

• state – Ein zufällig generierter, eindeutiger Wert, den Sie zur Absicherung gegen CSRF‑Angriffe verwenden. Prüfen Sie nach dem Callback, ob der zurückgegebene state-Wert mit dem gesendeten übereinstimmt.
• client_id – Die Client ID Ihrer in Evalanche angelegten Applikation.
• redirect_uri – Die Redirect‑URL, auf die nach erfolgreicher Authentifizierung zurückgeleitet wird. Muss exakt mit einer der in Evalanche hinterlegten Redirect‑URLs übereinstimmen.

Nach erfolgreicher Anmeldung leitet Evalanche den Benutzer an die angegebene redirect_uri weiter und übergibt dabei einen Authorization Code als Query‑Parameter.

Schritt 2: Authorization Code gegen Token tauschen

Senden Sie den erhaltenen Authorization Code per POST‑Request an den Token‑Endpunkt, um ein ID‑Token zu erhalten:

POST https://<ihre-evalanche-domain>/api/auth/v1/oidc/token
Accept: application/json
Content-Type: application/json

Request Body (JSON):

{
    "code": "<AUTH-CODE>",
    "redirect_uri": "<REDIRECT-URI>",
    "client_id": "<CLIENT-ID>",
    "client_secret": "<CLIENT-SECRET>",
    "grant_type": "authorization_code"
}

Parameter:

• code – Der im Callback erhaltene Authorization Code.
• redirect_uri – Muss identisch zur redirect_uri aus Schritt 1 sein.
• client_id – Ihre Client ID.
• client_secret – Ihr Client Secret.
• grant_type – Immer authorization_code.

Wichtig: Der Authorization Code ist einmalig verwendbar und nur 60 Sekunden gültig. Der Token‑Tausch muss daher unmittelbar nach Erhalt des Codes erfolgen.

Response (JSON):

{
    "id_token": "<JWT>",
    "token_type": "Bearer",
    "access_token": "",
    "expires_in": <Sekunden>
}

Felder:

• id_token – Ein signiertes JWT, das die Identitätsinformationen des Benutzers enthält (siehe Abschnitt „Übergebene Daten bei erfolgreicher Authentifizierung").
• token_type – Immer Bearer.
• access_token – Derzeit nicht befüllt.
• expires_in – Gültigkeitsdauer des Tokens in Sekunden.

Übergebene Daten bei erfolgreicher Authentifizierung

Bei erfolgreicher Authentifizierung werden folgende Informationen im ID‑Token (Claims) übergeben:

Inhalt des ID‑Token (Claims):

• iss – URI (Hostname), die für den Aufruf genutzt wurde
• aud – Liste, beinhaltet mindestens die Client‑ID
• sub – Name des Users
• iat – Datum der Erzeugung des ID‑Tokens
• exp – Expiry‑Date des ID‑Tokens
• email – E‑Mail‑Adresse des Users
• eva-user-id – Interne ID des Users

Integration der Applikation in Evalanche (iFrame / AppSwitch)

Um eine nahtlose User Experience zu schaffen, kann die angelegte Applikation direkt in Evalanche eingebunden werden:

Einbindung im Bereich „APPs" per iFrame

• Ihre Anwendung wird innerhalb von Evalanche im iFrame dargestellt.

Einbindung im AppSwitch als Icon mit Link

• Ihre Anwendung ist über ein Icon im AppSwitch erreichbar, der Benutzer gelangt per Klick direkt in Ihre App.

Die Konfiguration der Einbindung erfolgt im Bereich „PartnerApps / Eigene App". Dort können Sie definieren, ob und wie Ihre Applikation im APP‑Bereich und im AppSwitch sichtbar sein soll. 

Verantwortlichkeit für Benutzer‑Berechtigungen

Evalanche stellt die Authentifizierung bereit, also den sicheren Nachweis, welcher Benutzer sich angemeldet hat. Die Autorisierung innerhalb Ihrer eigenen Applikation liegt vollständig in Ihrer Verantwortung als Partner.

Das bedeutet insbesondere:

• Sie entscheiden, welche Rollen, Rechte oder Funktionen ein Benutzer in Ihrer Applikation erhält.
• Sie werten hierzu die vom OIDC‑Provider gelieferten Informationen (z.B. User‑ID, E‑Mail, Claims, Gruppen/Rollen‑Claims, falls vorhanden) aus.
• Evalanche selbst trifft keine Berechtigungsentscheidungen in Ihrer Applikation.

Sicherheitsempfehlungen

• Speichern Sie das Client Secret niemals im Frontend oder in öffentlich zugänglichen Repositories.
• Rotieren Sie Secrets regelmäßig, insbesondere bei Verdacht auf Kompromittierung.
• Validieren Sie stets die Felder iss, aud, exp und ggf. nonce des ID‑Tokens.
• Verwenden Sie HTTPS für alle Kommunikationswege (Redirect‑URLs, Token‑Requests, API‑Zugriffe).

Fehlerbehebung

Häufige Fehlerursachen:

• „redirect_uri mismatch"
  Die angegebene redirect_uri stimmt nicht exakt mit der in Evalanche hinterlegten URL überein.
• „invalid_client" oder „unauthorized_client"
  Client ID oder Client Secret sind falsch oder gehören nicht zu der aufgerufenen Applikation.
• „invalid_grant"
  Der Authorization Code ist abgelaufen, wurde bereits verwendet oder redirect_uri passt nicht zur ursprünglichen Anfrage.
• Ungültige Token‑Signatur
  Überprüfen Sie, ob Ihr System den korrekten öffentlichen Schlüssel (JWKS) des Evalanche‑Issuers verwendet.