CloudCenter-API

CloudCenter-API

 Funktionsumfang des d.velop cloud centers

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 Mandanten buchen können.

 Verwenden der cloud center API

Nachfolgend erfährst du, wie du die Programmierschnittstelle des cloud centers für eigene Entwicklungen nutzen kannst.

 App Secret

Das App Secret ist ein zufällig geniertes Byte Array, welches in einen Base64 -String encodiert wurde. Bevor du das App Secret verwenden kannst, musst du den Base64-String in ein Byte Array umwandeln (decodieren). Das Decodieren von Base64-Strings ist in vielen Programmiersprachen implementiert.

Das App Secret wird verwendet um zu prüfen, ob die gestellte Anfrage wirklich von der d.velop cloud kommt (siehe Mandanten Header). Außerdem wird das App Secret zur Absicherung der Events, die das cloud center schickt und im Kapitel Event Lifecycle näher beschrieben werden, genutzt.

 Wie komme ich an mein App Secret?

Nach der Anlage der App im cloud center siehst du das App Secret als Base64-String im Klartext auf der Bearbeiten-Seite deiner App (ganz unten). Du solltest als erstes das App Secret kopieren und an einem sicheren Ort aufbewahren und in deiner App hinterlegen. Nachdem du das erste mal eine Änderung an der App gemacht hast, beispielsweise den Anzeigenamen ändern, wird das App Secret dir nur noch in Form von Sternchen angezeigt. Solltest du vergessen haben, das App Secret zu kopieren, oder solltest du es verlegt haben, kannst du aber auch jederzeit über die Oberfläche dir ein neues App Secret generieren lassen. Dieses solltest du anschließend umgehend in deiner App hinterlegen, da deine App sonst nicht mehr erreichbar ist.

 Event Lifecycle

 Grundlagen

Damit du weißt, wann deine App beispielsweise von einem Kunden gebucht wurde, veröffentlich das cloud center vier Eventtypen ("subscribe", "unsubscribe", "resubscribe", "purge"), die nachfolgend beschrieben werden. Wie du technisch die Events empfängst, wird im Kapitel Technische Umsetzung beschrieben.

Image of lifecycle-events

In seltenen Fällen kann es vorkommen, dass ein Event doppelt an deine App gesendet wird. Daher solltest du immer vorher prüfen, ob du das Event bereits erhalten hast. Hast du das Event noch nicht erhalten, ist das Event entsprechend des Eventtyp's zu behandeln.

 Eventtyp "subscribe"

Das subscribe-Event erhälst du, sobald ein Kunde deine App bucht. Sobald du dieses Event erhälst muss deine App den Mandanten initialisieren.

 Eventtyp "unsubscribe"

Das unsubscribe-Event erhälst du, wenn der Kunde deine App nicht mehr benutzen möchte und kündigt. Dies ist für dich erstmal nur ein Hinweis darauf, dass deine App vom Kunden nicht mehr genutzt wird. Als reaktion darauf kannst du den Mandanten sperren oder andere Maßnahmen ergreifen, beispielsweise dem Kunden seine Daten vorab bereitstellen. Auf keinen Fall darfst du allerdings die Daten des Kunden löschen (siehe: Eventtyp purge)!

 Eventtyp "resubscribe"

Das resubscribe-Event empfängst du, falls ein Kunde, der deine App gekündigt hat, sich umentscheidet und deine App doch weiter nutzen möchte. Dann solltest du die Daten des Kunden wiederherstellen, sodass dieser mit deiner App so weiter arbeiten kann, als ob sie nie gekündigt worden ist.

 Eventtyp "purge"

Das purge-Event wird nach einer bestimmten Karrenzzeit, nachdem das unsubscribe-Event wurde, gesendet. Empfängt deine App dieses Event können die Daten des jeweiligen Mandanten gelöscht werden, sofern die Kundendaten vorhälst.

 Technische Umsetzung

 HTTP Request

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

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

 Event Body

Der Request des cloud center's enthält nachfolgenden Body in Form eines JSON-Dokuments.

   
{
    "type": "subscribe|unsubscribe|resubscribe|purge",
    "tenantId": "Mandanten ID des Kunden",
    "baseUri": "https://mandant.d-velop.cloud"
}

PropertyBeschreibung
"type"Enthält den jeweiligen Eventtypen. Je nach dem welcher Type gesendet wurde, muss deine App entsprechende Aktionen ausführen.
"tenantId"Dies ist die eindeutige Identifikationsnummer des Kundenmandanten. Diese ist einmalig.
"baseUri"Unter dieser Adresse ist der Mandant des Kunden erreichbar. Die BaseUri wird immer absolut und ohne Slash am Ende mitgeliefert.

 Sicherheit

