Kunden der d.velop cloud werden Funktionen in Form von so genannten Apps bereitgestellt. Diese stellen ein oder mehrere zusammengehörige Funktionen für die Digitalisierung von Unternehmensprozessen bereit. So könnte eine App beispielsweise lediglich eine einzelne Funktion zum Signieren von Dokumenten bereitstellen oder aber mehrere zusammengehörige Funktionen anbieten, die zusammen genommen ein vollständiges Bewerbermanagement darstellen.

Im Folgenden ist beschrieben, welche Anforderungen eine d.velop cloud App erfüllen muss.

Die Inhalte stehen auch als Video zur Verfügung.

 Motivation und Prinzipien

Technologien, Frameworks und Tools ändern sich. Dies trifft insbesondere auf die Webentwicklung zu, bei der sich die Framework- und Toollandschaft gefühlt jedes Jahr ändert. Ein Framework, welches vielleicht heute noch als das Mittel der Wahl gilt, fristet mit hoher Wahrscheinlichkeit in einigen Jahren ein Nischendasein und wird dann eher als Belastung empfunden. Selbst wenn man diese Veränderungsprozesse mal außen vor lässt, wäre es wohl nicht möglich, sich zu einem bestimmten Zeitpunkt mit einer Vielzahl von Entwicklungsteams auf eine einheitliche Programmiersprache und einheitliche Frameworks zu einigen, ohne dass ein Großteil der beteiligten Personen diese Einigung als hinderlich empfinden würde.

Wie würdest du dich fühlen, wenn wir dir vorschreiben würden, dass du zwingend Java 5 und JSF verwenden musst, wenn du d.velop cloud apps entwickeln willst. Oder was würdest du sagen, wenn wir noch einen Schritt weitergehen würden und eine d.velop cloud spezifische Programmiersprache bzw. ein entsprechendes Framework vorschreiben würden, das du erst einmal erlernen musst und welches abseits der d.velop cloud völlig nutzlos ist?

Wir sind fest davon überzeugt, dass du als App Entwickler am besten entscheiden kannst, welche Programmiersprache, welches Framework und welche Tools du verwenden willst und auch in der Lage sein solltest, deine Entscheidung wieder zu revidieren, sobald sich eine bessere Alternative ergibt.

Aus diesem Grund beschränken wir uns bei den Vorgaben für d.velop cloud apps auf das absolute Minimum, mit dem Ziel, möglichst viele Freiheitsgrade zu gewähren, aber dennoch ein System zu erhalten, welches vom Endbenutzer als eine einzige Applikation wahrgenommen wird.

Bei den Vorgaben setzen wir auf etablierte, Programmiersprachen- und Framework-neutrale Standards, um eine hohe Stabilität und breite Anwendbarkeit zu erreichen.

Zusammengefasst agieren wir nach den folgenden Prinzipien:

1. Möglichst wenige Vorgaben und hohe Freiheitsgrade für dich als App Entwickler
2. Programmiersprachen- und Frameworkneutralität
3. Nutzung von offenen und etablierten Standards
4. Möglichst wenige d.velop cloud spezifischen Besonderheiten

 Vorgaben

Trotz der angestrebten Freiheitsgrade für dich als App Entwickler, gibt es einige Vorgaben, an die du dich halten musst, damit wir dem Endbenutzer letztendlich ein sicheres und verlässliches System bereitstellen können, welches für ihn so wirkt, als ob er mit einer einzigen großen Applikation und nicht mit einer Vielzahl unterschiedlicher Einzelapplikationen arbeitet.

 Zwingend zu erfüllende Vorgaben

Eigentlich gibt es mit HTML und HTTPS nur 2 unverhandelbare technische Vorgaben für eine d.velop cloud app. Die Registrierung der App im d.velop Cloudcenter ist hier eher organisatorischer Natur.

 HTML

