Eine eigene Anwendung anbinden

Wenn Sie eine eigene Anwendung oder ein eigenes Werkzeug an die Documents Partner API anbinden wollen, brauchen Sie dafür eine Applikation in der Benutzerverwaltung Ihres Mandanten. Diese Anleitung führt Schritt für Schritt durch die Anlage.

Zu den Abbildungen. Sie stammen aus einer Testumgebung. Der Mandantenname und die Namen der handelnden Personen sind geschwärzt; an ihrer Stelle steht bei Ihnen der eigene Mandant. Die gezeigte Client-Kennung gehört zu einer Testapplikation und ist nur ein Beispiel für das Format.

⚠️ Das setzt die Volllizenz voraus. Nur sie schließt im Regelfall das Recht ein, eigene Applikationen zu registrieren. Mit einer partnergebundenen Lizenz ist der Zugang an das jeweilige Partnerprodukt geknüpft, und eine selbst angelegte Applikation würde mit 403 CLIENT_NOT_LICENSED abgewiesen. Der Unterschied steht in Lizenzen und Berechtigungen.

Maßgeblich ist Ihr Vertrag – er kann im Einzelfall abweichende Regelungen enthalten. Wenn Sie unsicher sind, ob dieser Weg für Ihre Kanzlei offensteht, klären Sie das vorher mit Ihrem Ansprechpartner bei STP.

Was Sie dabei erhalten – und was nicht

Dass die Client-Kennung erzeugt wird, ist der Punkt, der am ehesten überrascht: Sie können sie nicht bestimmen. Die Anwendung muss die erzeugte GUID übernehmen.

STP-Administratoren sehen die von Ihnen angelegten Applikationen ebenfalls – hilfreich, wenn Sie beim Support nachfragen.

Sie sind Partner und wollen Ihr Produkt mehreren Kanzleien anbieten? Dann ist dieser Weg nicht der richtige – eine mandantenspezifische Applikation gilt nur für einen einzigen Mandanten. Ein Client, der bei allen lizenzierten Kanzleien funktioniert, wird zentral von STP registriert; wenden Sie sich dafür an den STP-Support.

Schritt eins: Zur Applikationsübersicht

Melden Sie sich als Administrator Ihres Mandanten an und öffnen Sie Identity Admin. In der linken Leiste finden Sie den Eintrag Applikationen.

Die Liste ist zu Beginn leer („keine Applikationen“). Rechts oben legt „+ neue Applikation“ eine an.

Schritt zwei: Grunddaten und Verhalten

Tragen Sie zunächst den Anzeigenamen ein – er erscheint später auf der Zustimmungsseite, sollte für Ihre Anwender also verständlich sein. Im Beispiel oben ist das Mein Test Client.

Darunter stehen die Schalter. Diese müssen gesetzt sein:

⚠️ Ohne „Benutzer Xid-Eigenschaft“ scheitert später jeder Aufruf. Die Sitzung im Dokumentenmanagement wird im Namen des anfragenden Benutzers geführt, und dessen Kennung kommt genau aus dieser Eigenschaft. Fehlt sie, läuft die Anmeldung fehlerfrei durch, und trotzdem antwortet jeder Fachaufruf mit 403 MISSING_USER_IDENTITY – ein Fehlerbild, das ohne diesen Hinweis kaum zu deuten ist.

Diese Schalter bleiben leer:

Die Felder „Aktualisierungsmarkenlänge in Bytes“ und „linker Bereich URI“ bleiben leer. Bei ersterem warnt die Oberfläche zu Recht – zu wenige Bytes führen zu Kollisionen.

Die Laufzeiten darunter können Sie unverändert lassen. Die Vorgabewerte:

Schritt drei: Gewährungsart

Unter zulässige Gewährungsarten wählen Sie Authorization Code.

Für die Documents Partner API ist das die einzige freigeschaltete Wahl – und das ist kein Versehen: Die Anwendung handelt im Namen eines Benutzers, und nur dieser Ablauf bringt eine Benutzerkennung mit. Ein Ablauf ohne Benutzeranmeldung würde an derselben Stelle scheitern wie eine fehlende Xid-Eigenschaft.

Schritt vier: Berechtigungsbereiche

Unter erlaubte Bereiche wählen Sie aus, was die Anwendung anfordern darf. Für die Documents Partner API sind das:

