Zum Hauptinhalt springen

OAuth für Werkzeuge

Viele der eingebauten Werkzeuge von BasePeak.AI sind mit Drittanbieterdiensten (GitHub, Google, Slack und anderen) integriert und erfordern OAuth 2.0 zur Authentifizierung im Namen der Benutzer. Workspace-Administratoren konfigurieren die OAuth-Anwendungszugangsdaten, damit Benutzer diese Integrationen verbinden können, ohne ihre eigenen API-Zugangsdaten verwalten zu müssen.

Wo konfigurieren​

OAuth-App-Zugangsdaten werden über die Werkzeuge-Seite (/admin/tools) verwaltet. Für jedes Werkzeug, das OAuth erfordert, ist eine Konfigurationsoption direkt auf der Karte des Werkzeugs verfügbar. Werkzeuge, die noch nicht konfiguriert wurden, zeigen einen Hinweis an, damit Sie erkennen können, welche Aufmerksamkeit benötigen.

Eine OAuth-App einrichten​

Jedes Werkzeug bietet Schritt-für-Schritt-Anleitungen zur Registrierung einer OAuth-Anwendung beim entsprechenden Dienst:

  1. Öffnen Sie die Admin-Werkzeuge-Seite
  2. Suchen Sie das Werkzeug, das Sie konfigurieren möchten
  3. Öffnen Sie seine OAuth-Konfiguration
  4. Folgen Sie den eingebetteten Anleitungen, um eine OAuth-App in der Entwicklerkonsole des Drittanbieterdiensts zu erstellen
  5. Geben Sie die Client-ID und das Client-Secret (sowie alle anderen erforderlichen Felder) aus der registrierten App ein
  6. Speichern

Nach dem Speichern können sich Benutzer über das Werkzeug mit diesem Dienst authentifizieren, ohne eigene API-Zugangsdaten zu benötigen.

Die Redirect-URI​

Jede OAuth-App, die Sie über die Admin-Oberfläche für Werkzeuge konfigurieren, hat genau eine Redirect-URI – im Dialog als Weiterleitungs-URL bezeichnet. Sie muss beim Drittanbieterdienst exakt so registriert werden, wie BasePeak.AI sie anzeigt:

https://<ihre-instanz>/api/app-oauth/callback/<alias>

<alias> ist ein Kennzeichen aus Kleinbuchstaben, Zahlen und Bindestrichen, nicht der Anzeigename: bei den Anbieter-Presets etwa google, slack, microsoft365 oder nextcloud-oidc, bei einer benutzerdefinierten App der von Ihnen gewählte Alias. Der Konfigurationsdialog zeigt den vollständigen Wert mit einer Kopierschaltfläche in dem Schritt an, in dem die Konsole des Anbieters ihn verlangt. Kopieren Sie ihn dort, anstatt ihn abzutippen.

Ist Ihre Instanz unter mehreren Hostnamen erreichbar, verwenden Sie die für die Instanz konfigurierte (kanonische) Adresse. Bei den Anbieter-Presets bildet der Dialog den Wert aus der Adresse, unter der Sie die Admin-Oberfläche gerade aufgerufen haben – auf einem Zweit-Hostnamen zeigt er daher eine URI an, die die Plattform später nicht sendet.

Die reine Instanz-URL (https://<ihre-instanz>/) ist keine gültige Redirect-URI für ein Werkzeug. Die Anmeldung bei BasePeak.AI selbst akzeptiert einen Callback auf der reinen Instanz-URL, deshalb liegt diese Verwechslung nahe – OAuth für Werkzeuge erfordert jedoch den vollständigen Pfad oben. Manche Anbieterkonsolen fragen sowohl eine Startseite als auch eine Redirect-URI ab; die reine Instanz-URL gehört ausschließlich in das Startseiten-Feld.

Stimmen der registrierte Wert und der vollständige Pfad nicht überein, verweigert der Anbieter die Verbindung und zeigt einen Fehler anstelle des Zustimmungsbildschirms – Google etwa Error 400: redirect_uri_mismatch. Vergleichen Sie in diesem Fall die registrierte URI mit dem Wert im Konfigurationsdialog.

Benutzerdefinierte OAuth-Apps​

Für Werkzeuge, die einen generischen OAuth-Flow verwenden (anstelle eines benannten Anbieter-Presets), können Sie eine benutzerdefinierte OAuth-App mit Ihren eigenen Client-Zugangsdaten registrieren. Sie wählen dabei den Alias, der die oben beschriebene Redirect-URI vervollständigt; der Konfigurationsdialog zeigt die fertige URI zum Kopieren an. Der Alias lässt sich nach dem Anlegen nicht mehr ändern, weil er in die registrierte Redirect-URI eingeht – wählen Sie ihn daher bewusst.

Hinweise​

  • OAuth-Zugangsdaten werden verschlüsselt gespeichert und sind für Benutzer nicht sichtbar
  • Der Konfigurationsdialog jedes Werkzeugs beschreibt die für diese Integration erforderlichen genauen Scopes
  • Administratoren können Zugangsdaten jederzeit entfernen oder neu konfigurieren, ohne andere Werkzeuge zu beeinträchtigen