Freischaltung

Freischaltungsprozess beim Kunden

Im Folgenden wird der Freischaltungsprozess eines Services beschrieben. Um einen Marketplace-Service nutzen zu können, müssen Kunden diesen zunächst freischalten.

Wählt der Benutzer einen Anbieter über „Marketplace > Übersicht“ aus, der noch nicht freigeschaltet ist, öffnet sich ein Pop-up für die Freischaltung. Die Freischaltung ist nur für Administratoren des onOffice-Mandanten (d.h. der Kundenversion) möglich.

Dem Benutzer wird folgende Maske angezeigt:

Freischaltung

  1. „Zum Anbieter“ zeigt eine Beschreibung Ihres Unternehmens und Ihrer Services. Unter „Beschreibung der freizugebenden Rechte“ werden die Rechte beschrieben, die der Benutzer Ihnen einräumen muss. Damit ist dem Benutzer bewusst, auf welche Daten zugegriffen wird.
  2. Unter „Bestätigungen“  bestätigt der Benutzer Ihre Auftragsverarbeitungsvereinbarung (AVV), allgemeinen Geschäftsbedingungen (AGB) und die Datenschutzerklärung.
  3. Unter „Benutzerrecht aktivieren“ muss der Benutzer bewusst entweder „alle Benutzer“ oder „alle Administratoren“ einstellen, damit die Freischaltung durchgeführt werden kann. Administratoren haben immer Zugriff. Bei Marketplace-Anbietern, die genau EINEN Service per Webhook anbieten, ist diese Auswahl deaktiviert und „alle Benutzer“ ist vorausgewählt.
  4. Abschließend klickt der Benutzer auf „Freischalten”. Mit dem Klick auf „Freischalten“ sendet onOffice enterprise im Hintergrund einen verschlüsselten POST-Request an die vom Anbieter hinterlegte URL (Remote Site). Dieser Request enthält alle notwendigen Daten inklusive des API-Keys (Secrets).

Anforderungen an den Aktivierungs-Endpunkt

Den POST-Request zur Freischaltung sendet onOffice nicht über den Browser des Benutzers, sondern direkt von Server zu Server an die von Ihnen hinterlegte URL. Damit dieser Aufruf Ihre Anwendung erreicht, muss Ihr Endpunkt für die Freischaltung (Aktivierungs-Endpunkt) folgende Anforderungen erfüllen:

  • Öffentlich erreichbar: Der Endpunkt muss öffentlich aus dem Internet per Server-to-Server-POST erreichbar sein. URLs, die nur intern, per VPN oder lokal erreichbar sind (z. B. Test- oder Intranet-Umgebungen), kann onOffice nicht aufrufen.
  • Kein vorgeschalteter Zugriffsschutz: Der Aufruf darf nicht durch Login-Seiten, Zugriffsschutz oder andere vorgeschaltete Mechanismen abgefangen werden – z. B. durch einen Passwortschutz per HTTP-Authentifizierung, einen Wartungsmodus oder einen Bot- bzw. Captcha-Schutz. Die Echtheit des Aufrufs prüfen Sie stattdessen anhand von Timestamp und Signatur.
  • Gültiges SSL-Zertifikat inklusive vollständiger Zertifikatskette: Der Endpunkt muss über HTTPS ein gültiges SSL-Zertifikat ausliefern (nicht abgelaufen, für die aufgerufene Domain ausgestellt, nicht selbstsigniert) – einschließlich der vollständigen Zertifikatskette, also aller Zwischenzertifikate (Intermediate Certificates).
  • Keine Weiterleitung auf eine HTML-Seite: Der Endpunkt darf keine Weiterleitung auf eine HTML-Seite zurückgeben, z. B. auf eine Login-, Fehler- oder Startseite. Er muss mit der erwarteten JSON-Antwort antworten (siehe Benutzer-Feedback). Hinterlegen Sie daher am besten direkt die endgültige URL Ihres Endpunkts.

Hinweis zur Fehlersuche: Wird der Aufruf durch einen vorgeschalteten Zugriffsschutz abgefangen oder ist die Zertifikatskette fehlerhaft, bricht die Verbindung ab, bevor der eigentliche HTTP-Aufruf Ihre Anwendung erreicht. In Ihren Logs ist dann keine Anfrage zu sehen. Prüfen Sie in diesem Fall zuerst die oben genannten Anforderungen.

