CloudCenter-API

cloud center API

 Einleitung

In diesem Thema findest du allgemeine Informationen zur cloud center-API, dem Funktionsumfang sowie zu den Kenntnissen, die hilfreich beim Verwenden der API-Funktionen sind.

 Funktionsumfang von d.velop cloud center

Das d.velop cloud center ist die Self-Service-Oberfläche für die d.velop cloud. App Builder können hier ihre Apps registrieren und verwalten, sodass Endkunden diese für ihre d.velop cloud buchen können.

 Technische Hintergrundinformationen

Das cloud center ist ein Tool, welches über das Internet mit deiner App kommuniziert. Daher solltet du dich als App Builder mit folgenden Webtechnologien auskennen: - HTTPS - RESTful - JSON

Damit die Kommunikation zwischen dem cloud center und deiner App abgesichert ist, sollten dir die Hash-Funktion SHA256 und der Authentifizierungscode HMAC bekannt sein.

In den nachfolgenden Kapiteln erfährst du mehr über das App Secret sowie den Signaturprozess. Das App Secret und der Signaturprozess stellen sicher, dass die Kommunikation zwischen deiner App und dem cloud center abgesichert ist.

 Grundlegendes zum App Secret

Das App Secret besteht aus zufällig zusammengestellten Bytes, welche in einen Base64-String umgewandelt wurden. Bevor du das App Secret verwenden kannst, musst du den Base64-String in Bytes umwandeln (decodieren). Viele Programmiersprachen besitzen Bibliotheken, die das Umwandeln für dich übernehmen.

Das App Secret wird zur Absicherung der Kommunikation des Mandanten mit deiner App verwendet (siehe Mandanten Header). Zudem wird es auch zur Absicherung der Events verwendet, die vom cloud center gesendeten wurden.

Nach der Erstellung der App im cloud center siehst du das App Secret als Base64-String im Klartext auf der Bearbeitungsseite deiner App im Bereich technische Details. Du solltest als erstes das App Secret kopieren und in deiner App hinterlegen. Nach der ersten Änderung wird dein App Secret nurnoch verschlüsselt dargestellt. Solltest du vergessen haben, das App Secret zu kopieren, kannst du dir jederzeit im Bereich technische Details ein neues App Secret erstellen lassen. Wechsle dazu in den Bearbeitungsmodus und wähle die Schaltfläche Neues Secret generieren aus. Im folgenden Dialog kannst du dir ein neues App Secret erzeugen lassen. Kopiere das App Secret und hinterlege es in deiner App, da deine App sonst nicht mehr erreichbar ist.

 Grundlegendes zum Signaturprozess

Um sicherzustellen, dass eine eintreffende Anfrage vom d.velop cloud center stammt, musst du in deiner App die Signatur auf Gültigkeit prüfen. Dazu erstellst du nach dem gleichen Prozess die Signatur basierend auf dem App Secret, welches nur dir und dem d.velop cloud center bekannt ist. Stimmt deine berechnete Signatur mit der aus der Anfrage überein, kannst du dir sicher sein, dass die Anfrage vom d.velop cloud center gesendet wurde.

Anfrage Header

Folgende Header müssen bei der Anfrage des cloud centers an deine App angeliefert werden:

  • Authorization: Bearer Token mit der berechneten Signatur in hexadezimaler Schreibweise.
  • x-dv-signature-headers: Kommaseparierte Liste (ohne Leerzeichen) aller für die Signatur genutzten Header-Namen in Kleinbuchstaben. Die Auflistung enthält auch den eigenen Header-Namen.
  • x-dv-signature-algorithm: Für die Signatur verwendeter Algorithmus. Zur Zeit steht dort DV1-HMAC-SHA256.
  • x-dv-signature-timestamp: Zeitstempel in UTC-Zeit nach ISO 8601 (Format: "yyyy-MM-ddTHH:mm:ssZ", z.B.: 2019-08-23T08:49:42Z).

 Implementation des Signaturprozesses

Im folgenden erfährst du anhand eines Beispiels mehr über die notwendigen Schritte im Signaturprozess.

