CXT-Plattform

Die CXT-Plattform stellt die Basis für Clients bereit, welche die CXT-Technologie nutzen, um MicroApps einzubinden. Im Wesentlichen umfasst sie derzeit drei Hauptfunktionalitäten:

• ein mit dem Protokoll „OAuth2“ kompatibler Authorization-Server, der Zugriff auf andere REST-Schnittstellen absichert
• die MicroApp-Registry, in der sich MicroApps für die Verwendung aus Clients heraus anmelden können
• eine rudimentäre REST-API für Basisfunktionalitäten von FirstSpirit

Voraussetzungen

• Es ist eine SOCKET-Verbindung zum FirstSpirit-Server erforderlich.
• Die Plattform-Webanwendung muss über denselben externen Host erreichbar sein wie die CXT-Clients (z. B. die FragmentCreator-Webanwendung, „same-origin“).

Modul-Datei

platform-[version].fsm

Installieren des Moduls

Das Modul wird über den FirstSpirit ServerManager installiert, und zwar im Dialog „Servereigenschaften / Module“ über die Schaltfläche „Installieren“:

URL anpassen

Der Dienst „CXT-Platform | Configuration Service“ von dem „FirstSpirit CXT Platform“ Modul stellt eine Konfigurationsoberfläche bereit. Diese öffnet sich mit einem Klick auf „Konfigurieren“ oder Doppelklick auf den Dienst. Hier muss die URL zur MicroApp konfiguriert werden. Dabei handelt es sich um die URL, über die die CXT-MicroApp-API in eine Webseite eingebunden werden kann.

Dabei handelt es sich um den Wert des Parameters cxt.platform.external-url, der für die CXT-Plattform konfiguriert wird (siehe dazu Konfiguration):

https://external/cxt-platform/microapps/api.js

(Zu weiteren Informationen zur Installation von Modulen siehe auch Module (→Dokumentation für Administratoren).)

Globale Webanwendung erstellen

Die Webanwendung muss anschließend über den FirstSpirit ServerManager im Bereich „Web-Applikationen“ als eigene, globale Webanwendung definiert und konfiguriert werden (Schaltfläche „Hinzufügen“ bei „Globale Web-Apps konfigurieren“, siehe dazu auch Web-Applikationen (→Dokumentation für Administratoren), Abschnitt „Installieren von globalen Web-Applikationen“).

Der Wert für Web Context muss

/cxt-platform

lauten, z. B.:

Web-Komponente hinzufügen

Für diese globale Web-Applikation muss ein geeigneter Webserver ausgewählt sein, dann die Web-Komponente „CXT Platform“ hinzugefügt und deployed (Schaltfläche „Installieren“ / „Aktualisieren“) werden:

Statusseite für die Fehleranalyse

Eine Quelle für Fehler ist häufig eine fehlerhafte Konfiguration. Sie kann dazu führen, dass die Software nicht oder nicht wie erwartet funktioniert.

Unter

/status

(angehängt an die URL der Plattform) ist eine Statusseite erreichbar, die beim Aufdecken von Konfigurationsproblemen hilft, also z. B.

http://myServer:8080/cxt-platform/status

Neben Informationen zum Server führt die Seite auch einen Test der Konfiguration durch, listet die letzten HTTP-Requests und Logmeldungen sowie alle aktuell registrierten MicroApps mit Erreichbarkeit, Name und URL auf.

Um Logmeldungen zu erhalten, muss der Parameter logging.file.name mit der gewünschten Log-Datei (z. B. /tmp/platform.log) angegeben werden, z. B.

logging.file.name=/home/tomcat/logs/platform.log

Die Statusseite ist nur für Administratoren erreichbar.

Hinweis: Zum Testen der Erreichbarkeit sendet die Statusseite an jede MicroApp einen leeren Kontext zur Überprüfung. Das kann zu Warnmeldungen wie dieser im Log führen:

de.espirit.cxt.microapps.stereotype.UnsupportedContextException: Context is not supported

Managementseite für MicroApps

Die Managementseite ist nur für Server- oder Projekt-Administratoren erreichbar.

Unter

/management