Eine reine Auswertungsanwendung kommt ohne documents.write und uploads aus. Alles, was Dokumente ablegen soll, braucht beide.

Warum dms.cloud.api.standalone nicht weggelassen werden darf

Jeder Aufruf wird gegen zwei Arten von Bereichen geprüft: den fachlichen und den Lizenzbereich. Fehlt der Lizenzbereich, wird schon abgewiesen, bevor der fachliche überhaupt betrachtet wird – mit 403 LICENSE_MISSING.

Für eine selbst angelegte Applikation ist dms.cloud.api.standalone der einzige Lizenzbereich, der zur Auswahl steht – die partnergebundene Variante gehört zum jeweiligen Partnerprodukt.

Ohne diesen Bereich ist die Applikation also vollständig eingerichtet und trotzdem bei jedem Aufruf abgewiesen. Die Prüfreihenfolge im Einzelnen steht in Lizenzen und Berechtigungen.

Schritt fünf: Client-Geheimnis

Der Schalter „bedarf eines Client Geheimnisses“ ist für mandantenspezifische Applikationen Pflicht – er bleibt gesetzt. Legen Sie darüber unter „Vorher vereinbartes Geheimnisse“ mit Neu ein Geheimnis an.

Ihre Anwendung muss es also sicher aufbewahren können. Für eine reine Browseranwendung, die das nicht kann, ist dieser Weg nicht geeignet – dort gehört die Anmeldung auf einen Server Ihrer Seite, der das Geheimnis hält.

Das Geheimnis wird nur einmal im Klartext angezeigt. In der Tabelle sehen Sie danach nur noch den Hashwert in der Spalte Value; Value (unhashed) bleibt leer. Notieren Sie das Geheimnis sofort an einem sicheren Ort – es lässt sich nicht wieder sichtbar machen, nur löschen und neu anlegen.

Die zweite Tabelle, Zertifikat Geheimnisse, bleibt leer. Sie wird für die Documents Partner API nicht benötigt.

Schritt sechs: Adressen

Zuletzt die Adressen Ihrer Anwendung:

Die Adressen müssen exakt mit dem übereinstimmen, was Ihre Anwendung beim Anmelden angibt – einschließlich Schema, Port und abschließendem Schrägstrich.

Ein Server-Dienst ohne Browseroberfläche braucht keine CORS-Herkunft.

Mit Speichern ist die Applikation angelegt.

Änderungen wirken nicht sofort. Die Oberfläche weist selbst darauf hin: Es kann bis zu 15 Minuten dauern, bis eine Änderung greift. Wenn direkt nach dem Speichern noch etwas nicht funktioniert, lohnt sich zuerst Abwarten und ein erneuter Versuch.

Schritt sieben: Die Client-Kennung übernehmen

In der Liste steht die Applikation nun mit ihrer erzeugten Client-Kennung – einer GUID wie 303be097-b510-4436-95ac-f804f8933439. Daneben stehen Inhaber (Ihr Mandant) und Schöpfer (wer sie angelegt hat). Darunter zeigt die Übersicht die vergebenen Bereiche, zum Beispiel:

"dms.cloud.api.documents.read" "dms.cloud.api.documents.write"
"dms.cloud.api.standalone" "dms.cloud.api.uploads"
"email" "openid" "profile" "um.acc.profile.read"

Diese GUID ist die client_id, die Ihre Anwendung beim Anmelden verwendet. Zusammen mit dem Mandantennamen haben Sie damit alles, was Erste Schritte für den Anmeldeablauf beschreibt.

Schritt acht: Die Anmeldung durchführen

Mit der Client-Kennung ist der Ablauf derselbe wie für jede andere Anwendung. Die Endpunkte stehen unter der Anmeldeadresse Ihres Mandanten:

https://<mandant>.stp-cloud.de/identity/.well-known/openid-configuration

Die Subdomain muss der Mandant sein, zu dem das handelnde Benutzerkonto gehört – bei authorize und bei token. Ein Aufruf gegen einen anderen Mandanten schlägt fehl, auch wenn Client-Kennung und Geheimnis stimmen.

Erstens: Den Benutzer zur Anmeldung schicken

GET https://<mandant>.stp-cloud.de/identity/connect/authorize
      ?client_id=303be097-b510-4436-95ac-f804f8933439
      &redirect_uri=http%3A%2F%2Flocalhost%3A5099%2Fcallback
      &response_type=code
      &scope=*
      &state=<eigener-Zufallswert>
      &code_challenge=<BASE64URL-SHA256-des-Verifiers>
      &code_challenge_method=S256

