Skip to main content
Novaplan AI stellt einen OAuth-2.0-Autorisierungsserver bereit. Eine Workspace-Administration kann Anwendungen registrieren, Redirect-URIs hinterlegen und deren Berechtigungen festlegen. Stimmen Sie Integrationen und administrative Scopes mit Novaplan ab, bevor Sie sie produktiv freigeben.

​
Anwendung anlegen

  1. Melden Sie sich als Administration an und öffnen Sie Workspace Settings → Developer Settings → OAuth 2.0 Apps.
  2. Wählen Sie New OAuth application und vergeben Sie einen Application Name. Optional können Sie eine Beschreibung sowie Homepage-, Datenschutz- und Nutzungsbedingungen-URLs eintragen. Diese Angaben helfen Nutzenden, die Anwendung im Einwilligungsdialog zu erkennen.
  3. Wählen Sie den passenden Grant-Typ. Authorization Code ist für Anwendungen mit persönlicher Anmeldung vorgesehen. Öffentliche Clients wie mobile Apps und Single-Page-Apps benötigen dabei PKCE. Refresh Token ermöglicht erneute Tokens nach erteilter offline_access-Berechtigung.
  4. Tragen Sie die Redirect-URIs der Clients ein. Die URI im Autorisierungsaufruf muss exakt einem registrierten Wert entsprechen. HTTPS ist erforderlich; localhost und 127.0.0.1 können für lokale Clients zulässig sein.
  5. Wählen Sie nur die Scopes, die die Anwendung tatsächlich benötigt. Speichern Sie die Anwendung und verwahren Sie Client ID und Client Secret sicher. Das Secret wird bei der Erstellung nur einmal angezeigt; geht es verloren, müssen Sie es neu erzeugen und alle angebundenen Anwendungen mit dem neuen Wert aktualisieren.
Client Credentials authentifiziert eine Anwendung ohne persönliche Anmeldung. Verwenden Sie diesen Grant nicht für Anfragen, deren Ergebnis die Berechtigungen eines bestimmten Nutzers beachten muss. Dafür sind Authorization Code oder ein benutzergebundenes Token vorgesehen.

​
Scopes auswählen

Scopes begrenzen den angeforderten Zugriff. Zu den in der technischen Referenz dokumentierten Gruppen gehören: Nicht jede Anwendung benötigt alle diese Scopes. Besonders Schreib-, Lösch- und Administrationsrechte sollten einzeln geprüft werden. Der MCP-Server kann über seine OAuth-Metadaten eine serverseitige Auswahl bekannt geben.

​
Authorization-Code-Ablauf

  1. Der Client leitet die Person zu NOVAPLAN_WORKSPACE_URL/api/v1/oauth2/authorize weiter. Er übergibt unter anderem client_id, redirect_uri, response_type=code, angeforderte scope-Werte und einen zufälligen state-Wert. Öffentliche Clients senden zusätzlich eine PKCE-Code-Challenge.
  2. Die Person meldet sich an und prüft die angeforderten Berechtigungen.
  3. Novaplan AI leitet zur registrierten Redirect URI mit einem kurzlebigen Autorisierungscode und state zurück. Der Client vergleicht state mit dem ursprünglich gespeicherten Wert.
  4. Der Client tauscht den Code per POST an NOVAPLAN_WORKSPACE_URL/api/v1/oauth2/token gegen Tokens. Die redirect_uri muss mit dem Autorisierungsaufruf übereinstimmen. Vertrauliche Clients authentifizieren sich mit ihrem Secret; öffentliche Clients verwenden den zugehörigen PKCE-Code-Verifier.
Bei offline_access kann ein Refresh Token ausgegeben werden. Die technische Quellanleitung nennt 30 Tage als voreingestellte Gültigkeit, die pro Anwendung konfigurierbar ist; prüfen Sie den Wert im bereitgestellten Workspace. Bei jeder Erneuerung wird das bisherige Refresh Token durch ein neues ersetzt und ungültig. Speichern Sie daher immer den zuletzt erhaltenen Wert sicher. Tokens lassen sich über den Revocation-Endpunkt widerrufen.

​
Token für einen vertraulichen Client abrufen

Eine serverseitige Anwendung tauscht den Autorisierungscode mit ihrer Client ID und ihrem Client Secret aus. Ersetzen Sie die Platzhalter und verwenden Sie die tatsächliche Workspace-Adresse:
Ein öffentlicher Client wie eine Single-Page-App darf kein Client Secret enthalten. Er sendet bei der Token-Anfrage stattdessen den code_verifier, der zur ursprünglichen PKCE-Challenge gehört. Verwenden Sie den erhaltenen Access Token als Authorization: Bearer ACCESS_TOKEN für freigegebene API-Aufrufe.

​
Token erneuern und widerrufen

Nach Ablauf eines Access Tokens kann ein vertraulicher Client das aktuelle Refresh Token verwenden:
Speichern Sie das neue Refresh Token aus jeder erfolgreichen Antwort, weil das bisherige ungültig wird. Ist ein Token nicht mehr erforderlich, widerrufen Sie es:
Für ein Refresh Token setzen Sie token_type_hint=refresh_token. Ein client_credentials-Token eignet sich nur für genehmigte Anwendungs-Scopes ohne persönliche Benutzeridentität und darf nicht für benutzergebundene Suche verwendet werden.