(angehängt an die URL der Plattform) ist eine Managementseite erreichbar, über die die Verfügbarkeit vom MicroApps konfiguriert werden kann, also z. B.

http://myServer:8080/cxt-platform/management

Um die Managementseite zu erreichen ohne die URL kennen zu müssen, kann auf der FirstSpirit Startseite ein Startbutton konfiguriert werden.

Dafür ist das „ApplicationPlugin: MicroApp Management“ der Web-Applikation „Startseite“ hinzuzufügen.

Dort muss die Web-Komponente auch deployed werden (Schaltfläche „Installieren“ / „Aktualisieren“).

Anschließend muss das ApplicationPlugin für „MicroApp Management“ im Bereich „Startseite“ („FirstSpirit ServerManager / Server / Eigenschaften / Startseite“) hinzugefügt werden:

Nach Auswahl des Plugins steht auf der Startseite das Icon zum Starten des „MicroApp Management“ zur Verfügung.

MicroApps können auch Aktionen definieren, die Benutzern zur Verfügung stehen. Diese Aktionen können auf der Managementseite ebenfalls konfiguriert werden.

Um die Konfigurationseinstellungen zu speichern, muss der Parameter cxt.platform.management.persistence.persistenceFile mit dem gewünschten Pfad zu der Persistenz-Datei angegeben werden (siehe Konfiguration).

Konfiguration

per web.xml

Die Konfiguration der Web-Applikation erfolgt über die entsprechende web.xml oder über eine Properties-Datei.
Die standardmäßig verwendeten Platzhalter-Werte funktionieren nicht in jedem Setup und sollten geprüft und an das jeweilige Setup angepasst werden.

Speziell bei Änderungen des Standardwerts der URL für die Webanwendung „FirstSpirit Startseite“ fs5root über den Parameter WEBAPP_ROOT_URL) funktioniert die automatische Ersetzung für den Platzhalter ${FIRST_SPIRIT_URL} nicht (z. B. cxt.dataservice.url). In diesem Fall muss der gewünschte Wert manuell angegeben werden.
(Zu weiteren Informationen zum Parameter WEBAPP_ROOT_URL siehe Web Applications (→Dokumentation für Administratoren).)

Beispiel: FirstSpirit-Server, Standardkonfiguration für cxt.dataservice.url in der web.xml:

<context-param>
   <param-name>cxt.dataservice.url</param-name>
   <param-value>${FIRST_SPIRIT_URL}/cxt</param-value>
</context-param>

Ausgerolltes Modul auf dem Tomcat-Webserver (automatische Ersetzung):

<context-param>
   <param-name>cxt.dataservice.url</param-name>
   <param-value>http://demo.e-spirit.de:2001/cxt</param-value>
</context-param>

Bei Änderung auf den Wert WEBAPP_ROOT_URL=/fs5root:

<context-param>
   <param-name>cxt.dataservice.url</param-name>
   <param-value>http://demo.e-spirit.de:2001/fs5root/cxt</param-value>
</context-param>

Kommentare

Kommentare werden in der web.xml mit

<!--

eingeleitet.
Diese Zeichenfolge kann auch zum Auskommentieren von Parametern verwendet werden.

Kommunikation

cxt.platform.firstspirit.hostname: Hostname oder IP-Adresse des FirstSpirit-Servers.

cxt.platform.firstspirit.port: Port des FirstSpirit-Servers.

cxt.platform.firstspirit.connection-mode: Verbindungsmodus für die Kommunikation mit dem FirstSpirit-Server.

• HTTP: normale Internetverbindung
• SOCKET: direkter Verbindungsmodus (Standardeinstellung; Single-Sign-On nur im SOCKET-Modus)

cxt.dataservice.url: Angabe der Adresse, unter der die DAP Bridge erreichbar ist, z. B.

cxt.dataservice.url=http://localhost:8080/cxt/

cxt.platform.internal-url: Angabe der URL, über die die CXT-Plattform intern erreichbar ist, z. B.

cxt.platform.internal-url=http://localhost:8888/cxt-platform/