Verwendetes App Secret:


    Rg9iJXX0Jkun9u4Rp6no8HTNEdHlfX9aZYbFJ9b6YdQ=

Beispielname deiner App:


    myapp

Verwendeter Payload/Anfrage Body:


    {"type":"subscribe","tenantId":"id","baseUri":"https://someone.d-velop.cloud"}\n

Hinweis

Beachte das dem Body angehängte "\n". Von einigen Parsern wird dieses entfernt, was einen falschen Hashwert zur Folge hat.

Verwendeter Zeitstempel:


    2019-08-09T08:49:42Z

 Sortieren und Normalisieren der Header

Es werden alle unter x-dv-signature-headers angegebenen Header alphabetisch sortiert. Zur weiteren Verarbeitung werden die Header nach folgemdem Muster aneinandergereiht:

Schema:


    Lowercase(header1) + ":" + Trim(value1) + "\n" +
    Lowercase(header2) + ":" + Trim(value2) + "\n" +
    ...
    Lowercase(headerN) + ":" + Trim(valueN) + "\n"

Beispiel


    "x-dv-signature-algorithm:DV1-HMAC-SHA256\nx-dv-signature-headers:x-dv-signature-algorithm,x-dv-signature-headers,x-dv-signature-timestamp\nx-dv-signature-timestamp:2019-08-09T08:49:42Z\n"

 Normalisierung der Anfrage

In diesem Schritt werden die Bestandteile der Anfrage in normalisierter Form mit einem Zeilenumbruch als Trennzeichen aufgelistet. Außerdem wird ein SHA256-Hash über den Payload gebildet, welcher ebenfalls angehangen wird. Mehr Informationen zur Bildung des Hashwertes findest du im nächsten Abschnitt.

Schema:


    HTTP-Verb            + "\n" +   // GET, PUT, POST...
    Pfad der Resource    + "\n" +   // With leading slash
    Querystring          + "\n" +   // Without ?, urlencoded
    Headers              + "\n" +   // Normalized header string
    SHA256(Payload)                 // SHA256-Hash of request body as hex value

Beispiel


   "POST\n/myapp/dvelop-cloud-lifecycle-event\n\nx-dv-signature-algorithm:DV1-HMAC-SHA256\nx-dv-signature-headers:x-dv-signature-algorithm,x-dv-signature-headers,x-dv-signature-timestamp\nx-dv-signature-timestamp:2019-08-09T08:49:42Z\n\nc2a6fefc93b809eeaf2f069504fe8e02b0f3341b3c5e488e6a402ca45301415c"

 Bilden eines Hashwerts in Hexadezimal

Verwende zum Erstellen der Hash-Werte den Hash-Algorithmus SHA256 und die Bibliothek der jeweiligen Programmiersprache. Zum Bilden des Hashwertes wird zuerst ein SHA-256-Hash aus dem normalisierten Anfrage-String berechnet. Der Hash wird anschließend in einen Hexadezimalwert mit Kleinbuchstaben umgewandelt.

Beispiel


    fcecaac3dae4d40d6f2a065678f59f4794dfbe8497fe9ca825f737299887ebf4

 Berechnen der Signatur

Aus dem berechneten hexadezimalen Anfrage-String und dem App Secret wird nun mittels HMAC-SHA-256-Verfahren eine Prüfsumme berechnet. Das Ergebnis wird wiederum in einen Hexadezimalwert mit Kleinbuchstaben umgewandelt.

Hinweis

Das App Secret ist Base64 kodiert und muss vor der Verwendung wieder dekodiert werden.

Beispiel


    02783453441665bf27aa465cbbac9b98507ae94c54b6be2b1882fe9a05ec104c

 Prüfen der Signatur

