OAuth-Anwendungen für Partner

Aus Planfix

Eine partner-eigene OAuth-Anwendung ist für eine Integration vorgesehen, die sich mit mehreren Planfix-Konten verbindet. Dieselben Anwendungsanmeldeinformationen werden für alle Kundenkonten verwendet, während jedes Konto die Zulassung separat steuert und jede/r Benutzer/in der eigenen Verbindung zustimmt.

Wenn eine Integration nur für ein einziges Konto vorgesehen ist, ist es einfacher, eine kontoeigene Anwendung zu erstellen.

Erstellung einer Anwendung

  1. Öffnen Sie Ihr Partnerkonto.
  2. Gehen Sie zu OAuth-Anwendungen.
  3. Wählen Sie Anwendung erstellen.
  4. Geben Sie den Namen und die Beschreibung ein, die Nutzer/innen und Administrator/innen sehen werden.
  5. Wählen Sie den OAuth-Client-Typ.
  6. Fügen Sie die Redirect-URIs hinzu.
  7. Wählen Sie die minimal erforderlichen REST-API-Scopes aus.
  8. Speichern Sie die Anwendung und kopieren Sie deren Anmeldeinformationen.

Eine neue Anwendung ist privat und erfordert in jedem Konto, mit dem sie sich verbindet, eine ausdrückliche Genehmigung.

OAuth-Client-Typ

Typ Vorgesehene Anwendungen Anmeldeinformationen
Public Mobile, Desktop- und Browser-Anwendungen sowie lokale MCP-Clients. Ein client_id nur. Es gibt kein Client-Secret; PKCE S256 ist verpflichtend.
Confidential Serverseitige Anwendungen, bei denen das Secret außerhalb des Geräts der Nutzer/innen und des Client-seitigen Codes gespeichert werden kann. Ein client_id und ein client_secret.

Der OAuth-Client-Typ ist getrennt davon, ob eine Anwendung veröffentlicht ist oder nicht. Beispielsweise ist eine private mobile Anwendung ein öffentlicher OAuth-Client ohne Secret.

Redirect-URIs

Geben Sie jede URL an, an die Planfix einen Nutzer oder eine Nutzerin nach der Anmeldung zurückgeben kann.

  • Verwenden Sie https für einen Webdienst.
  • http ist nur für Loopback-Adressen wie localhost und 127.0.0.1 erlaubt.
  • Ein Client kann für eine Loopback-Adresse einen dynamischen Port verwenden, aber Schema, Host, Pfad und Query müssen übereinstimmen.
  • Verwenden Sie keine Wildcards, URL-Fragmente oder Redirect-URIs, die Sie nicht kontrollieren.

Scopes

Scopes definieren die maximalen Berechtigungen der Anwendung. Fordern Sie nur die Zugriffsebenen an, die Sie aus der Liste der REST-API-Scopes benötigen.

Anwendungsscopes ersetzen nicht die normalen Berechtigungen des/der Benutzer/in. Selbst wenn ein Scope gewährt wird, kann die Anwendung nur mit den Daten arbeiten, die für diese/n Benutzer/in verfügbar sind.

Die Änderung von Redirect-URIs oder Scopes erzeugt eine neue Genehmigungsversion. Vorher verbundene Konten müssen die neue Version prüfen und genehmigen, und die Nutzer/innen müssen die Verbindung erneut herstellen.

Verbindung eines Kundenkontos

Eine private partner-eigene Anwendung muss in jedem Konto ausdrücklich von einer Administratorin oder einem Administrator genehmigt werden.

  1. Öffnen Sie die Anwendung in Ihrem Partnerkonto.
  2. Geben Sie im Bereich für den Genehmigungslink den Namen des Kundenkontos ein.
  3. Kopieren Sie den generierten Link und senden Sie ihn an eine/n Administrator/in dieses Kontos.
  4. Bitten Sie die Administratorin/den Administrator, den Inhaber, die Redirect-URIs und die Scopes zu überprüfen und die Anwendung dann zu genehmigen.
  5. Nach der Genehmigung können Nutzer/innen im Konto die OAuth-Autorisierung abschließen. Jede/r Nutzer/in stimmt getrennt in eigener Sache zu.

Der Link öffnet Kontoverwaltung → API → OAuth- und MCP-Anwendungen und zeigt die angeforderte Anwendung an.

Eine Administratorin oder ein Administrator, die/der die Anwendung gleichzeitig verbindet, kann Genehmigen und verbinden wählen.

Private und veröffentlichte Anwendungen

Status Wie die Zulassung im Konto erfolgt
Privat Erfordert immer eine ausdrückliche Genehmigung durch eine/n Administrator/in jedes Kontos.
Veröffentlicht Verfügbar ohne separate Genehmigung, wenn die Kontorichtlinie Veröffentlichte Anwendungen erlauben ist. Bei der Richtlinie Nur genehmigte Anwendungen ist weiterhin eine Genehmigung erforderlich.

Die Veröffentlichung ist eine separate Planfix-Prüfung. Bereiten Sie vor der Einreichung der Anwendung einen klaren Namen und eine eindeutige Beschreibung, ein minimales Set an Scopes, funktionierende Redirect-URIs und Benutzerdokumentation für das Verbinden und Entfernen der Integration vor. Kontaktieren Sie den Planfix-Support für das Veröffentlichungsverfahren.

Verbindungsadressen

Verwenden Sie die globalen OAuth-Endpunkte:

Zweck Adresse
Autorisierung https://auth.planfix.com/oauth/authorize
Token https://auth.planfix.com/oauth/token
Userinfo https://auth.planfix.com/oauth/userinfo
MCP https://mcp.planfix.com/mcp

Fügen Sie den Kontonamen nicht zu einer globalen URL hinzu. Die/der Benutzer/in wählt das Konto auf einer Planfix-Seite aus. Das vollständige Protokoll, einschließlich resource, PKCE, Token-Refresh und Widerruf, ist in OAuth 2.0 für Anwendungen beschrieben.

Verwaltung einer Anwendung

Ein Partner kann:

  • den Namen und die Beschreibung bearbeiten;
  • Redirect-URIs und Scopes ändern;
  • die Anwendung deaktivieren und wieder aktivieren;
  • das Client-Secret einer vertraulichen Anwendung rotieren;
  • einen Genehmigungslink für eine bestimmte Kontoerlaubnis generieren.

Nach der Rotation des Secrets funktioniert das alte Client-Secret sofort nicht mehr. Aktualisieren Sie das Secret auf dem Integrationsserver und senden Sie es niemals an Nutzer/innen.

Das Deaktivieren einer Anwendung blockiert die OAuth-Autorisierung und die ausgegebenen Tokens in jedem Konto. Diese Aktion betrifft alle Kund/innen, die die Anwendung nutzen.

Empfehlungen vor dem Start

  • Verwenden Sie Authorization Code mit PKCE S256 und validieren Sie state.
  • Fordern Sie nur die Scopes an, die Sie benötigen.
  • Zeigen Sie das ausgewählte Konto der/dem Nutzer/in nach der Anmeldung an.
  • Berücksichtigen Sie Rotation von Refresh-Tokens: Nach einem erfolgreichen Refresh ist das vorherige Refresh-Token nicht mehr gültig.
  • Schreiben Sie Tokens, Autorisierungscodes, code_verifier oder Client-Secrets nicht in Logs.
  • Dokumentieren Sie, wie Nutzer/innen die Integration trennen und die Löschung ihrer Daten anfordern können.
  • Testen Sie Szenarien für Widerruf von Genehmigungen, Deaktivierung der Anwendung und erneute Verbindung.

Gehe zu