cxt.platform.external-url: Angabe der URL, über die die CXT-Plattform in einem Browser erreichbar ist (Einbindung der JavaScript-API, Abfrage der MicroApp-Buttons usw.), z. B.

cxt.platform.external-url=https://external/cxt-platform/

Cross-Origin Resource Sharing (CORS)

Die Integrationsschnittstelle der CXT-Plattform stellt einzelne Funktionen aus der CXT-Welt in Form von MicroApps und über CXT-REST-Calls bereit, die dann in anderen Umgebungen verwendet werden können. Dazu gehören zum Beispiel klassische CRUD-Zugriffe auf Fragmente und Varianten, auch aus (Unternehmens-)WebApps, die nicht auf dem FirstSpirit Web-Server laufen („cross-origin resource sharing (CORS)“).

Liegen die aufrufende Stelle (z. B. Custom WebApp) und die CXT-Plattform nicht auf dem gleichen Web-Server („same-origin“), sondern auf unterschiedlichen Servern („cross-origin“), werden die Zugriffe vom Browser der externen WebApp normalerweise unterbunden (durch die Same-Origin-Policy (SOP)). Diese Einschränkung, kann für bestimmte URLs aufgehoben werden.

cxt.platform.cors-allowed-origins: Über diesen Parameter kann eine globale CORS-Konfiguration für CXT-MicroApps und für CXT-REST-Calls definiert werden. Mögliche Werte sind:

• Leer (keine Zugriffe erlaubt)
• * (alle Zugriffe erlaubt)
• Kommaseparierte Liste von URLs (Zugriffe für einzelne Origins erlaubt)

Authentifizierung (OAuth und Eureka)

FirstSpirit CXT verwendet das offene Sicherheitsprotokoll OAuth für die Autorisierung und Authentifizierung.
Es basiert auf dem Austausch von Tokens: Das so genannte Access-Token, welches nach erfolgreicher Authentifizierung vom OAuth-Server ausgegeben wird, ermöglicht Zugriffe auf Inhalte in CXT. Das so genannte Refresh-Token kann nach Ablauf eines Access-Tokens ein neues vom OAuth-Server anfordern, ohne dass eine erneute Authentifizierung notwendig ist. Das Refresh-Token kann nicht verlängert werden und ist nach dem Ablauf der Session nicht mehr nutzbar.

cxt.platform.eureka.password: Services registrieren sich am integrierten Eureka-Server. Dazu ist ein Passwort erforderlich. Vergeben Sie hier ein festes Passwort, und verwenden Sie dasselbe Passwort beim Konfigurieren des Client (z. B. FragmentCreator).

cxt.platform.oauth.client-secret: Clients, die OAuth-Tokens verwenden, benötigen einen gemeinsamen geheimen Schlüssel („Shared Secret“) für den Zugriff auf den Autorisierungsserver. Vergeben Sie hier ein festes Passwort und verwenden Sie dasselbe Passwort beim Konfigurieren des Client (z. B. FragmentCreator).

cxt.platform.oauth.jwt-signing-key: OAuth-Tokens werden mit diesem Schlüssel signiert und bleiben gültig, bis sie gemäß den unten konfigurierten Timeouts ablaufen. Der Standardwert RANDOM_VALUE sorgt für eine sichere Zeichenfolge, die sich mit jedem Start ändert.

Die Tokens haben eine zeitlich begrenzte Gültigkeit, die standardmäßig von FirstSpirit vorgegeben wird. Mit den folgenden Parametern kann die Gültigkeit der Tokens bei Bedarf an die speziellen Anforderungen des jeweiligen Projekts angepasst werden:

cxt.platform.oauth.access-token-validity-seconds: Legt den Gültigkeitszeitraum des OAuth-Access-Tokens fest (in Sekunden).
Standardwert: 3600 (1 Stunde)

cxt.platform.oauth.refresh-token-validity-seconds: Legt den Gültigkeitszeitraum des OAuth-Refresh-Tokens fest (in Sekunden). Der Wert sollte höher gewählt werden, als der des Parameters cxt.platform.oauth.access-token-validity-seconds.
Standardwert: 43200 (12 Stunden)

Content-Security-Policy Header (CSP)

