Zum Hauptinhalt springen
Ermöglichen Sie Benutzern, Ihre Anwendung für den Zugriff auf ihr Ace Data Cloud-Profil, Service-Abonnements, API Keys, Nutzung oder Bestellungen zu autorisieren. Verwenden Sie den Standard Authorization Code + S256 PKCE: Die Anwendung öffnet die Autorisierungsseite, der Benutzer erhält nach seiner Zustimmung einen einmaligen code, der dann gegen einen OAuth access token eingetauscht wird. Der OAuth access token wird für den Zugriff auf Kontoresourcen-Schnittstellen verwendet; für den Aufruf der Modell-API wird der entsprechende API Key verwendet. Die OAuth-Autorisierung erstellt nicht automatisch einen API Key, aktiviert keine Services und erhöht kein Guthaben.

Integrationsmethode auswählen

Die Standardweiterleitung erfordert weder embed=studio, embed_origin noch postMessage. Im Studio-Komponentenmodus erstellt der Host die Autorisierungsseite und verwaltet die Nachrichtenbrücke; Dritte integrieren sich gemäß dem Komponentenprotokoll am Ende dieses Dokuments und dürfen diese beiden Parameter nicht selbst zusammensetzen.

Endpunkte und Discovery-Dokument

Die Anwendungsverwaltungsschnittstelle erfordert eine Kontoanmeldung und ist keine Schnittstelle für anonyme dynamische Registrierung (DCR). Die eigenen Discovery-/Registrierungsadressen des MCP-Service unterscheiden sich von den OAuth-Endpunkten für Konten in dieser Tabelle; beim Verbinden mit einem bestimmten MCP folgen Sie dessen Dokumentation und Discovery-Ergebnissen. Das Discovery-Dokument wird verwendet, um Endpunkte und Protokollfunktionen zu erhalten. Der aktuelle Ablauf gibt OAuth token zurück, jedoch kein id_token; behandeln Sie ihn nicht allein aufgrund des Vorhandenseins des Scope openid als vollständigen OpenID-Connect-Anmeldeablauf.

Berechtigungsbereiche: Aktuelle Scope-Namen verwenden

scope besteht aus durch Leerzeichen getrennten, groß-/kleinschreibungssensitiven Berechtigungsnamen. Neue Anwendungen verwenden konkrete Berechtigungen wie profile:read, email:read, phone:read usw.

Wo die beantragbaren Berechtigungen abgerufen werden

Nach der Anmeldung gibt die OAuth-Anwendungslisten-Schnittstelle GET /api/v1/oauth2/applications/ available_scopes zurück; die Berechtigungsauswahl auf der Anwendungsverwaltungsseite verwendet denselben Katalog. Dies sind die optionalen Bereiche, die gewöhnliche Self-Service-Anwendungen verwenden sollten. scopes_supported in Discovery enthält alle von der Plattform erkannten Berechtigungsnamen, bedeutet aber nicht, dass Ihre Anwendung jede davon beantragen kann. Die tatsächliche Autorisierung prüft gleichzeitig:
  1. Ob die Berechtigung an diesen Anwendungstyp delegiert werden darf;
  2. Ob die Berechtigung in den zulässigen Bereichen dieser OAuth-Anwendung registriert ist;
  3. Ob der aktuelle Benutzer die angeforderte Berechtigung besitzt.
Unbekannte, nicht registrierte, nicht delegierbare oder vom Benutzer nicht besessene Berechtigungen geben invalid_scope zurück. Auch beim Einlösen und Aktualisieren des Autorisierungscodes wird erneut geprüft; Berechtigungen werden nicht automatisch ergänzt oder erhöht.

Optionale Berechtigungen für gewöhnliche Self-Service-Anwendungen