Für die Benutzeroberflächen von d.velop cloud Apps muss HTML verwendet werden. Ganz im Sinne unserer Prinzipien, ist es uns dabei aber völlig egal, welche Programmiersprache oder welches Framework du dafür verwendest oder ob du clientseitig oder serverseitig gerendertes HTML nutzt.

Da HTML jetzt nicht gerade ein Exot ist, ist die Chance hoch, dass du die notwendigen Fähigkeiten bereits beherrscht. Wenn dem nicht so sein sollte, dann gibt es eine Fülle von kostenlosen und kostenpflichtigen Schulungsangeboten im Netz. Das Erlernen von HTML ist sicherlich keine vergeudete Zeit.

Du hast bereits eine bestehende HTML Anwendung? Prima! Dann hast du bereits einen Großteil der Voraussetzungen erfüllt und kannst deine Anwendung mit wenigen Handgriffen als d.velop cloud App bereitstellen. Lese dir hierzu bitte die weiteren Anforderungen durch.

 Mandantenfähiger HTTPS Endpunkt

Jede App muss über einen mandantenfähigen HTTPS Endpunkt erreichbar sein, der ausfallsicher ist und entsprechend skaliert, um auch in Stoßzeiten sämtliche Requests aller Mandanten beantworten zu können.

Die folgende Grafik zeigt die entsprechende Systemarchitektur.

Innerhalb der d.velop cloud bekommt jeder Mandant eine eigene Subdomain unterhalb von d-velop.cloud. Ein Mandant ist dabei üblicherweise eine Firma mit mehreren Mitarbeitern deren Daten um jeden Preis von den Daten der anderen Mandanten getrennt werden müssen.

Sämtliche DNS Einträge verweisen auf den so genannten Approuter. Dieser ist ein Teil der d.velop cloud Plattform und fungiert als eine Art Reverse Proxy für sämtliche Apps.

Anhand des 1. Pfadsegmentes entscheidet der Approuter, an welchen Endpunkt der jeweilige Request weitergeleitet werden muss. So werden Requests, deren Pfad mit /dms/ beginnt, an den mandantenfähigen Endpunkt der DMS-App weitergeleitet. Wohingegen Requests, deren Pfad mit /dash/ beginnt, an die Dashboard-App weitergeleitet werden.

Mit welchen Mitteln du einen mandantenfähigen Endpunkt erstellst, der nicht nur ausfallsicher ist, sondern auch lastabhängig skaliert, bleibt dir überlassen. Wo dieser Endpunkt läuft und welche Domain du nutzt, spielt für uns ebenfalls keine Rolle, solange das zugrundeliegende Rechenzentrum ISO/IEC 27001 zertifiziert ist.

 Mandantenheader

Da sämtliche Requests aller Mandanten an einen einzigen Endpunkt weitergeleitet werden, muss dieser Endpunkt entscheiden können, auf welchen Mandanten sich der jeweilige Request bezieht.

Zu diesem Zweck fügt der Approuter HTTP Header, mit entsprechenden Informationen über den Mandanten, zum Request hinzu. Diese Informationen müssen dann vom Endpunkt ausgewertet werden, um zu entscheiden, in welchen Datentopf die App schauen muss, um Daten zum Mandanten zu bekommen und über welche Basis URI die anderen Apps des Mandanten angesprochen werden können.

1. Der Nutzer ruft die xyz-App des Mandanten acme im Browser auf.
2. Die DNS Abfrage für die Subdomain des Mandanten löst auf den Approuter auf.
3. Der Approuter fügt die passenden Mandantenheader zum Request hinzu und leitet diesen an den, im d.velop Cloudcenter hinterlegten, Endpunkt für die xyz-App weiter.
4. Die xyz-App prüft die Signatur der Mandantenheader um sicherzugehen, dass die Informationen über den Mandanten auch wirklich vom Approuter kommen und kann dann anhand der tenant-id 345az3 im entsprechenden Datentopf für den Mandanten nachschauen, um den Request zu beantworten.

 x-dv-tenant-id