Tipp: Testen Sie Ihren Endpunkt vorab mit einem POST-Request von einem externen Server aus, z. B. mit curl. Ein Aufruf im Browser reicht als Test nicht aus: Browser ergänzen fehlende Zwischenzertifikate häufig selbst, sodass eine unvollständige Zertifikatskette dort nicht auffällt.

Aufbau der Iframe-URL zur Freischaltung

Der Ablauf bei der Freischaltung als Sequenzdiagramm:

Sequenzdiagramm Ablauf Freischaltung

Aufbau des Requests zur Freischaltung

Der Aufruf zur Freischaltung erfolgt als POST-Request an Ihren Endpunkt. Da Request-Bodys durch TLS verschlüsselt sind, sind diese nicht für potenziell böswillige Dritte einsehbar. Der Content-Type des Requests ist multipart/form-data.
Beim Senden des Requests werden Daten zur Identifikation des Kunden sowie für die Authentifizierung übertragen:
  • apiClaim: Parameter für künftige API-Aufrufe.
  • apiToken: Das Token zur Authentifizierung.
  • customerName: Name des Mandanten / der Kunderversion. Ein Mandant ist eine Instanz der onOffice-Software, die viele Benutzer haben kann. Oft sind Mandanten Maklerbüros und Benutzer die Makler.
  • customerWebId: WebID des Mandanten (identifiziert die Kundenversion eindeutig).
  • parameterCacheId: Eine interne Parameter-Cache-ID.
  • secret: Der API-Key als String.
  • timestamp: Zeitstempel.
  • userId: UserID des Benutzers (identifiziert zusammen mit der WebID eindeutig einen Kunden).
  • signature: Signatur zur Verifizierung des Aufrufs.

Timestamp

Damit sichergestellt ist, dass der Aufruf über onOffice enterprise erfolgt, wird dem Request ein Timestamp-Parameter hinzugefügt. Der Timestamp stellt sicher, dass die Aufrufe nicht beliebig oft genutzt werden können.

Signatur

Außerdem werden alle Aufrufe von onOffice nach dem folgenden Verfahren signiert:
  1. Es werden alle POST-Felder herangezogen.
  2. Das Feld mit der Signatur (signature) wird aus den Feldern entfernt.
  3. Die verbleibenden Felder werden aufsteigend alphabetisch nach den Keys sortiert.
  4. Aus diesen sortierten Feldern wird ein Query-String gebildet (z. B. in PHP mit http_build_query()).
  5. Es wird die kanonische URL gebildet (aus Host, Port und Pfad) und der Query-String mit einem Fragezeichen (?) angehängt.
  6. Diese Zeichenkette wird über die Hash-Funktion HMAC-SHA256 mit Ihrem Anbieter-Secret verschlüsselt.
  7. Der so ermittelte Hash muss mit dem übermittelten Wert aus dem Parameter signature übereinstimmen.
Zusätzlicher Teil dieser Signatur ist ein Secret, das einmalig von Ihnen bei der Aufnahme in den Marketplace gesetzt werden muss. In Ihrem Anbieter-Mandant können Sie das Secret im Menü Marketplace >> Anbietersecret ändern eintragen und auch verändern. Das Secret muss aus mindestens 24 Zeichen bestehen sowie Groß- und Kleinbuchstaben, Zahlen und Sonderzeichen enthalten. 

Tipp: Da Parameter sich ändern, oder neue Parameter hinzukommen können, empfehlen wir, alle Parameter dynamisch auszulesen und sie zu sortieren, statt mit einer statischen, festen Liste von Parametern bei der Signaturberechnung zu arbeiten.

Beispiel

Ein Implementierungs-Beispiel für die Freischaltung finden Sie hier.

Freischaltung des Anbieters

Einleitung: Damit Ihr Service Daten in den Kundenversionen lesen und schreiben kann, wird bei der Freischaltung Ihres Dienstes automatisch ein API-Benutzer in der jeweiligen Kundenversion angelegt. Bei der Freischaltung werden ihnen API-Key und Token dieses API-Benutzers übergeben. Ihnen werden dadurch Rechte gegeben auf die onOffice-Software zuzugreifen.