Nachfolgend der aktuelle Katalog (2026-10-09); bei der Integration ist available_scopes maßgeblich. Um beispielsweise nur das Profil zu lesen, verwenden Sie profile:read; wenn eine E-Mail-Adresse benötigt wird, fügen Sie email:read hinzu; zum Lesen vorhandener API Keys verwenden Sie profile:read credentials:read. Beantragen Sie credentials:write nur, wenn Sie tatsächlich Keys erstellen oder ändern müssen, und fügen Sie offline_access nur hinzu, wenn eine Aktualisierung benötigt wird. Einige Berechtigungen sind nur für von der Plattform genehmigte vertrauenswürdige Anwendungen verfügbar, beispielsweise sites:read, sites:write, platform-tokens:read; andere Berechtigungen sind nicht für gewöhnliche OAuth-Anwendungen von Drittanbietern geöffnet. Die Client-Typen public/confidential beschreiben, ob ein secret sicher verwahrt werden kann, und haben nichts damit zu tun, ob eine Anwendung vertrauenswürdig ist. Selbst erstellte Anwendungen können vertrauenswürdige Berechtigungen nicht selbst aktivieren. account ist ein Berechtigungsauswähler für Konten, der vom angegebenen offiziellen Kontoverwaltungs-MCP verwendet wird, und kein „Alle Berechtigungen“-Scope für Drittanbieteranwendungen; er kann nicht mit anderen Scopes gemischt werden. Drittanbieter sollten die benötigten konkreten Berechtigungen ausdrücklich auflisten.

Migration aus alter Dokumentation

Alte Namen werden nicht als kompatible Aliase akzeptiert. Aktualisieren Sie gleichzeitig die Scopes in der OAuth-Anwendungsregistrierung, die Autorisierungs-URL und Ihre eigene Berechtigungsprüfung; das Ändern der Anwendungskonfiguration fügt bereits ausgestellten token keine Berechtigungen hinzu, und der Benutzer muss erneut autorisieren.

Schritt 1: OAuth-Anwendung registrieren

Öffnen Sie die OAuth-Anwendungsverwaltung, erstellen Sie eine Anwendung und füllen Sie Folgendes aus:
  • Name, Beschreibung, Anwendungslogo: werden auf einer Seite der Autorisierungsseite angezeigt.
  • Client-Typ: Wählen Sie für reine Frontends, mobile oder Desktop-Clients Public; wählen Sie für Dienste, die ein Secret im Backend verwahren können, Confidential.
  • Rückrufadresse: Verwenden Sie in der Produktionsumgebung HTTPS und registrieren Sie die vollständige URL, unter der die Anwendung den Rückruf tatsächlich verarbeitet.
  • Berechtigungen: Wählen Sie aus dem auf der Seite bereitgestellten Verzeichnis die tatsächlich benötigten Scopes aus.
Speichern Sie client_id. Confidential-Clients speichern client_secret serverseitig und dürfen es nicht in HTML, Frontend-Build-Variablen oder URLs ablegen. Public-Clients verwenden beim Austausch gegen ein Token kein Secret; selbst wenn die Registrierungsantwort dieses Feld enthält, darf es nicht als Berechtigung behandelt werden, die der Client geheim halten kann. redirect_uri muss bei der Registrierung, Autorisierung und beim Token-Austausch exakt übereinstimmen, einschließlich Pfad, abschließendem Schrägstrich und Abfrageparametern. Jedes Konto kann höchstens 20 Anwendungen erstellen. Das Secret wird nur bei der Erstellung/Rotation angezeigt; nach der Rotation kann das alte Secret nicht mehr für Austauschvorgänge verwendet werden, die eine Client-Authentifizierung erfordern.

Schritt 2: Autorisierung über die Schaltfläche starten

Erzeugen Sie bei jedem Klick auf Verbinden ein neues zufälliges state und code_verifier und berechnen Sie:
Speichern Sie state, Verifier und Rückrufadresse in der eigenen Sitzung der Anwendung und öffnen Sie dann die Autorisierungsseite mit URL-codierten Parametern:
Public-Clients müssen S256 PKCE senden. Obwohl Discovery weiterhin plain auflistet, dürfen Public-Clients es nicht verwenden. Auch Confidential-Clients wird die Verwendung von S256 empfohlen; wenn beim Start der Autorisierung PKCE verwendet wurde, muss beim Austausch der entsprechende Verifier übermittelt werden. Nach der Zustimmung des Nutzers erfolgt die Rückkehr zu redirect_uri, wobei die Abfrageparameter code und den unverändert zurückgegebenen state enthalten. Bei Ablehnung werden error=access_denied, eine Fehlerbeschreibung und state zurückgegeben. Überprüfen Sie vor der Verarbeitung des Rückrufs zunächst, ob state mit dieser Sitzung übereinstimmt. Der Autorisierungscode ist 10 Minuten gültig und kann nur einmal ausgetauscht werden; starten Sie nach einem Fehlschlag die Verbindung erneut und aktualisieren Sie nicht wiederholt die alte Rückruf-URL.

