Air-Gapped Devin: SSO mit Ihrem IdP

Diese Dokumentation gilt für die föderalen Deployments von Devin. Zurück zur Devin-Dokumentation

Standardmäßig wird der Zugriff auf den air-gapped Build ausschließlich über die Lizenzdatei gesteuert. Zusätzlich können Sie festlegen, dass sich jeder Nutzer bei Ihrem eigenen OIDC-Identitätsanbieter anmelden muss. SSO (Single Sign-On) bildet dabei eine zusätzliche Schicht über der Lizenz: Die Lizenz ist weiterhin erforderlich, und die Anmeldung erfolgt über den von Ihnen konfigurierten Issuer.

Auth-Datei erstellen


Standardpfad	`/etc/devin/auth.json`
Standardpfad (Windows)	`C:\ProgramData\Devin\auth.json`
Überschreibung	`DEVIN_AUTH_FILE=<path>`

Die Datei legt genau einen Modus fest. Ist die Datei nicht vorhanden, verhält sich das Produkt so, als enthielte sie "mode": "license".

/etc/devin/auth.json

{
  "schema_version": 0,
  "mode": "sso",
  "issuer": "https://sso.example.com",
  "client_id": "devin-cli",
  "scopes": ["openid", "profile", "email"],
  "groups_claim": "groups",
  "required_group": "devin-users",
  "additional_endpoint_hosts": []
}

Feld	Erforderlich	Bedeutung
`schema_version`	ja	Muss `0` sein.
`mode`	ja	`"sso"`, um eine Anmeldung vorauszusetzen, oder `"license"` für reinen Lizenzzugriff (Standard, wenn keine Datei vorhanden ist).
`issuer`	ja (sso)	Die OIDC-Issuer-URL. Muss mit `https://` beginnen (einfaches `http://` wird nur für Loopback-Hosts akzeptiert) und darf weder Query-String noch Fragment oder eingebettete Anmeldedaten enthalten. Die automatische Erkennung erfolgt über `<issuer>/.well-known/openid-configuration`.
`client_id`	ja (sso)	Der Client, den Sie beim IdP registrieren.
`scopes`	nein	Standardwert ist `openid profile email`. Falls gesetzt, muss `openid` enthalten sein. `offline_access` wird automatisch angefordert, wenn der IdP es unterstützt, damit ein Aktualisierungstoken ausgestellt wird.
`groups_claim`	nein	ID-Token-Claim, der die Gruppenmitgliedschaft enthält. Standardwert ist `groups`.
`required_group`	nein	Falls gesetzt, wird die Anmeldung nur zugelassen, wenn dieser Wert im Gruppen-Claim enthalten ist.
`additional_endpoint_hosts`	nein	Zusätzliche Hosts, für die das Discovery-Dokument des IdP Endpunkte angeben darf. Lassen Sie dieses Feld leer, sofern Sie es nicht benötigen; siehe Discovered endpoints must stay on the issuer.

Unbekannte Felder werden abgelehnt. Im Modus license sind nur schema_version und mode zulässig.

Wenn Ihr IdP ein Zertifikat einer privaten CA verwendet, setzen Sie DEVIN_CA_BUNDLE auf ein PEM-Paket, damit die CLI diesem Zertifikat vertraut; siehe Netzwerk und Zertifikate.

Client bei Ihrem IdP registrieren

Die CLI führt den OIDC-Authorization-Code-Flow mit PKCE (S256) als öffentlicher Client aus; ein Client-Secret gibt es nicht. Der Client, den Sie registrieren, muss folgende Anforderungen erfüllen:

Ein öffentlicher Client (ohne Client-Secret) mit der ID, die Sie in client_id angeben, zum Beispiel devin-cli, mit aktiviertem Authorization-Code-Grant und der PKCE-Methode S256.
http://127.0.0.1/callback muss als gültige Weiterleitungs-URI registriert sein. Für den Browser-Flow lauscht die CLI auf einem zufälligen Loopback-Port (http://127.0.0.1:<port>/callback), für den manuellen Flow verwendet sie die feste Adresse http://127.0.0.1/callback. Gemäß RFC 8252 sollte der IdP den Loopback-Port ignorieren; falls Ihr IdP dies nicht tut, registrieren Sie eine passende Wildcard.
Wenn Sie required_group verwenden möchten, muss das ID-Token den in groups_claim angegebenen Claim für die Gruppenmitgliedschaft enthalten (standardmäßig groups).
Der IdP muss beim Refresh ein ID-Token zurückgeben (was die meisten tun, wenn der Geltungsbereich openid gewährt wurde), und die Gültigkeitsdauer des ID-Tokens für diesen Client muss kurz sein. Die Gründe dafür finden Sie unter Wie sich ein Entzug auswirkt.

Melden Sie sich über ein Terminal auf der Workstation an:

devin auth login

Opening your browser to sign in with your identity provider...
If the browser does not open, visit:

  https://sso.example.com/authorize?client_id=devin-cli&...