cxt.platform.microapps.csp-origins: Über diesen Parameter kann das HTTP-Header-Feld Content-Security-Policy (CSP, siehe dazu auch https://content-security-policy.com/) angepasst werden. Dies ist z. B. dann erforderlich, wenn Zugriffe auf MicroApps von anderen Domains erlaubt werden sollen.
Bei inkorrekter bzw. fehlender Konfiguration des Parameters wird eine Fehlermeldung in der Browser-Konsole ausgegeben, z. B.

Refused to display 'http://myhost:8050/fragments/microapps/firstspirit-fragments-edit-by-reference' in a frame because an ancestor violates the following Content Security Policy directive: "frame-ancestors 'self'".

und die entsprechende MicroApp wird nicht geöffnet.

Über den Parameter können die Origins angegeben werden, von denen ein Zugriff möglich sein soll. Dabei wird der vollqualifizierte Domänenname erwartet.
* kann als Wildcard verwendet werden, z. B. um alle URLs zuzulassen oder bestimmte Subdomains einer Domain.

Mehrere Einträge können per Leerzeichen getrennt voneinander angegeben werden.

Wird der Parameter nicht angegeben, wird der Standardwert 'self' verwendet. Damit werden ausschließlich Zugriffe vom selben Server erlaubt (derselbe Host und Port).

Beispiel:

cxt.platform.microapps.csp-origins='self' *.e-spirit.de:8050

erlaubt Zugriffe von der Domain, von der der Header gesendet wird, sowie von Subdomains von e-spirit.de:8050.

Logausgaben

Optional können Parameter für erweiterte Logausgaben konfiguriert werden.
Siehe dazu Spring Boot Documentation (HowTo Logging).

logging.level: Spring Boot protokolliert Meldungen basierend auf dem Inhalt des Klassenpfades. Standardmäßig werden Meldungen mit dem Level WARN und höher geloggt. Zu Debug-Zwecken kann das Level über das Präfix logging.level in der web.xml aber temporär auch auf ein niedrigeres Level eingestellt werden. So können z. B. Logausgaben für CXT-Klassen über die Angabe des Packages de.espirit.cxt auf das Loglevel DEBUG eingestellt werden, z. B.

<context-param>
    <param-name>logging.level.de.espirit.cxt</param-name>
    <param-value>DEBUG</param-value>
</context-param>

logging.file.name: Über diesen Parameter können Logausgaben zusätzlich (zur Ausgabe in der Konsole) in eine Datei geschrieben werden, z. B.

<context-param>
    <param-name>logging.file.name</param-name>
    <param-value>/var/log/tomcat/cxt.log</param-value>
</context-param>

Management von MicroApps

cxt.platform.management.persistence.persistenceFile: Über diesen optionalen Parameter kann der Dateipfad zu der Persistenz-Datei definiert werden. In dieser Datei wird die Verfügbarkeitskonfiguration von MicroApps gespeichert, die bei dem CXT-Platform registriert sind.

per Properties-Datei

Alternativ kann zur Konfiguration des Plattform-Moduls eine Properties-Datei verwendet werden (cxt-platform.properties). Die dort hinterlegte Konfiguration überschreibt alle anderen Propertys (u.a. auch die Konfiguration über die Datei web.xml). Bei einem automatischen FirstSpirit-Update bleiben die in der Properties-Datei hinterlegten Einstellungen unverändert und werden nicht überschrieben bzw. zurückgesetzt.

Dazu muss im Classpath zunächst ein „config“-Verzeichnis erstellt und anschließend eine Datei

/config/cxt-platform.properties

angelegt werden. Bei Verwendung eines Tomcat z. B. im Verzeichnis

${TOMCAT_HOME}/lib

Innerhalb dieser Datei können die gewünschten Parameter konfiguriert werden, z. B.

cxt.dataservice.url=http://localhost:8080/cxt/

Deployment

Die wie oben beschrieben konfigurierte Web-Applikation für die CXT-Plattform muss anschließend per Schaltfläche „Installieren“ auf dem gewählten Webserver ausgerollt werden.

Siehe dazu auch Web-Applikationen (→Dokumentation für Administratoren).