Schritt 3: OAuth-Token abrufen

Public-Clients tauschen direkt im Browser oder Client; Confidential-Clients tauschen in ihrem eigenen Backend. Der Anfrageinhalt unterstützt Formularcodierung, die folgenden Variablen stehen für die Daten, die die Anwendung bei dieser Autorisierung erhalten hat:
Confidential-Clients müssen serverseitig zusätzlich das Formularfeld client_secret hinzufügen. Derzeit wird client_secret_post unterstützt; behandeln Sie HTTP-Basic-Client-Authentifizierung nicht als unterstützte Methode. Lesen Sie aus der erfolgreichen Antwort access_token, token_type, expires_in und den tatsächlich gewährten scope. Nur wenn offline_access angefordert und genehmigt wurde, gibt es ein refresh_token. Behandeln Sie das OAuth-Access-Token nicht als API-Key der Modell-API und schreiben Sie Token, Verifier oder Autorisierungscode nicht in Logs, Analyseereignisse oder Freigabelinks.

Schritt 4: Benutzerinformationen und API-Key lesen

Verwenden Sie zunächst das OAuth-Access-Token, um UserInfo anzufordern:
Die zurückgegebenen Felder hängen vom Scope ab: id ist die Benutzerkennung; mit profile:read oder openid können grundlegende Profildaten gelesen werden (z. B. username, nickname, avatar, is_verified, date_joined, registration_method); für die E-Mail-Adresse ist email:read erforderlich, für Telefonnummer und Region phone:read. Verlassen Sie sich nicht darauf, dass nicht autorisierte Felder immer vorhanden sind. Wenn ein vorhandener API-Key benötigt wird und credentials:read genehmigt wurde, verwenden Sie die id aus UserInfo als Filterbedingung:
Die zurückgegebene Liste verwendet count und items; das Key-Feld ist items[*].token, nicht data[0].value. user_id=me ist keine gültige Benutzer-ID für diese Schnittstelle. Lesen Sie mehrseitige Daten mit offset/limit weiter; behandeln Sie nicht die erste Seite als alle Zugangsdaten. Wählen Sie je nach Anwendung, Dienst und Gültigkeitsstatus die passende Berechtigung aus und nehmen Sie nicht blind den ersten Eintrag. Eine leere Liste bedeutet nicht, dass die Autorisierung fehlgeschlagen ist; der Nutzer hat möglicherweise noch keinen passenden Key erstellt. Die Berechtigungskontrolle des OAuth-Access-Tokens und Dienstumfang, Kontingent sowie Ablaufbedingungen des API-Keys selbst sind unterschiedliche Einschränkungen. Das Zulassen des Lesens von API-Keys bedeutet, dass Dritte sie speichern und verwenden können. Das Widerrufen der OAuth-Anfrage oder das Löschen des Anmeldestatus der Anwendung macht bereits kopierte API-Keys nicht ungültig; der Nutzer muss den Key in der Zugangsdatenverwaltung separat widerrufen oder rotieren.

Ausführbares Public-/PKCE-Browserbeispiel

Stellen Sie die folgende Seite unter Ihrer registrierten REDIRECT_URI bereit und ersetzen Sie CLIENT_ID und die Rückrufadresse. Die Schaltfläche startet die Standardautorisierung; nach der Rückkehr zur selben Seite werden persönliche Profildaten und die Anzahl vorhandener Keys gelesen. Das Beispiel zeigt oder persistiert keine Keys; Produktionsanwendungen verwenden die Ergebnisse entsprechend ihrem tatsächlichen Zweck. Validieren Sie zunächst auf einer eigenständigen Browserseite und nehmen Sie danach gemäß den späteren iframe-Anforderungen ab.
Der Callback und der Einstieg des Beispiels müssen sich in derselben Herkunft sowie im selben Browser-Tab/-iframe befinden, damit der zuvor gespeicherte sessionStorage gelesen werden kann. Produktionsanwendungen sollten Tokens in ihrem eigenen Sitzungsschema verwalten, den Ablauf behandeln und die Autorisierungs-URL-Parameter nach Erhalt der Antwort löschen; die Hauptoberfläche der Seite sollte zuerst gerendert werden, und Netzwerkfehler sollten nur den Verbindungsstatus beeinträchtigen.

iframe in White-Label-Websites

Kundenwebsite leitet selbst zur Autorisierungsseite weiter