Die tenant-id ist eine eindeutige und lebenslang gültige Id für einen Mandanten, die nicht neu vergeben wird. Diese eignet sich also dazu, einen Mandanten dauerhaft zu identifizieren und die Daten des Mandanten von Daten der anderen Mandanten zu trennen. Wie diese Trennung implementiert wird, hängt wiederum vom genutzten Datenbankmanagementsystem ab. Bei relationalen Datenbanken liegt die Nutzung separater Schemata nahe, während die tenant-id bei Key Value Stores ein Teil des Keys (z.B. als Prefix) sein könnte.

 x-dv-baseuri

Nicht nur die Kommunikation vom Client (Browser) zu den Apps, sondern auch die Kommunikation zwischen den Apps, läuft über den Approuter. Daher muss eine App, die Requests gegen eine andere App absetzen will, neben dem Namen der anzusprechenden App, auch die baseuri des Mandanten kennen. Diese wird im x-dv-baseuri Header übertragen.

 x-dv-sig-1

Um sicherzustellen, dass die Mandanteninformationen auch wirklich vom Approuter kommen, ist es zwingend erforderlich, dass jede App die HMAC-SHA256 Signatur prüft, die im x-dv-sig-1 Header übertragen wird. Dazu berechnet die App die Signatur nach folgendem Verfahren:

   Signatur = HMAC-SHA256 ("<Wert von x-dv-baseuri><Wert von x-dv-tenant-id>",App Secret)

und vergleicht das Ergebnis mit der Wert des x-dv-sig-1 Headers. Hierbei ist zu beachten, dass der Wert im x-dv-sig-1 Header Base64 kodiert ist.

Sollte der Vergleich fehlschlagen, d.h. der berechnete Wert für die Signatur stimmt nicht mit dem im Header übertragenen Wert überein, dann muss die App den Request ablehnen. Üblicherweise wird dazu der HTTP Status Code 403 Forbidden verwendet.

Das folgende Beispiel kann als Test für die Implementierung einer eigenen Signaturprüfung genutzt werden:

   x-dv-tenant-id:                 a12be5
x-dv-baseuri:                   https://header.example.com
App Secret (base64 encoded):    ptuQ0b0BskmLLxXsjjhH9Su8ozTvZl6Z/5/HlaORoRg=

x-dv-sig-1 (base64 encoded):    Zjcf28p5aQ6amtbs6s9b9cPyBPdziwUslR2DZqaGUTQ=

 Dringend empfohlene Vorgaben

Neben den beiden Vorgaben HTML und mandantenfähiger HTTPS Endpunkt gibt es in der Tat keine weiteren Vorgaben, die du zwingend einhalten musst. Es gibt allerdings einige zusätzliche Punkte, deren Umsetzung wir dir dringend ans Herz legen. Zumindest solltest du genau wissen, welche Konsequenzen es hat, wenn du diese Punkte missachtest.

 Responsive Material Design

Wir verfolgen die Strategie, unsere HTML Oberflächen nur einmal zu entwickeln und auf verschiedenen Endgeräten wie Desktop PCs, Tablets und Mobiltelefonen anzuzeigen. Aus diesem Grund nutzen wir Responsive Webdesign für unsere HTML Oberflächen.

Des Weiteren nutzen wir Material Design von Google. Als Designsystem beinhaltet dies nicht nur eine Komponentensammlung für die Webentwicklung, sondern auch umfangreiche Guidelines und Prinzipien, die beschreiben, in welcher Situation man welches Oberflächenelement wie nutzen sollte.

Da alle unsere Oberflächen Material Design nutzen (oder gerade darauf umgestellt werden), erhält der Benutzer ein einheitliches Look & Feel und verschwimmen die für den Nutzer sichtbaren Grenzen zwischen den Oberflächen der verschiedenen Apps.

