Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// integration

Authentifizierung

Gilt für

Produkt: Cloud · Server · Zielgruppe: Entwickler / Integrator

Gemeinsame vs. persönliche Zugangsdaten, Umgang mit Tokens und wie basebox die Identität eines Nutzers an das angebundene System weiterreicht. Die Regel in einem Satz: Ihr Server besitzt keine Zugangsdaten von Nutzern – er reicht sie durch.

Die zwei Modelle

Modell	Woher die Zugangsdaten kommen	Wann richtig
Persönliche Zugangsdaten	basebox setzt je Anfrage den `Authorization`-Header mit dem Token des fragenden Nutzers	Immer, wenn das Zielsystem Rechte je Person kennt – der Regelfall
Servicekonto	Ein maschineller Schlüssel aus einem Kubernetes-Secret in Ihrer Umgebung	Nur für Inhalte, die ohnehin alle Nutzer sehen dürfen (öffentliches Wiki, allgemeines Handbuch)

Ein Konnektor kann beides kombinieren – etwa ein Servicekonto für einen anonymen Index und persönliche Tokens für den Zugriff auf Inhalte. Das Zugangsmodell steht in der Werkzeugbeschreibung und in Ihrer Dokumentation, damit Administratoren es beim Freigeben kennen.

Wie persönliche Zugangsdaten bei Ihnen ankommen

Der Nutzer trägt sein Token einmalig in basebox ein (im Chat über „+" oder unter Einstellungen → Konnektoren) und klickt auf Verbindung testen.
basebox speichert es nur schreibend in der Nutzereinstellung. Kein Administrator sieht es.
Bei jedem Werkzeugaufruf lädt AISRV das Token anhand der user_id frisch und erzeugt daraus den Header – Bearer oder HTTP Basic, je nach Konnektor-Konfiguration.
POST /mcp an Ihren Server trägt diesen Header. Sie reichen ihn unverändert an das Zielsystem weiter.

Es gibt keinen Schritt, in dem Ihr Server ein Token entgegennimmt, um es zu behalten. Ein Login-Werkzeug („melde mich an") ist ein Designfehler.

Was Sie mit dem Header tun

Weiterreichen, exakt wie erhalten, an jeden Aufruf des Zielsystems.
Nicht speichern – nicht im Prozess über die Anfrage hinaus, nicht auf Platte, nicht in einem Cache-Schlüssel.
Nicht loggen – auch nicht gekürzt, auch nicht als Hash. In Produktionslogs erscheinen Zugangsdaten nie; im Rahmen gezielter Diagnoseläufe höchstens auf Level DEBUG.
Nicht umformen – kein Tausch gegen ein anderes Token, keine Anreicherung. Braucht das Zielsystem einen anderen Header-Namen (X-Auth-Token, PRIVATE-TOKEN), übertragen Sie den Wert, aber ohne ihn anzureichern oder zu erweitern.
Fehlt der Header, antworten Sie mit einem klaren Werkzeugfehler („Keine Zugangsdaten hinterlegt – bitte Konnektor in basebox einrichten"), nicht mit einem Rückfall auf ein Servicekonto.

Welches Token Nutzer eintragen sollen

Verlangen Sie ein eigens erzeugtes, widerrufbares Zugriffstoken des Zielsystems – nie das Login-Passwort. Beispiele: permanente Tokens in YouTrack, App-Passwörter oder Tokens in Wikis, OAuth-Tokens mit begrenztem Scope. Beschreiben Sie in Ihrer Dokumentation, wie Nutzer es erzeugen; für YouTrack existiert eine solche Anleitung unter YouTrack-Token erstellen.

Empfehlen Sie Nutzern den minimalen Scope: lesend, wenn nur gelesen wird; begrenzt auf die Projekte oder Bereiche, die sie brauchen.

Servicekonten richtig einsetzen

Als Kubernetes-Secret bereitstellen und per valueFrom.secretKeyRef in Ihren Container laden – nie im Klartext in Helm-Values oder im Image.
Ein dediziertes Konto mit minimalen, lesenden Rechten; kein Konto einer echten Person.
Rotation einplanen: Das Secret lässt sich austauschen, ohne den Konnektor neu zu bauen.
In der Werkzeugbeschreibung kenntlich machen, dass Ergebnisse nicht nutzerspezifisch sind.

Fehler des Zielsystems abbilden

Zielsystem antwortet	Ihr Werkzeugergebnis
401 Unauthorized	„Zugangsdaten ungültig oder abgelaufen – Token in basebox erneuern"
403 Forbidden	„Kein Zugriff auf diese Ressource" – keine Umgehung, kein Fallback
404 Not Found	„Nicht gefunden" – dasselbe, was der Nutzer direkt sähe
429 Too Many Requests	„Ratenlimit erreicht – später erneut versuchen"
5xx	„Zielsystem nicht erreichbar" mit kurzer Ursache

Diese Meldungen kommen als Daten zurück; das Modell erklärt sie dem Nutzer. Sie dürfen keine Details enthalten, die über das hinausgehen, was das Zielsystem preisgibt.

Verbindung testen

Administratoren und Nutzer klicken in basebox auf Verbindung testen. Damit das etwas aussagt, sollte Ihr Server einen günstigen, lesenden Aufruf gegen das Zielsystem ausführen können, der mit den übergebenen Zugangsdaten die Authentifizierung bestätigt – etwa das eigene Nutzerprofil abrufen.

Checkliste

Kein Speichern, kein Loggen, kein Cachen von Zugangsdaten
Header unverändert weitergereicht; Bearer und Basic unterstützt, soweit das Zielsystem sie kennt
Fehlender Header → klarer Fehler, kein Rückfall
401/403 des Zielsystems → als Ergebnis zurückgegeben, nie umgangen
Servicekonto nur aus Kubernetes-Secret, nur lesend, nur für allgemein zugängliche Inhalte
Dokumentation, welches Token Nutzer wie erzeugen

Weiter: Lesezugriff · Konnektor-Authentifizierung (Admin-Sicht) · Autorisierungsablauf