Verwenden Sie einfach die Standard-OAuth-Parameter und Ihre eigene Callback-Verarbeitung; window.location.assign() navigiert das aktuelle iframe, während die übergeordnete Seite auf der White-Label-Domain bleibt. Es ist nicht erforderlich, für das Symbol embed=studio hinzuzufügen oder das Studio-Nachrichtenprotokoll zu implementieren. Folgende Bedingungen müssen erfüllt sein:
  • Anwendungsseite und Callback-Seite verwenden HTTPS, sind tatsächlich erreichbar und erlauben die Einbettung durch die White-Label-Parent-Domain über iframe; prüfen Sie bei beiden Content-Security-Policy: frame-ancestors und X-Frame-Options.
  • Die Sandbox erlaubt die von der Seite benötigten Skripte, Formulare und Herkunfts-/Speicherfunktionen. Bei Unterstützung der Anmeldung per Pop-up werden außerdem die entsprechenden Pop-up-Funktionen benötigt; bevorzugen Sie die von Studio bereitgestellte Konfiguration der Website-Komponente.
  • Der Browser erlaubt, dass das aktuelle Einbettungsszenario den für den Autorisierungsstatus erforderlichen Speicher verwendet. Der Anmeldestatus der White-Label-Website und der Anmeldestatus von AuthFrontend können unterschiedlich sein; es darf nicht angenommen werden, dass die Anmeldung bei der White-Label-Website bereits eine Anmeldung auf der Autorisierungsseite bedeutet.
  • Der Token-Austauschdienst im Callback ist verfügbar, und ursprungsübergreifende Anfragen erlauben die Anwendungsherkunft; DNS-, CORS- und HTTP-Fehler müssen alle einen erneut versuchbaren Status anzeigen und dürfen nicht dazu führen, dass die gesamte Seite nicht mehr gerendert wird.
Die linke Seite der Autorisierungsseite liest das OAuth-Anwendungslogo; die rechte Seite liest das Favicon/Logo dieser Site, wenn der Browser die Parent-Herkunft bereitstellen kann und die Parent-Domain die Prüfung über die verifizierte Website besteht, andernfalls wird ein Standardsymbol angezeigt. Dies bestimmt nur die Markendarstellung, erstellt keine Anmeldesitzung und stellt der Kundenseite keine Kontoberechtigungen bereit. Aktuelle Einschränkung: Wenn bei gewöhnlichem OAuth innerhalb eines iframe eine erneute Anmeldung erforderlich ist, besteht noch eine Lücke im Ablauf, nach Abschluss der Anmeldung zur Autorisierungsseite zurückzukehren. Vor dem Go-live müssen „Auth angemeldet“ und „Auth nicht angemeldet/abgelaufen“ jeweils separat abgenommen werden. Bevor diese Lücke behoben und verifiziert ist, kann die erstmalige Anmeldung auf einer separaten Seite über Standard-OAuth erfolgen oder die nachfolgende Autorisierung über die Studio-Komponente verwendet werden; versprechen Sie nicht allein aufgrund von Tests im angemeldeten Zustand, dass alle iframe-Szenarien funktionieren.

Autorisierung mit dem aktuellen Studio-Konto verwenden

Aktivieren Sie OAuth in Studio unter „Einstellungen → Startseite → Website-Komponenten“ und geben Sie client_id sowie die registrierte Callback-Adresse ein. Website und Callback müssen dieselbe HTTPS-Herkunft verwenden und sich von der Studio-Herkunft unterscheiden. Die Drittanbieterseite muss:
  1. acedatacloud:oauth:ready an die exakte Origin der Parent-Site senden sowie acedatacloud:oauth:init empfangen und validieren.
  2. Beim Button-Klick state und PKCE verifier generieren und acedatacloud:oauth:authorize senden (state, S256 challenge); der verifier bleibt innerhalb der eigenen Seite.
  3. Parent-Fenster, Origin und state validieren, code oder error in acedatacloud:oauth:result verarbeiten und am Standard-Token-Endpunkt eintauschen. Studio zeigt die Autorisierungsseite im Komponentenbereich an; nach Zustimmung des Benutzers wird der Autorisierungscode per Nachricht zurückgegeben, die Anwendung muss nicht umleiten. Wenn keine Anmeldung besteht, wird login_required zurückgegeben, bei Ablehnung wird access_denied zurückgegeben und bei einer Wartezeitüberschreitung wird authorization_timeout zurückgegeben. Änderungen am Konto erstellen das Anwendungs-iframe neu und brechen unvollständige Autorisierungen ab.