Nach der Anmeldung und der Zustimmung wird der Benutzer an die Rückleitungsadresse geschickt, die code und state als Abfrageparameter trägt.

scope=* ist der empfohlene Weg. STP-IAM beantwortet eine Wildcard – ebenso einen leeren scope – mit allen Bereichen, die die Applikation anfordern darf. Was tatsächlich im Token landet, ist ohnehin die Schnittmenge mit Lizenz und Rollen.

Der Grund, das einer festen Liste vorzuziehen: Ein Anmeldedienst lässt die gesamte Anfrage mit invalid_scope scheitern, wenn auch nur ein einziger genannter Bereich unbekannt ist. Eine fest verdrahtete Liste ist damit eine Umbenennung davon entfernt, die Anmeldung komplett lahmzulegen. Eine ausdrückliche Liste ist nur dann sinnvoll, wenn eine Anwendung bewusst weniger anfordern soll, als sie dürfte.

Zweitens: Den Code gegen ein Token tauschen

POST an den Token-Endpunkt, Inhalt als application/x-www-form-urlencoded:

curl -sS -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=$CODE" \
  -d "client_id=303be097-b510-4436-95ac-f804f8933439" \
  -d "redirect_uri=http://localhost:5099/callback" \
  -d "code_verifier=$CODE_VERIFIER" \
  -d "client_secret=$CLIENT_SECRET" \
  "https://<mandant>.stp-cloud.de/identity/connect/token"

Zwei Punkte, an denen dieser Aufruf regelmäßig scheitert:

• code_verifier ist Pflicht, sobald PKCE gesetzt ist – und das ist es hier. Der Anmeldedienst prüft ihn gegen die zuvor gesendete code_challenge. Ohne ihn wird der Tausch abgelehnt, obwohl code und Geheimnis stimmen.
• client_secret gehört hier immer dazu. Mandantenspezifische Applikationen sind stets vertraulich, also erwartet der Anmeldedienst das Geheimnis. (Nur bei einem öffentlichen Client – den es auf diesem Weg nicht gibt – entfiele das Feld ersatzlos; leer mitschicken wäre auch dann falsch.)

Der weitere Ablauf – Erneuerung über grant_type=refresh_token, Inhalt des Tokens – steht in Erste Schritte.

Schritt neun: Der erste Aufruf

Die Schnittstelle liegt unter demselben Mandanten:

https://<mandant>.stp-cloud.de/documents/dms-cloud-api/api

Die Versionsangabe gehört nicht in die Basisadresse, sondern an den Anfang jedes Pfades. Der erste Aufruf sollte eine Suche sein – sie beweist die ganze Kette vom Token über die Lizenz bis in das Dokumentenmanagement:

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Correlation-Id: mein-erster-aufruf" \
  "https://<mandant>.stp-cloud.de/documents/dms-cloud-api/api/v1/dms/documents/container?pageSize=5"

Kommt eine Liste zurück – und sei sie leer –, funktioniert die Integration. Wie es von dort weitergeht, zeigt Schnellstart.

Wenn stattdessen ein Fehler kommt

Die vollständige Liste steht in Fehlercodes.

Was Sie danach noch brauchen

Die Applikation allein genügt nicht – sie legt nur die Obergrenze fest. Es fehlen noch:

1. Die Rolle für die handelnden Benutzerkonten. Ohne sie fehlt im Token der fachliche Bereich, und der Aufruf endet mit 403 INSUFFICIENT_SCOPE – siehe Rollen und Gruppen.
2. Ein installierter und angemeldeter Connector, sonst antwortet jeder Aufruf mit 502 CONNECTOR_OFFLINE.

Was tatsächlich im Token landet, ist die Schnittmenge aus dem, was die Applikation anfordern darf, was die Lizenz hergibt und was die Rollen des Benutzers hergeben. Ein Bereich, der in der Applikation fehlt, kommt nie an – ganz gleich wie gut lizenziert und berechtigt der Benutzer ist.

Weiterführend

• Schnellstart – die Aufrufe im Einzelnen, mit curl und C#
• Rollen und Gruppen
• Lizenzen und Berechtigungen
• Fehlercodes