Die Prüfung der Signatur besteht aus zwei Teilen. Mithilfe des Zeitstempels im Header x-dv-signature-timestamp siehst du, ob die Anfrage aktuell ist. Der Zeitstempel bezieht sich auf die UTC-Zeit beim Absenden der Anfrage an deine App. Um Zeitdifferenzen zwischen Servern auszugleichen, sind Anfragen für den Zeitraum von 5 Minuten vor bzw. 5 Minuten nach dem angegebenen Zeitstempel gültig. Wenn die angegebene Zeit außerhalb des Zeitfensters ist, muss die Signatur als ungültig betrachtet und die Anfrage mit dem HTTP-Status "403 Forbidden" abgelehnt werden. Durch anwenden des beschriebenen Signaturprozesses berechnet die App nun eine Vergleichssignatur. Stimmt die berechnete Signatur nicht mit dem hexadezimalen Wert aus dem Authorization-Header überein, so ist die Anfrage ebenfalls mit dem HTTP-Status "403 Forbidden" abzulehnen.

Hinweis

Entferne vor dem Vergleich das Wort "Bearer", um den reinen hexadezimalen Wert zu erhalten.

 Verwenden der API-Funktionen

Das cloud center stellt eine API-Schnittstelle zur Verfügung, mit der du beispielsweise sehen kannst, wann deine App gebucht wurde.

 Grundlegendes zu den Ereignissen des App-Lebenszyklus

Damit du weißt, wann deine App beispielsweise von einem Kunden gebucht wurde, veröffentlicht das cloud center vier Ereignistypen (subscribe, unsubscribe, resubscribe und purge), die nachfolgend beschrieben werden. Was du tun musst, um diese Ereignisse zu Empfangen und zu verarbeiten, erfährst du im Kapitel "Empfangen von Ereignissen".

Image of lifecycle-events

In manchen Fällen wird ein Ereignis mehrfach an deine App gesendet, z.B. wenn ein Kunde eine App bucht, die abhängig von deiner App ist. Daher musst du immer vorher prüfen, ob du das Ereignis bereits erhalten hast. Wenn du das Ereignis noch nicht erhalten hast, musst du es dem Ereignistypen entsprechend behandeln.

 Ereignistyp "subscribe"

Du empfängst dieses Ereignis sobald ein Kunde deine App bucht. Je nach Funktion deiner App ist eine Initialisierung deiner App notwendig. Beispielsweise, wenn du kundenspezifische Informationen in deiner Datenbank speichern musst.

 Ereignistyp "unsubscribe"

Das unsubscribe-Ereignis erhältst du, wenn der Kunde deine App nicht mehr verwenden möchte und kündigt. Dies ist für dich erstmal nur ein Hinweis darauf, dass deine App vom Kunden nicht mehr genutzt wird. Sobald das unsubscribe-Ereignis gesendet wurde, ist deine App nicht mehr in der d.velop cloud des Kunden verfügbar. Der Kunde kann daher nicht mehr mit deiner App interagieren. Auf keinen Fall darfst du die Daten des Kunden löschen (siehe: Eventtyp purge).

 Ereignistyp "resubscribe"

Das resubscribe-Ereignis empfängst du, falls ein Kunde sich nach dem Kündigen umentscheidet und deine App doch weiter verwenden möchte.

 Ereignistyp "purge"

Nachdem ein Kunde die App gekündigt hat und die Karrenzzeit abgelaufen ist, empfängt deine App das purge-Ereignis. Dieses Vorgehen schützt den Kunden vor einer vorzeitigen Löschung seiner Daten, nachdem er gekündigt hat. Sobald du dieses Ereignis empfängst musst du alle Daten des Kunden löschen. Welche Daten du löschen musst, kannst du dem Ereignis entnehmen.

 Empfangen von Ereignissen

In diesem Abschnitt erhältst du Informationen zu den Voraussetzungen für den Empfang von Ereignissen.

HTTP-Anfrage

Deine App muss eine Ressource namens "dvelop-cloud-lifecycle-event" zur Verfügung stellen.

Die Anfrage vom cloud center sieht wie folgt aus:


   POST  https://myapp1.example.com/myapp1/dvelop-cloud-lifecycle-event
   Content-Type: application/json

Event Body