Die Komponente fordert derzeit profile:read credentials:read an und enthält kein offline_access. Gehen Sie nicht davon aus, dass Sie zwingend ein Refresh-Token erhalten können. embed=studio und embed_origin werden vom Studio-Host und der Autorisierungsseite verwaltet; die Kundenseite muss nur das Nachrichtenprotokoll einhalten. Ein vollständiges Schaltflächenbeispiel finden Sie im OAuth-Integrationsleitfaden für Studio-Website-Komponenten.

Lebenszyklus, Aktualisierung und Widerruf

Die Standardgültigkeitsdauer des Access-Tokens beträgt 15 Tage; die Aktualisierung oder erneute Autorisierung sollte anhand von expires_in in jeder Antwort geplant werden. Das Refresh-Token gilt standardmäßig 30 Tage, die Dauer wird durch die Dienstkonfiguration beeinflusst. Codieren Sie diese beiden Werte nicht als dauerhafte Zusagen fest. Nach Genehmigung von offline_access kann Folgendes aufgerufen werden:
Die Aktualisierung gibt neue Token zurück, und die Anwendung sollte die neuesten Werte speichern. Bei der Aktualisierung wird geprüft, ob die Anwendung weiterhin gültig ist, der Benutzer verfügbar ist und die Berechtigungen weiterhin genehmigt sind. Löschen Sie bei einem Fehler Ihren eigenen Verbindungsstatus und autorisieren Sie erneut. Die aktuelle OAuth-Aktualisierungsimplementierung garantiert nicht, dass das alte Refresh-Token unmittelbar nach der Aktualisierung ungültig wird. Betrachten Sie den Erhalt eines neuen Tokens nicht als Widerruf des alten Tokens und ersetzen Sie die Beendigung bestehender Token nicht durch die Rotation eines Secrets. Der Widerrufsaufruf erfolgt wie folgt:
Der aktuelle Widerrufs-Endpunkt gibt HTTP 200 zurück, implementiert jedoch keine sofortige Ungültigkeit bereits ausgestellter JWTs. Die Anwendung sollte die von ihr gespeicherten Token löschen und darf 200 nicht als Nachweis dafür ansehen, dass alle ausgestellten Token oder API Keys ungültig sind. Betroffene Anmeldedaten für offengelegte oder kopierte API Keys müssen separat widerrufen oder rotiert werden.

Häufige Fehler und Abnahme

Validieren Sie vor der Auslieferung mindestens: korrekten Rückruf, Ablehnung, fehlerhaften State, abgelaufenen/bereits verwendeten Code, keinen Key, Netzwerkausfall, abgelaufenes Token, fehlenden erforderlichen Scope sowie die erste Anmeldung und den Kontowechsel im iframe-Szenario. Speichern Sie in den Testnachweisen keine vollständigen Codes, Token oder API Keys.

Zwei-Schritt-Verifizierung und erneute Autorisierung

Nachdem ein Benutzer die Zwei-Schritt-Verifizierung aktiviert hat, führt Ace Data Cloud auf der Autorisierungsseite die Prüfung des Authenticator-Codes oder eines einmaligen Wiederherstellungscodes durch und liefert anschließend den Autorisierungscode aus. Ihre Anwendung verwendet weiterhin den Standard-OAuth-Ablauf und darf Benutzer nicht auffordern, Authenticator-Schlüssel oder Wiederherstellungscodes bereitzustellen, speichern oder weiterzuleiten. Nachdem ein Benutzer die Zwei-Schritt-Verifizierung aktiviert, ändert, deaktiviert oder sein Konto wiederherstellt, können die vorherigen Kontositzungen, Refresh-Token und zugehörigen Plattform-Autorisierungstoken ungültig werden. Starten Sie bei einer ungültigen Sitzung oder bei invalid_grant erneut einen für den Benutzer sichtbaren Autorisierungsablauf, verwenden Sie alte Autorisierungscodes nicht wiederholt und versuchen Sie nicht, die Verifizierung zu umgehen. Die Authentifizierungsmethode für gewöhnliche Modell-API-Keys bleibt unverändert; bei Verdacht auf eine Kontoübernahme sollten die betroffenen API Keys separat geprüft und widerrufen werden.