Damit du sicher stellen kannst, dass die Anfrage wirklich vom cloud center kommt, ist die Anfrage entsprechend des nachfolgend beschriebenen Signatur-Mechanismuses abgesichert. Sobald die Anfrage ankommt solltest du als erstes Prüfen, ob diese Anfrage richtig signiert ist und in der richtigen Zeit kommt.

 Signaturprozess für cloud center Events

 Voraussetzungen

 Request Header

Folgende Header müssen vom Request angeliefert werden:

HeaderBeschreibung
Authorization: Bearer (berechnete Signatur)Kennzeichnet, dass der Request mit der hier beschriebenen Methode authentifiziert wurde
x-dv-signature-headersKommaseparierte Liste (ohne Leerzeichen) aller für die Signatur genutzten Header-Namen in Kleinbuchstaben
x-dv-signature-algorithmFür die Signatur verwendeter Algorithmus. Zur Zeit muss dort DV1-HMAC-SHA256
x-dv-signature-timestampISO 8601 Zeitstempel in UTC (Format: "yyyy-MM-ddTHH:mm:ssZ", z.B.: 2019-08-09T08:49:42Z)

 Gültigkeit der Anfrage

Bevor deine App die Signatur prüft, muss geprüft werden, ob die ankommende Anfrage aktuell ist. Dies erfolgt anhand des im Header x-dv-signature-timestamp befindlichen Zeitstempels. Der Zeitstempel bezieht sich auf die UTC-Zeit beim Absenden der Anfrage an eure App. Anfragen sind gültig für den Zeitraum von 5 Minuten vor bis 5 Minuten nach dem angegebenen Zeitstempel, um Zeitdifferenzen zwischen Server auszugleichen. Ist der Zeitstempel außerhalb dieses Zeitfensters, ist der Requests als nicht authentifiziert abzulehnen, typischerweise mit einem HTTP-Status 403 "Forbidden".

Ist die Anfrage außerhalb des gewählten Zeitfensters, sollte deine App den HTTP Status 403 "Forbidden" zurückliefern.

 Genutzter Hash-Algorithmen

Zum Erstellen der Hash-Werte wird der Hash-Algorithmus HMAC SHA256 verwendet. Dieser Algorithmus ist bereits in vielen Programmiersprachen enthalten.

 Berechnung der Signatur

Im folgenden werden die nötigen Schritte zur Berechnung der Signatur erklärt.

Verwendetes App Secret:

   
Rg9iJXX0Jkun9u4Rp6no8HTNEdHlfX9aZYbFJ9b6YdQ=

Name der Beispielapp:

   
myApp

Verwendeter Payload / Request Body:

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

 Sortieren und Normalisieren der Header

Es werden alle unter x-dv-signed-headers angegebenen Header alphabetisch sortiert. Danach werden die Header in Kleinbuchstaben gefolgt von einem ":" und dem entsprechenden Wert ohne Leerzeichen sowie einem Zeilenumbruch aneinandergereiht. Sollte einer der Header fehlen, sollte deine App mit dem HTTP Fehler 403 "Forbidden" antworten.

Wichtig: Die Liste muss alle *x-dv-** Header enthalten. Der Empfänger hat zu prüfen, ob diese Bedingung eingehalten wurde.

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-headers,x-dv-signature-algorithm,x-dv-signature-timestamp\nx-dv-signature-timestamp:2019-08-09T08:49:42Z\n"

 Normalisierung des Requests

In diesem Schritt werden die Bestandteile des Requests in normalisierter Form mit einem Zeilenumbruch als Trennzeichen aufgelistet.

Schema: HTTP-Verb + "\n" + // GET, PUT, POST... Pfad der Resource + "\n" + // Mit führendem Slash Querystring + "\n" + // Ohne ?, urlencodiert Headers + "\n" + // Der normalisierte Headerstring SHA256(Payload) // SHA256-Hash des Request-Body als Hexadezimalwert

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"

 Hexadezimal kodierten Hashwert bilden

Zuerst wird ein SHA-256 Hash aus dem normalisierten Request-String berechnet. Der Hash wird anschließend in einen Hexadezimalwert mit Kleinbuchstaben umgewandelt.

   
11cd5c976361611e4d66e748a6a2c2d902c6d4cdfc6e9b57c807f82fd22e719e

 Die Signatur berechnen

Aus dem berechneten hexadezimalen Request-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.

   
afc55d9822bbcd666aad9e53497508cee2e25dd4669a197c619ca8b786ff59ca

 Prüfung der Signatur

Um die Gültigkeit der Anfrage zu bestätigen, muss du als Empfänger den gleichen Prozess anwenden und prüfen, ob der berechnete Wert dem im Authorization-Header mitgegebenen Wert entspricht. Stimmt der Übermittelte Wert aus der Anfrage nicht mit dem berechneten Wert überein, soll der HTTP Fehler 403 "Forbidden" zurückgeliefert werden.