(Use `devin auth login --force-manual-token-flow` on headless machines.)
Logged in as jsmith via https://sso.example.com.
Token expires at 2026-03-02 15:04:05 UTC.

Verwenden Sie auf einem Host ohne grafische Oberfläche oder über SSH den manuellen Flow. Die CLI gibt eine URL aus, die Sie in einem Browser auf einer beliebigen Maschine öffnen. Nach der Anmeldung wird der Browser auf eine 127.0.0.1-URL weitergeleitet, die sich nicht laden lässt. Kopieren Sie diese vollständige URL (einschließlich der Query-Parameter) und fügen Sie sie anschließend im Terminal ein.

devin auth login --force-manual-token-flow

Open this URL in a browser (on any machine) and sign in:

  https://sso.example.com/authorize?client_id=devin-cli&...

After signing in, the browser is redirected to a 127.0.0.1 URL that will not load — copy that full URL (including its query parameters) and paste it here.
Paste the full redirect URL:

Devin Desktop verwendet über den mitgelieferten Agent dieselbe Anmeldung; Nutzer, die nicht angemeldet sind, werden aufgefordert, sich in den Devin-Settings anzumelden, bevor sie mit der Arbeit beginnen.

Status prüfen und abmelden

devin auth status

Auth mode: SSO (issuer: https://sso.example.com)
Status: logged in
User: jsmith
Subject: 6f1c2a0e-...
Groups: devin-users
Token expires at 2026-03-02 15:04:05 UTC.

Wenn die zwischengespeicherte Anmeldung fehlt oder nicht mehr aktualisiert werden kann, lautet die Ausgabe Status: not logged in (<reason>), gefolgt von Run \devin auth login` to sign in.`

devin auth logout

Logged out: local SSO tokens deleted.

Die Abmeldung erfolgt ausschließlich lokal: Dabei wird nur der token-Cache gelöscht, der IdP wird nicht kontaktiert.

Was die CLI validiert

Das ID-Token wird lokal validiert: die Signatur anhand des JWKS des IdP, iss, aud, der Ablaufzeitpunkt (mit einer Toleranz von 120 Sekunden für Uhrenabweichungen), die Login-nonce sowie die Gruppenprüfung. Das ID-Token und das Aktualisierungstoken werden im lokalen Anmeldedatenspeicher mit Berechtigungen ausschließlich für den Eigentümer (0600) zwischengespeichert und im Hintergrund über den IdP aktualisiert. Wenn SSO konfiguriert ist, keine gültige Anmeldung vorliegt und auch die Aktualisierung im Hintergrund fehlschlägt, bricht die CLI beim Start mit einer Fehlermeldung ab, die den Nutzer auffordert, devin auth login auszuführen. Die CLI folgt grundsätzlich keinen HTTP-Weiterleitungen des IdP: Liefert der Discovery-, JWKS- oder Token-Endpunkt einen 3xx-Status, schlägt die Anmeldung mit einer Fehlermeldung fehl, die den betreffenden Endpunkt nennt. issuer muss daher auf die URLs verweisen, die der IdP tatsächlich bereitstellt.

Per automatischer Erkennung ermittelte Endpunkte müssen auf dem Issuer liegen

Die per automatischer Erkennung ermittelten Werte authorization_endpoint, token_endpoint und jwks_uri müssen dasselbe Schema, denselben Host und denselben Port wie issuer haben (Standard-Ports gelten als gleichwertig). Ein Endpunkt auf einem anderen Host wird abgelehnt, und die Anmeldung schlägt mit einer Fehlermeldung wie dieser fehl:

IdP discovery document advertises jwks_uri 'https://keycloak.corp.internal:8443/realms/devin/protocol/openid-connect/certs'
on host 'keycloak.corp.internal:8443', which is not the configured issuer's host 'sso.corp.example:443';
refusing to trust it. If this IdP really serves that endpoint from a different host,
add "keycloak.corp.internal" to `sso.additional_endpoint_hosts` in the auth file

Manche IdP-Topologien stellen Endpunkte berechtigterweise über mehr als einen Host bereit. Der typische On-Premises-Fall ist Keycloak mit hostname-backchannel-dynamic=true: Hier werden token_endpoint und jwks_uri auf den internen hostname umgeschrieben, über den die CLI die Verbindung hergestellt hat. Fügen Sie den zusätzlichen Host nur dann hinzu, wenn Sie anhand der Konfiguration des IdP selbst bestätigt haben, dass er beabsichtigt ist:

"additional_endpoint_hosts": ["keycloak.corp.internal"]

Einträge haben die Form host (beliebiger Port) oder host:port und werden ohne Berücksichtigung der Groß-/Kleinschreibung abgeglichen. Es gibt keine Platzhalter und keine Möglichkeit, die Prüfung zu deaktivieren. Die Positivliste lockert die TLS-Anforderungen nie: Ein http://-Endpunkt wird unter einem https://-Issuer weiterhin abgelehnt. Fügen Sie einen Host nicht nur deshalb hinzu, weil er in einer Fehlermeldung bei der Anmeldung genannt wird – der Fehler zeigt, dass die Prüfung funktioniert.

Wie sich ein Entzug auswirkt

Die Gruppenprüfung erfolgt anhand des zwischengespeicherten ID-Tokens. Wenn Sie einen Nutzer beim IdP aus required_group entfernen (oder den Nutzer deaktivieren), greift dies daher erst bei der nächsten Token-Aktualisierung – spätestens, wenn das aktuelle ID-Token abläuft, zuzüglich einer Toleranz von 120 Sekunden für Zeitabweichungen. Wählen Sie für diesen Client eine kurze Gültigkeitsdauer des ID-Tokens, wenn ein schneller Entzug wichtig ist. Enthält eine Aktualisierungsantwort kein neues ID-Token, wird weiterhin das zwischengespeicherte ID-Token verwendet, allerdings höchstens 24 Stunden über dessen exp hinaus. Danach muss sich der Nutzer erneut anmelden, selbst wenn der IdP das Aktualisierungstoken noch akzeptiert.

Erneute Validierung in laufenden Sitzungen

Während Devin Desktop (oder ein anderer Client des mitgelieferten Agents) läuft, prüft der Agent die Anmeldung alle 60 Sekunden erneut und erzwingt mindestens alle 15 Minuten eine Token-Aktualisierung beim IdP. Schlägt eine Prüfung fehl, protokolliert der Agent ein sso_revalidation_failed-Audit-Ereignis mit dem Code IDP, nimmt keine neuen Aufgaben mehr an und beendet sich. Der Nutzer muss sich dann erneut anmelden und den Client neu starten.

Was protokolliert wird

SSO-Aktivitäten werden als auth-Ereignisse in das lokale Audit-Protokoll geschrieben. Jedes Ereignis, für das ein validiertes token vorliegt, enthält die SSO-Identität in actor (sso_issuer, sso_subject, sso_user, sso_groups).

`action`	Wann
`sso_login`	Anmeldung abgeschlossen (`devin auth login` oder Desktop).
`sso_login_denied`	Anmeldung nach Antwort des IdP verweigert: Die erforderliche Gruppe fehlt (`error_code: "IDP004"`), oder das zurückgegebene ID-token hat die Validierung nicht bestanden bzw. fehlte (`IDP005`). `actor` enthält die vom IdP bestätigte Identität; es wird nichts zwischengespeichert.
`sso_refresh`	tokens wurden beim IdP aktualisiert.
`sso_logout`	`devin auth logout` oder Abmeldung in Desktop.
`sso_revalidation_failed`	Ein aktiver Agent hat seine Anmeldung verloren und wird beendet; `error_code` enthält den `IDP`-Code.

IDP-Fehlercodes

Code	Bedeutung	Vorgehensweise
`IDP001`	Die Auth-Datei ist nicht lesbar oder ungültig.	Korrigieren Sie `/etc/devin/auth.json` (bzw. den Pfad in `DEVIN_AUTH_FILE`); die Meldung nennt das fehlerhafte Feld.
`IDP002`	Für den konfigurierten Issuer ist keine zwischengespeicherte Anmeldung vorhanden.	Führen Sie `devin auth login` aus.
`IDP003`	Die Anmeldung ist ungültig oder abgelaufen und konnte nicht automatisch im Hintergrund erneuert werden (auch bei einer `invalid_grant`-Antwort des IdP).	Führen Sie `devin auth login` erneut aus.
`IDP004`	Die Anmeldung war erfolgreich, aber der Nutzer ist kein Mitglied von `required_group`.	Fügen Sie den Nutzer beim IdP zur Gruppe hinzu oder korrigieren Sie `required_group` / `groups_claim`.
`IDP005`	Der IdP war nicht erreichbar oder hat einen Fehler zurückgegeben.	Prüfen Sie die Netzwerkerreichbarkeit, die TLS-Vertrauenskette (`DEVIN_CA_BUNDLE`) und die Logs des IdP.
`IDP006`	Der lokale SSO-Token-Cache ist nicht lesbar, fehlerhaft oder nicht ausschließlich für den aktuellen Nutzer zugänglich.	Führen Sie `devin auth login` aus; bei einer neuen Anmeldung wird der Cache neu geschrieben.

Der vollständige Katalog befindet sich auf der Seite Fehlercodes.

​Auth-Datei erstellen

​Client bei Ihrem IdP registrieren

​Anmelden

​Status prüfen und abmelden

​Was die CLI validiert

​Per automatischer Erkennung ermittelte Endpunkte müssen auf dem Issuer liegen

​Wie sich ein Entzug auswirkt

​Erneute Validierung in laufenden Sitzungen

​Was protokolliert wird

​IDP-Fehlercodes

Auth-Datei erstellen

Client bei Ihrem IdP registrieren

Anmelden

Status prüfen und abmelden

Was die CLI validiert

Per automatischer Erkennung ermittelte Endpunkte müssen auf dem Issuer liegen

Wie sich ein Entzug auswirkt

Erneute Validierung in laufenden Sitzungen

Was protokolliert wird

IDP-Fehlercodes