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"}

 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.

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/d-velop-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\ndb5142ec6d2cd31ee985e7729b764546f29e187990d0f113720f90bab265311f"

 Bilden eines Hashwerts in Hexadezimal

Verwende zum Erstellen der Hash-Werte den Hash-Algorithmus HMAC 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

   
    edcf568f1bd446ec93a56189bcd22b96d8566be54c2b6c15c24089b87308f87e

 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.

Beispiel

   
    baa8415d308089d654530849e9c42afd1c1996fd8871a7e0dcf32672d215cf59

 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

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.