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

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 Apps für ihre d.velop-Cloud buchen können.

 Technische Hintergrundinformationen

d.velop 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 d.velop cloud center und deiner App abgesichert ist, sollten dir die Hashfunktion 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 d.velop cloud center abgesichert ist.

 Grundlegendes zum App Secret

Das App Secret besteht aus zufällig zusammengestellten Bytes, die 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 das App Secret auch zur Absicherung der Events verwendet, die von d.velop cloud center gesendet wurden.

Nach der Erstellung der App in d.velop 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 eintragen. Nach der ersten Änderung wird dein App Secret nur noch verschlüsselt dargestellt. Solltest du vergessen haben, das App Secret zu kopieren, kannst du dir jederzeit im Bereich technische Details ein neues App Secret erzeugen 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 von 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 d.velop cloud center bekannt ist. Wenn deine berechnete Signatur mit der aus der Anfrage übereinstimmt, kannst du dir sicher sein, dass die Anfrage von d.velop cloud center gesendet wurde.

Anfrage Header

Folgende Header müssen bei der Anfrage von d.velop cloud center an deine App mitgeliefert 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: Der Algorithmus, der für die Signatur verwendet wird, aktuell 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).

 Implementieren 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

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"

 Normalisieren 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, der ebenfalls angehängt 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 Hashwerte den Hashalgorithmus SHA256 und die Bibliothek der jeweiligen Programmiersprache. Zum Bilden des Hashwertes wird zuerst ein SHA-256-Hash aus dem normalisierten Anfragestring berechnet. Der Hash wird anschließend in einen Hexadezimalwert mit Kleinbuchstaben umgewandelt.

Beispiel

    fcecaac3dae4d40d6f2a065678f59f4794dfbe8497fe9ca825f737299887ebf4

 Berechnen der Signatur

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

    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 fünf Minuten vor bzw. fünf Minuten nach dem angegebenen Zeitstempel gültig. Wenn die angegebene Zeit außerhalb des Zeitfensters ist, muss die Signatur als ungültig betrachtet werden und die Anfrage wird mit dem HTTP-Status "403 Forbidden" abgelehnt. Mit dem beschriebenen Signaturprozesses berechnet die App eine Vergleichssignatur. Stimmt die berechnete Signatur nicht mit dem hexadezimalen Wert aus dem Authorization-Header überein, wird die Anfrage ebenfalls mit dem HTTP-Status "403 Forbidden" abgelehnt.

 Verwenden der API-Funktionen

d.velop 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 Applebenszyklus

Damit du weißt, wann deine App beispielsweise von einem Kunden gebucht wurde, veröffentlicht d.velop 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".

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 verwendet 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 von d.velop cloud center enthält den nachfolgenden Body in Form eines JSON-Dokuments.

• "type": Enthält den jeweiligen Eventtyp. Je nachdem welcher Typ 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://tenant.d-velop.cloud"
}

 Überprüfen der Ereignisse

Damit du sicherstellen kannst, dass die Anfrage wirklich von d.velop cloud center kommt, ist die Anfrage mit dem beschriebenen Signaturmechanismus 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 mitgebucht werden.

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

• Bundle – Du möchtest mehrere Apps gleichzeitig bereitstellen, um sie z.B. dem Kunden als Produktvariante zu verkaufen. Dafür erstellst du eine App, die selbst keine Funktionen hat. Dort fügst du alle Apps, die gleichzeitig bereitgestellt werden sollen, als Abhängigkeit hinzu. Da die App selbst keine Funktionen hat, kannst du die Einstellung für die Berechtigungsstufe an den Abhängigkeiten auf dem Standardwert Keine belassen.
• Technische Abhängigkeit – Du möchtest den API-Endpunkt einer anderen App verwenden, um z.B. Dokumente aus der DMS-App abzurufen. Dafür fügst du die App, die den API-Endpunkt bereitstellt, als Abhängigkeit hinzu. Damit der API Endpunkt verwendet werden kann, musst du die Einstellung für die Berechtigungsstufe an der Abhängigkeit entsprechend festlegen (siehe Berechtigungsstufen).

 Berechtigungsstufen

Berechtigungsstufen steuern die Art des Zugriffs auf die Abhängigkeit. Hier solltest du das Least-Privilege-Prinzip verfolgen.

Implizite Berechtigungen

Einige Berechtigungen für grundlegende Apps müssen nicht angegeben werden, da HTTP Calls an diese grundlegenden Apps immer erlaubt sind. Die grundlegenden Apps sind die folgenden

Verwenden

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

Hinzufügen, entfernen und ändern einer Abhängigkeit sind nur möglich, so lange 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.

 Automatische Buchung

An der Abhängigkeit gibt es eine Eigenschaft für die automatische Buchung. Wenn die Eigenschaft aktiv ist, wird die Abhängigkeit automatisch bei der Buchung deiner App mitgebucht. Wenn du eine neue Abhängigkeit hinzufügst, ist die automatische Buchung nicht aktiv. Du kannst das Verhalten im Bearbeitungsdialog der Abhängigkeit ändern. Wenn du diese Eigenschaft im Nachhinein aktivierst, wird beim Speichern die Abhängigkeit in allen Mandanten deiner App nachgebucht. Wenn du die Eigenschaft nachträglich deaktivierst, findet keine Kündigung der geänderten Abhängigkeit in den Mandanten deiner App statt.

 Informationen zu Mandanten

Du kannst Informationen über den Mandanten abrufen, indem du innerhalb des Mandanten die _self-Route nutzt. Das zurückgelieferte Ergebnis enthält grundlegende Informationen über den Mandanten, aber auch über seine gebuchten Apps, die Abhängigkeiten der Apps und deren Zugriffsberechtigungen.

GET /center/t/_self

Accept: application/json OR application/hal+json

Beispiel:

https://example.d-velop.cloud/center/t/_self

 Objekte und Eigenschaften

Mandant-Objekt

App-Objekt

ACL-Objekt

Overwrites-Objekt

Ergebnis:

HTTP-Status: 200

{
    "tenant": {
        "id": "xyz",
        "name": "Example Tenant",
        "domainName": "example",
        "fullQualifiedDomain": "example.d-velop.cloud",
        "administrators": [
            "tenantadmin",
            "example@mail.com"
        ],
        "created": "2020-11-11T11:11:14.987654321Z",
        "updated": "2021-09-30T12:00:21.123456789Z",
        "organizationId": "abc123xyz",
        "apps": {
            "basis": {
                "name": "basis",
                "displayName": "d.velop cloud platform base",
                "dependencies": [
                    "config",
                    "home"
                ],
                "acl": {
                    "readonly": [
                        "config",
                        "home"
                    ],
                    "full": null
                }
            },
            "config": {
                "name": "config",
                "displayName": "config",
                "dependencies": null,
                "acl": {
                    "readonly": null,
                    "full": null
                }
            },
            "home": {
                "name": "home",
                "displayName": "home",
                "dependencies": null,
                "acl": {
                    "readonly": null,
                    "full": null
                }
            }
        },
        "overwrites": {}
    }
}