5.1 Konfiguration & Entwicklung
5.1.1 Konfigurationsdatei dashlets.json anlegen
Im Gegensatz zu enaio® client (Rich Client), dessen Dashlet-Konfiguration enaio® enterprise-manager durchgeführt wird, lädt enaio® webclient eine JSON-Datei namens dashlets.json. Diese JSON-Datei wird aus dem öffentlichen Teil des Konfigurationsverzeichnis des enaio® service-manager geladen und muss dort von Ihnen manuell für die Einbindung von Dashlets erstellt werden. Legen Sie dazu die dashlets.json sowie die noch nicht vorhandenen Unterverzeichnisse in enaio® service-manager an:
\service-manager\config\apps\osweb\public\dashlets\dashlets.jsonMehrere enaio® service-manager Instanzen
Besteht Ihre enaio®-Installation aus mehreren service-managern, so müssen alle Dateien im und unter dem config-Verzeichnis, darunter auch die dashlets.json, in jeder Instanz der enaio® service-manager identisch vorhanden sein. Lesen sie dazu bitte auch "1.8 Laden externer Ressourcen".
5.1.2 Dashlets in der dashlets.json konfigurieren
Innerhalb der dashlets.json existiert im JSON-Format eine Array mit einem JSON-Objekt pro Dashlet. Über das JSON-Objekt kann das spezifische Dashlet passgenau konfiguriert werden, dass es nur in den gewünschten Clienttypen, Objekttypen, Benutzer- oder Benutzergruppen sichtbar ist. Auch der Titel kann für alle unterstützen Sprachen vergeben werden. Die Dashlets werden im enaio® webclient in der Reihenfolge angezeigt, wie sie in der dashlets.json konfiguriert wurden.
[{
"objectTypes": "*",
"platforms": ["web","desktop_app", "mobile", "mobile_app"],
"uri": "https://hostname/resources/apps/osweb/public/dashlets/preview/index.html",
"title_EN": "Preview Dashlet",
"title_DE": "Vorschau Dashlet",
"title_FR": "Aperçu Dashlet",
"iconId": "1073741986"
},{
"objectTypes": ["farbbild_1"],
"platforms": ["web","desktop_app"],
"uri": "https://hostname/resources/apps/osweb/public/dashlets/vertragsakte/index.html",
"title_EN": "Contract file",
"title_DE": "Vertragsakte",
"title_FR": "Dossier de contrat",
"iconId": "1073741986",
"groups": ["STANDARD"],
"users": ["user1", "user2"]
},{
"objectTypes": "*",
"platforms": ["web","desktop_app"],
"uri": "https://hostname/applet/contentviewer/index.html?osid={objectident}&focusIndexData=true",
"title_EN": "External content viewer EN",
"title_DE": "Externe Inhaltsvorschau DE",
"title_FR": "Aperçu du contenu externe FR",
"iconId": "1"
}]Nachfolgend werden die einzelnen Properties näher erläutert.
Property | Beschreibung |
|---|---|
| Falls das Dashlet für alle Objekttypen angezeigt werden soll, so fügen Sie hier eine Zeichenkette mit einem * ein. Ansonsten können Sie hier eine Array mit den internen Namen der Objekttypen eintragen, für die das Dashlet sichtbar sein soll. Ab Version 11.10.21 werden Dashlets im enaio® webclient, die für alle Objekttypen angezeigt werden, Benutzern jederzeit im Vorschaubereich zur Auswahl angeboten - auch in leeren Standorten. |
| Über diese Property kann das Dashlet auf bestimmte Plattformen des enaio® webclient eingeschränkt werden:
|
| Absolute Webadresse zur index-Datei des Dashlet samt Hostnamen. Ressourcen wie Javaskripte und CSS-Referenzen innerhalb der index-Datei werden automatisch nachgeladen. Ab Version 10.10, Service Release 2 , können die folgenden Platzhalter für URL-Parameter verwendet werden:
Beispiel: |
| Titel des Dashlets für Clients in englischer Oberflächensprache. |
| Titel des Dashlets für Clients in deutscher Oberflächensprache. |
| Titel des Dashlets für Clients in französischer Oberflächensprache. |
| Optional eine Icon ID aus dem enaio® editor für ein Icon, welches neben dem Titel des Dashlets im Menü dargestellt wird. >> enaio® editor, "Icons" |
| Optional ein Array mit Benutzergruppen, für die das Dashlet sichtbar sein soll. |
| Optional ein Array mit Benutzernamen, für die das Dashlet sichtbar sein soll. |
5.1.3 Das Dashlet selber hosten
Nachdem nun die dashlets.json angelegt wurde, muss das Dashlet selber auch irgendwo gehostet werden. Das Konzept unterhalb des config-Verzeichnis im enaio® service-manager bietet eine große Freiheit und in Kombination mit Git auch eine Versionierung und Staging. Leider befindet er sich im mit Logindaten geschützten Bereich von enaio®. Da wir beim Laden eines Dashlet keine Logindaten mitsenden, kann lediglich enaio® webclient im Browser auf dort gehostete Dashlets und ihre Dateien zugreifen. Dies ist möglich, da hier der Browser das Cookie zur Authentifizierung automatisch mitsendet. Für enaio® webclient als Desktop-Anwendung und enaio® mobile müssten wir dies explizit aktivieren und dies ist in der aktuellen Ausbaustufe noch nicht der Fall. Aus diesem Grund können nur Dashlets, die ausschließlich im Browser verwendet werden, im config-Verzeichnis des enaio® service-manager gehostet werden. Ihnen steht jedoch frei, jeglichen anderen Hostingstandort für die Dateien des Dashlets zu wählen.
enaio® webclient im Browser
Wie in "1.8 Laden externer Ressourcen" dargestellt sieht das grundlegende Konzept vor, Alles in projektspezifische Bereiche aufzuteilen. Die dashlets.json liegt in einem Ordner namens osweb. Dieser Ordner steht für den enaio® webclient. Innerhalb des Ordners dashlets liegt die dashlets.json. Es steht ihnen frei hier weitere Unterverzeichnisse für die eigentlichen Dashlets zu erstellen oder diese auch im Git-Repository einzuchecken. Entwickeln Sie hingegen eine Templatelösung, so sollten Sie vielleicht innerhalb des apps-Verzeichnisses ein eigenes Verzeichnis für ihr Projekt anlegen und dort alle Projektdateien ablegen. Innerhalb der dashlets.json verweisen Sie dann auf dieses Verzeichnis. Bitte beachten Sie, dass aus dem Internet nur auf Dateien zugegriffen werden kann, die unterhalb eines Verzeichnisses public liegen.
enaio® webclient als Desktop-Anwendung und enaio® mobile
Für diese beiden Clientarten kann aktuell leider nicht das config-Verzeichnis des enaio® service-manager genutzt werden. Hier muss ein anderer, ggf. externer Hostingstandort ohne Authentifizierung gewählt werden.
5.1.4 Das Demo-Dashlet
Wir bieten ein Demo-Dashlet an, welches auf einfache Weise demonstriert wie ein Dashlet geschrieben werden kann. Es beinhaltet alle Funktionen, die zum jetzigen Zeitpunkt zur Verfügung stehen und wird fortlaufend aktuell gehalten.
>> "5.5 Demo-Dashlet"
5.1.5 Sandbox-Direktiven
Die Dashlet-Sandbox bietet über die zur Verfügung stehenden Direktiven zusätzliche Möglichkeiten und damit mehr Flexibiliät an. Wichtig ist, dass diese Direktiven zwar die Funktionalität von Dashlets flexibel erweitern, jedoch auch potenzielle Sicherheitsrisiken mit sich bringen, wenn diese nicht ordnungsgemäß genutzt werden.
Direktive | Beschreibung | Sicherheitsrisiko |
|---|---|---|
allow-scripts | Erlaubt die Ausführung von JavaScript. Dies ist eine Basiserlaubnis, sie schließt Erlaubnisse wie allow-popups oder allow-modals nicht ein. | Kann die Ausführung potenziell bösartiger Skripte ermöglichen, wenn diese nicht ordnungsgemäß geprüft werden. |
allow-same-origin | Ermöglicht Inhalte im Dashlet, die die gleiche Herkunft haben (same-origin) | Kann genutzt werden, um Sicherheitsrichtlinien wie die Same-Origin-Policy zu umgehen, was Angriffe ermöglicht. |
allow-forms | Ermöglicht das Absenden von Formularen durch das Dashlet | Könnte böswillige Formularübermittlungen oder Phishing-Angriffe durch das Einschleusen von Formularen ermöglichen. |
allow-presentation | Erlaubt den Gebrauch des Presentation API durch das Dashlet | Kann dazu führen, dass sensible Informationen über die Präsentationsschnittstelle unerwartet geteilt werden. |
allow-modals | Ermöglicht das Öffnen von modalen Dialogen durch das Dashlet | Kann Phishing-Angriffe ermöglichen, indem täuschende modale Dialoge für Benutzer angezeigt werden. |
allow-popups | Erlaubt das Öffnen zusätzlicher Fenster (oder Tabs) durch das Dashlet | Könnte genutzt werden, um Pop-up-Spam zu erstellen oder Benutzer auf bösartige Websites umzuleiten. |
allow-popups-to-escape-sandbox | Ermöglicht, dass Popups, die vom Dashlet geöffnet werden, bestimmte Sandbox-Beschränkungen umgehen können, was umfassendere Interaktionsmöglichkeiten ermöglicht (ab 10.10.224, 11.0.508 und 11.10.14) Beispiel Dashlets: https://optimalsystems.github.io/iframe-demos/ & https://googlechrome.github.io/samples/allow-popups-to-escape-sandbox/ | Kann Popups uneingeschränktes Verhalten ermöglichen, wodurch diese möglicherweise auf die übergeordnete Umgebung in unerwünschter Weise zugreifen können. |
allow-downloads | Erlaubt Downloads, die durch Inhalte im Dashlet-iFrame initiiert werden (ab 10.10.224, 11.0.508 und 11.10.14) Beispiel Dashlets: https://optimalsystems.github.io/iframe-demos/ & https://googlechrome.github.io/samples/allow-popups-to-escape-sandbox/ | Kann unbeabsichtigte oder bösartige Datei-Downloads ermöglichen. |
Beispiel für die Verwendung in einem iFrame
<iframe
src="https://example.com/dashlet"
sandbox="allow-scripts allow-same-origin allow-forms allow-presentation allow-modals allow-popups allow-popups-to-escape-sandbox allow-downloads">
</iframe>Richtlinien zur Risikominderung
Entwickler von Dashlets sollten die folgenden Schutzmaßnahmen umsetzen:
Content Security Policies (CSPs) anwenden: Beschränken Sie die Quellen von Skripten, Styles und anderen Ressourcen im iFrame.
Eingaben validieren und bereinigen: Schützen Sie sich vor potenziellen Injection-Angriffen.
Vertrauenswürdige Quellen einschränken: Stellen Sie sicher, dass die Inhalte des iFrames aus sicheren und vertrauenswürdigen Domänen stammen.
Direktiven nur bei Bedarf aktivieren: Verwenden Sie diese Direktiven nur, wenn die Funktionalität sie zwingend erfordert.
Durch die Einhaltung dieser Richtlinien können Sie die neuen Direktiven nutzen, um leistungsstarke Funktionen bereitzustellen und gleichzeitig die Sicherheit zu gewährleisten.