Viele Dienste im Marketplace benötigen lesenden oder schreibenden Zugriff auf bestimmte Ressourcen in onOffice enterprise, um zu funktionieren. Beispiel Grundrissoptimierung: Kunde bestellt Grundriss im Marketplace für eine bestimmte Immobilie (Anbieter muss lesend auf Immobilie bzw. den Grundriss zugreifen), Anbieter erstellt Grundriss, Anbieter spielt optimierten Grundriss zurück (Anbieter muss schreibend auf Immobilie zugreifen).

Authentifizierung und Aktivitäten: Der zugehörige API-Key (Secret), das Token zur Authentifizierung und eine Parametercache-ID werden Ihnen während des Freischaltungsprozesses übergeben. Verwenden Sie den übermittelten API-Key und das Token für die weitere Kommunikation. Um den Prozess abzuschließen, müssen Sie die API-Funktion zur Freischaltung des Anbieters aufrufen (ACTION_ID_DO, unlockProvider) und den Parameter parameterCacheId übergeben. Dieser enthält die notwendigen internen Informationen aus dem Parameter-Cache (Details finden Sie in der ProvicderUnlock.php in den Code-Beispielen.

Datenspeicherung und Identifikation: Nach erfolgreichem Aufruf ist Ihr Angebot freigeschaltet. Speichern Sie die API-Zugangsdaten (API-Key und Token) sicher ab. Wichtig zur Identifikation: Eine Kundenversion wird auf technischer Ebene eindeutig über die Mandanten-ID (customerWebId) identifiziert. Da die Freischaltung einmalig für den gesamten Mandanten erfolgt, ist die Speicherung der Zugangsdaten pro customerWebId maßgeblich für die weitere API-Kommunikation.

Benutzer-Feedback: Das Ergebnis der Freischaltung teilen Sie onOffice in der Antwort auf den POST-Request mit. War die Freischaltung erfolgreich, antworten Sie mit dem HTTP-Statuscode 200 und folgender JSON-Struktur im Response-Body:

{
  "status": {
    "active": true
  }
}

Optional können Sie zusätzlich das Feld info mitsenden – es ist nicht verpflichtend:

{
  "status": {
    "active": true
  },
  "info": []
}

Empfohlen ist der Header Content-Type: application/json. Ist die Freischaltung nicht erfolgreich, geben Sie eine Fehlermeldung für den Benutzer zurück (siehe JsonResponse.php in den Code-Beispielen). Nach erfolgreicher Freischaltung wechselt der Status von „Inaktiv“ zu „Aktiv“. Beachten Sie die Anforderungen an den Aktivierungs-Endpunkt.

Beachten Sie: Sie müssen keine eigenen API-Benutzer für Ihren Service erstellen. Die API-Benutzer für Ihren Service in den Kundenversionen werden automatisch angelegt, wenn die Kunden Ihren Dienst aktivieren. Die notwendigen Informationen (API-Key und Token) werden dabei übertragen.

Beachten Sie, dass ausserdem bei jedem API-Call ein Parameter „extendedclaim“ angegeben werden muss. Bei jedem Aufruf Ihres Services durch den Kunden wird deswegen an Sie ein Parameter „apiClaim“ übergeben. Anschliessend müssen Sie diesen „apiClaim“ bei allen API-Calls wieder als Parameter „extendedclaim“ zurückliefern. Dies dient dazu, dass die Übergabe der Benutzer-ID und der Kundenversion verifiziert ist. Bitte benutzen Sie den „apiClaim“ aus dem neuesten Serviceaufrufes des Kunden. Der apiClaim bei der Freischaltung kann nur für den unlockProvider-Call genutzt werden.
Genauere Informationen dazu unter https://www.marketplacedoc.onoffice.de/api-calls.

In den Code-Beispielen finden Sie auch einen Programm-Code als Vorlage für die Implementierung des Freischaltungsprozesses.

Der Benutzer hat Ihr Angebot freigeschaltet. Ihre Services können nun über den Menüpunkt „Marketplace“ in onOffice enterprise gebucht werden. Ruft der Benutzer Ihren Service auf, wird ihm im Popup Ihr Iframe mit dem gewünschten Service-Frontend angezeigt.

Ablaufskizze - Freischaltung Anbieter