Üblicherweise ist man als Entwickler trotzt Designsystem nicht unbedingt in der Lage, visuell ansprechende Oberflächen in kurzer Zeit zu gestalten. Aus diesem Grund stellt unser Design und Usability Team einige Open Source Kopiervorlagen für ganze HTML Seiten bereit, die eine gute Ausgangsbasis für eigene Oberflächen sind.

 Integration in die Shell-App

Wenn du bereits die d.velop cloud genutzt hast oder On-Premises mit d.3one gearbeitet hast, dann ist dir bestimmt aufgefallen, dass wir - je nach zur Verfügung stehendem Platz - eine bestimmte Bildschirmaufteilung haben und dass es eine Art Menüleiste gibt, über die man die Bildschirmaufteilung ändern kann. Darüber hinaus werden beim Klick auf bestimmte Links neue Webseiten (Ressourcen) reinanimiert.

Diese und weitere Funktionen werden durch die Shell-App bereitgestellt, die die Webseiten aller beteiligten Apps in separate iframes lädt. Auf diese Weise erhält man ein homogenes Bedienkonzept und gleichzeitig sind die verschiedenen Seiten der Apps voneinander isoliert, so dass innerhalb des iframes unterschiedliche Frameworks verwenden können.

Die Integration in die Shell-App ist nicht sonderlich aufwendig und unobstrusive gehalten. D.h. bei der Konzeption der Shell war und ist es das Ziel, möglichst wenig an vorhandenen Webseiten ändern zu müssen, um die Shell-App zu nutzen. Wie du dich in die Shell-App integrierst, findest du in der entsprechenden API Beschreibung.

 Browserunterstützung

Aktuell unterstützen wir in der d.velop cloud die folgenden Browser auf den genannten Betriebssystemen bzw. Geräten:

• Internet Explorer 11 (Support endet Oktober 2021), Chrome und Firefox auf Microsoft Windows
• Chrome auf Android ab Android Version 5.0
• Safari auf iOS (iPhone/iPad)
• Safari auf MacOS

Bei Chrome, Firefox und Safari unterstützen wir jeweils nur die aktuellste Version.

Da der Internet Explorer seitens Microsoft nicht mehr weiterentwickelt wird, fehlen diesem wesentliche Funktionen eines modernen Browsers. Daher werden wir nicht sicherstellen können, dass auch zukünftig sämtliche Funktionen der d.velop cloud im Internet Explorer zur Verfügung stehen. Dies gilt natürlich nicht für die wesentlichen Kernfunktionen. Diese stehen selbstverständlich auch im Internet Explorer zur Verfügung. Allerdings betrifft dies möglicherweise einige optionale Zusatzfunktionen wie z.B. die Möglichkeit, das Theming zu ändern.

 Authentifizierung über die Identityprovider-App

Mit der Identityprovider-App gibt es in der d.velop cloud eine zentrale Anlaufstelle für die Authentifizierung, also für die Fragestellung "welcher Benutzer sitzt dort gerade vor dem Rechner".

Neben einem eigenen Identitätspool unterstützt der Identityprovider eine Reihe von externen Identitätsprovidern wie z.B. Google, Azure AD oder Facebook, so dass sich Benutzer in der d.velop cloud auch mit ihren bestehenden Credentials anmelden können, wenn sie bereits ein Konto bei den genannten Diensten haben und der jeweilige externe Identitätsprovider durch den Administrator im Mandanten konfiguriert worden ist.

Nach einer erfolgreichen Anmeldung erzeugt die Identityprovider-App eine Session für den angemeldeten Benutzer, die von sämtlichen Apps in der d.velop cloud genutzt werden kann, um den Benutzer eindeutig zu identifizieren.

Die Autorisierung, also die Fragestellung "Was darf der angemeldete Benutzer", kann dann allerdings nur von der jeweiligen App gelöst werden, da hierzu Wissen über die in der App abgebildete Fachlichkeit notwendig ist.