Die Anfrage des cloud centers enthält nachfolgenden Body in Form eines JSON-Dokuments.

  • "type": Enthält den jeweiligen Eventtypen. Je nachdem welcher Type gesendet wurde, muss deine App entsprechende Aktionen ausführen.
  • "tenantId": Dies ist die eindeutige Identifikationsnummer der d.velop cloud des Kunden.
  • "baseUri": Unter dieser Adresse ist die d.velop cloud des Kunden erreichbar. Die BaseUri wird immer absolut und ohne Slash am Ende mitgeliefert.

Beispiel


{
    "type": "subscribe",
    "tenantId": "xyz",
    "baseUri": "https://mandant.d-velop.cloud"
}

 Überprüfen der Ereignisse

Damit du sicherstellen kannst, dass die Anfrage wirklich vom cloud center kommt, ist die Anfrage mit dem beschriebenen Signatur-Mechanismuses abgesichert. Sobald du ein Ereignis empfängst, musst du prüfen, ob die Anfrage richtig signiert ist (siehe Grundlegendes zum Signaturprozess).

 Abhängigkeiten zu anderen Apps

Eine App kann Abhängigkeiten zu anderen Apps haben. Wenn ein Kunde eine App bucht wird sichergestellt, dass alle Abhängigkeiten bereits gebucht sind oder automatisch mit gebucht werden.

Abhängigkeiten sind für folgende Use Cases vorgesehen.

  • Bundle – Man möchte mehrere Apps gleichzeitig bereitstellen, um sie z.B. dem Kunden als Produktvariante zu verkaufen. Dafür erstellt man eine App, die selbst keine Funktionen hat. Dort fügt man alle Apps, die gleichzeitig bereitgestellt werden sollen, als Abhängigkeit hinzu. Da die App selbst keine Funktionen hat, kann man die Einstellung für die Berechtigungsstufe an den Abhängigkeiten auf dem Standard Wert "Keine" belassen.
  • Technische Abhängigkeit – Man möchte den API Endpunkt einer anderen App nutzen, um z.B. Dokumente aus der DMS-App abzurufen. Dafür fügt man die App, die den API Endpunkt bereitstellt, als Abhängigkeit hinzu. Damit der API Endpunkt verwendet werden kann, muss man die Einstellung für die Berechtigungsstufe an der Abhängigkeit entsprechend setzen (siehe Berechtigungsstufen).

 Berechtigungsstufen

Berechtigungsstufen steuern die Art des Zugriffs auf die Abhängigkeit. Hier sollte das Least-Privilege-Prinzip verfolgt werden.

BerechtigungsstufeErklärung
KeineAlle API Aufrufe deiner App in Richtung der Abhängigkeit werden blockiert.
LesendEs werden nur lesende Operationen deiner App in Richtung der Abhängigkeit erlaubt.
Erlaubte HTTP-Methoden sind: GET, OPTIONS, HEAD.
Lesend und schreibendLesende und schreibende Operation deiner App in Richtung der Abhängigkeit sind erlaubt.
Zusätzlich zu lesenden HTTP-Methoden sind auch folgende HTTP-Methoden erlaubte: POST, PUT, PATCH, DELETE.

 Benutzung

Um eine Abhängigkeit deiner App hinzuzufügen, musst du zunächst über deinen Anbieter-Account zu deiner App navigieren. Navigiere auf der App-bearbeiten-Seite zur Rubrik "Abhängigkeiten". Hier kannst du weitere Abhängigkeiten hinzufügen. Über das Bearbeiten einer Abhängigkeit kannst du die Zugriffsberechtigung deiner App auf die Abhängigkeit anpassen oder auch die Abhängigkeit entfernen.

Hinzufügen, entfernen und ändern einer Abhängigkeit sind nur so lange möglich, wie deine App noch nicht freigegeben ist. Sobald deine App den Freigabeprozess durchlaufen hat und deine App freigegeben ist, sind keine Änderungen der Abhängigkeiten mehr möglich. Sollte eine Änderung erforderlich sein, kontaktiere bitte deinen zuständigen Solutions Architect bei der d.velop AG.