​
Token für eine Anwendung ohne Nutzeridentität

Für einen ausdrücklich freigegebenen Server-zu-Server-Ablauf kann eine vertrauliche Anwendung einen Token mit client_credentials anfordern:
Dieser Token steht für die Anwendung, nicht für eine angemeldete Person. Er ist daher ungeeignet für Suche, Chat oder Dokumentabrufe, bei denen individuelle Quellberechtigungen gelten müssen. Verwenden Sie für solche Anfragen den Authorization-Code-Ablauf oder ein benutzergebundenes Token.

​
Endpunkte

Bei Fehlern vergleichen Sie Redirect URI, Grant-Typ, registrierte Scopes und bei PKCE die Code-Challenge mit dem Verifier. Prüfen Sie außerdem, ob ein Secret abgelaufen oder eine Anwendung ausgesetzt wurde. Für Freigaben und Fragen zu produktiven Integrationen kontaktieren Sie Novaplan Support.

​
Anwendungen verwalten

In der Detailansicht einer OAuth-Anwendung können Administrierende die Client ID, erlaubten Scopes, Grant-Typen, Redirect-URIs und Token-Einstellungen prüfen. Wenn ein Client Secret kompromittiert wurde oder rotiert werden soll, wählen Sie Generate new client secret und hinterlegen den neuen Wert in allen betroffenen Integrationen. Das bisherige Secret wird sofort ungültig; Anwendungen mit dem alten Wert können sich danach nicht mehr authentifizieren. Unter Advanced lässt sich eine Anwendung mit Suspend Application vorübergehend aussetzen. Dadurch sind neue Autorisierungen und Token-Ausgaben nicht mehr möglich; bereits ausgegebene Tokens bleiben laut Quellanleitung bis zu ihrem Ablauf gültig. Über Activate application kann die Anwendung wieder freigegeben werden. Für einen Sicherheitsvorfall können Administrierende Revoke all tokens verwenden und die Aktion durch Eingabe des Anwendungsnamens bestätigen. Delete Application ist dauerhaft und widerruft die zugehörigen Access- und Refresh-Tokens; damit verlieren angebundene Integrationen unmittelbar den Zugang. Stimmen Sie solche Schritte mit den Verantwortlichen der betroffenen Anwendungen ab.

​
Sicherheitsregeln und Fehlersuche

  • Bewahren Sie Client Secrets nur in einem geschützten Secret-Speicher auf. Öffentliche Clients dürfen kein fest eingebautes Secret enthalten und benötigen PKCE, vorzugsweise mit S256.
  • Erzeugen Sie für jeden Autorisierungsversuch einen neuen, nicht vorhersehbaren state-Wert und vergleichen Sie ihn beim Rückruf. Speichern Sie nach jeder Token-Erneuerung den zuletzt ausgegebenen Refresh Token. Widerrufen Sie Tokens, wenn eine Person die Integration trennt.
  • Schlägt die Autorisierung fehl, prüfen Sie client_id, den Status der Anwendung, exakt passende Redirect URI und erlaubte Scopes.
  • Bei invalid_grant kann der Autorisierungscode abgelaufen oder schon verwendet worden sein. Die Quellanleitung nennt zehn Minuten Gültigkeit. Prüfen Sie außerdem Redirect URI und den PKCE-code_verifier gegen die ursprüngliche Challenge; beginnen Sie danach einen neuen Anmeldeversuch.
  • Wird ein Refresh Token abgelehnt, kann er bereits rotiert, abgelaufen oder administrativ widerrufen worden sein. Melden Sie die Person erneut über den Authorization-Code-Ablauf an.
  • Bei 403 Forbidden prüfen Sie sowohl den Scope des Access Tokens als auch die Berechtigung der angemeldeten Person in der Organisation. Ein zusätzlicher Scope ersetzt keine fehlende Quellberechtigung.
Die Quellanleitung nennt höchstens zehn registrierte Redirect-URIs pro Anwendung. Prüfen Sie diese und die unterstützten PKCE-Verfahren gegen die tatsächlich bereitgestellte Novaplan-Version, bevor Sie eine produktive Integration freigeben.

​
Häufige Fragen

​
Wer kann OAuth-Anwendungen anlegen?

Die Verwaltung von OAuth-Anwendungen ist laut Quellreferenz auf Organisationsadministrierende beschränkt. Andere Personen können einer vorbereiteten Anwendung beim persönlichen Autorisierungsablauf Zugriff gewähren.

​
Was geschieht beim Erneuern eines Client Secrets?

Das bisherige Secret wird sofort ungültig. Aktualisieren Sie alle betroffenen Integrationen mit dem neuen Wert; bis dahin schlagen deren Authentifizierungsanfragen fehl.

​
Wie viele Anwendungen und Redirect-URIs sind möglich?

Die Quellreferenz nennt keine feste Obergrenze für die Anzahl der OAuth-Anwendungen einer Organisation, aber höchstens zehn registrierte Redirect-URIs pro Anwendung. Prüfen Sie beides gegen den bereitgestellten Enterprise Workspace.

​
Wird PKCE unterstützt?

Ja. Für öffentliche Clients ohne sicher verwahrbares Client Secret ist PKCE erforderlich. Die zugängliche Implementierung nennt S256 und plain; verwenden Sie nach Möglichkeit S256 und bestätigen Sie die tatsächlich unterstützten Verfahren im bereitgestellten Workspace.