Die folgende Grafik zeigt den Ablauf bei der Authentifizierung.

Ablauf der Authentifizierung:

1. Der Nutzer ruft eine beliebige App der d.velop cloud auf. Im Beispiel die Hello-App im Mandanten acme.
2. Der Approuter fügt die Mandantenheader hinzu (hier nicht dargestellt) und leitet den Request an die Hello-App weiter. Diese stellt fest, dass keinerlei Authentifizierungsinformationen im Request enthalten sind und leitet den Client daher per Redirect (HTTP Status 302 Found) an die login-Ressource des Identityproviders weiter. Die ursprünglich aufgerufene Ressource /hello/world wird dabei URL-enkodiert als query Parameter übergeben.
3. Der Browser folgt automatisch dem Redirect, so dass der Request über den Approuter am Identityprovider landet.
4. Der Identityprovider findet ebenfalls keine Authentifizierungsinformationen im Request und führt daher eine Authentifizierung des Benutzers gegen den internen Identitätspool oder gegen den konfigurierten externen Identitätspool durch (hier nicht dargestellt). Wenn der Benutzer sich erfolgreich authentifiziert hat, setzt der Identityprovider ein AuthSessionId-Cookie, anhand dessen der angemeldete Benutzer identifiziert werden kann und leitet den Client dann - ebenfalls per Redirect - zur ursprünglich aufgerufenen Ressource /hello/world weiter.
5. Der Browser folgt automatisch dem Redirect, so dass letztendlich ein entsprechender Request auf die ursprünglich (siehe Schritt 1) angeforderte Ressource bei der Hello-App landet. Allerdings enthält der Request jetzt eine Authentifizierungssession.
6. Die Hello-App empfängt den Request mit der Authentifizierungssession (AuthSessionId), kennt aber den zur Session gehörenden Benutzer noch nicht. Um diesen zu ermitteln, ruft die Hello-App die validate-Ressource des Identityproviders auf und überträgt die Authentifizierungssession als Bearer-Token. Beachte, dass das Bearer Token nicht URL enkodiert ist.
7. Der Identityprovider kennt den zur Authentifizierungssession gehörigen Benutzer bereits und beantwortet die Anfrage mit einem standardisierten JSON Objekt, welches Informationen über den Benutzer enthält. Unter anderem enthält dieses SCIM User Object auch eine dauerhaft gültige Id für den Benutzer, die auch über die Gültigkeit der Authentifizierungssession hinaus geeignet ist, um den Benutzer eindeutig zu identifizieren. Beachte, dass die Authentifizierungssession ihre Gültigkeit nach einer, vom Identityprovider festgelegten Zeit, verliert und daher nicht geeignet ist, um den Benutzer dauerhaft zu identifizieren.
8. Die Hello-App hat jetzt sämtliche Informationen über den angemeldeten Benutzer, um eine Berechtigungsprüfung durchzuführen und den Request des Benutzers zu beantworten, falls dieser berechtigt ist. Damit das ganze Verfahren nicht wiederholt für jeden einzelnen Request durchlaufen werden muss, sollte sich die jeweilige App in einem mandantenspezifischen Cache merken, welches SCIM User Object zu einer AuthSessionId gehört. Der vom Identityprovider gesetzte Cache-Control-Header gibt Auskunft darüber, wie lange diese Information gecacht werden darf.

 Registrierung der Features an der Dashboard-App

Sobald ein Mandant deine App in der d.velop cloud gebucht hat, müssen dessen Benutzer natürlich wissen, wie die verschiedenen Funktionen deiner App aufgerufen werden können. Eine Möglichkeit wäre es, sämtlichen Benutzern die URIs zu den verschiedenen Features deiner App mitzuteilen, so dass diese passende Bookmarks setzen können.

Das ist natürlich nicht sonderlich benutzerfreundlich, so dass wir zu diesem Zweck die Dashboard-App in der d.velop cloud bereitstellen. Die Dashboard-App bietet Apps die Möglichkeit, auf der Startseite als Widget angezeigt zu werden. Dadurch wird ein komfortabler Einstieg in die Features der gebuchten Apps ermöglicht.

In der API Beschreibung der Dashboard-App findest du genauere Informationen dazu, wie du ein Widget für deine App auf dem Dashboard erstellen kannst.

 Empfehlungen

Du weißt jetzt welche zwingenden Vorgaben es gibt und welche Vorgaben zwar nicht absolut notwendig sind, aber für deren Nichteinhaltung du gute Gründe haben solltest.

Daneben gibt es noch einige Empfehlungen, die im Folgenden aufgeführt sind. Ob du diesen folgen willst, liegt bei dir. Wir haben mit der Umsetzung dieser Empfehlungen und der daraus resultierenden losen Kopplung der Apps, gute Erfahrungen gemacht, so dass wir dir diese nicht vorenthalten wollen. Selbst, wenn du hier andere Wege gehen willst - was für uns vollkommen in Ordnung ist - hilft dir die Kenntnis dieser Empfehlungen beim Umgang mit unseren d.velop cloud Apps und deren APIs.

 Self-Contained Systems

Aus der Problemstellung heraus, mit einer stetig steigenden Anzahl von Entwicklern an einer Software zu arbeiten, haben wir nach einer Lösung gesucht, die es uns ermöglicht, autarke Teams zu bilden, die jeweils nur an einem Teil dieser Software arbeiten und diese Teile für den Endkunden wieder zu einem großen Ganzen zusammenzusetzen.

Die klassische Aufteilung in Frontend, Backend und ggf. Datenhaltung stößt hier an ihre Grenzen, da diese maximal drei Teams zulassen würde. Ganz davon abgesehen, dass diese Teams alles andere als autark sind. Ganz im Gegenteil! Selbst für die kleinsten Erweiterungen in der Fachlichkeit müssen i.d.R. alle drei Teams zusammenarbeiten und passende Schnittstellen absprechen.

Statt die Teams also nach horizontalen, technischen Layern zu bilden, benutzten wir vertikale, fachlich orientierte Schnitte, um die Anwendungsdomäne in mehrere Bausteine aufzuteilen. Die Kunst bei der Erarbeitung dieser Bausteine liegt darin, Ausschnitte der Anwendungsdomäne zu finden, die möglichst wenig Abhängigkeiten zu den anderen Teilen der Domäne haben. Diese Bausteine können dann von unterschiedlichen Teams eigenständig bearbeitet werden. Intern enthalten diese Bausteine dann wieder die üblichen Schichten (Frontend, Backend, Datenhaltung), allerdings sind die Schnittstellen zwischen diesen Schichten jetzt ein internes Detail des Bausteins und für andere Bausteine unsichtbar.

Diese genannten Bausteine sind unsere Apps. Um diese für den Benutzer zu einer virtuellen Gesamtapplikation zusammenzufügen, verwenden wir vorzugsweise Links im Frontend. Dies ermöglicht uns eine wesentlich losere Kopplung als eine Interaktion auf Datenebene.

Wir haben diese Architektur nicht erfunden und sind auch nicht die einzigen, die ihre Systeme so konstruieren. Mittlerweile hat sich mit Self-Contained Systems (SCS) auch ein Name für eine solche Architektur gefunden.

 REST

Manchmal lässt der umzusetzende Anwendungsfall keine Verlinkung im Frontend zu. Beispielsweise ist bei der serverseitigen Archivierung von E-Mails kein Benutzer und damit auch kein Frontend im Spiel.

Für solche Fälle bieten wir selbstverständlich auch klassische, RESTful HTTP APIs mit JSON Repräsentationen an. Insbesondere nutzen wir an vielen Stellen die JSON Hypertext Application Language, um auch im JSON Format zwischen verschiedenen Ressourcen zu verlinken.