Bereich: Communication

###########################
# communication
###########################
HTTP_PORT=8000
SOCKET_PORT=1088

HOST (optional)

Falls ein externer Applikations-Server eingesetzt wird, wird hier der Hostname oder IP-Adresse des FirstSpirit-Servers eingetragen. Servlets auf dem externen Applikations-Server verbinden zum SOCKET_PORT des FirstSpirit-Servers auf dieser Adresse. Dieser Parameter wird automatisch in die Datei web.xml der FirstSpirit-Servlets beim Start eingetragen.

HTTP_PORT

Http-Port des FirstSpirit-Servers (wird für die Standardkommunikation zwischen FirstSpirit-Client und -Server benötigt)

URL (optional)

Die hier angegebene URL zur Startseite des FirstSpirit-Servers wird an unterschiedlichen Stellen verwendet, z. B.:                                            

• in automatisch gesendeten E-Mails, die eine URL zum Start des Clients enthalten. Solche E-Mails werden zum Beispiel bei Zustandsänderungen innerhalb definierter Arbeitsabläufe (siehe Arbeitsabläufe (→Online Dokumentation FirstSpirit)) gesendet.   
• bei Verwendung der Funktion „FirstSpirit Adresse kopieren“ im SiteArchitect (Menü „Extras“, siehe Extras (→Handbuch FirstSpirit SiteArchitect))
• zum Ermitteln einer Referenz innerhalb einer FS_BUTTON-Komponente
• beim Wechsel von einer Webapplikation in eine andere (z. B. von fs5root in fs5webmon) 

Normalerweise wird die URL automatisch ermittelt, was aber nicht funktioniert, falls der Server unter mehreren Hostnamen bekannt ist.

URL=http://fs5server.domain.net

Der Parameter URL muss immer gesetzt werden, wenn einer der oben genannten Anwendungsfälle vorliegt (z. B. Arbeitsablauf-E-Mails) und ein externer Web-Applikations-Server (z. B. Tomcat) verwendet werden sollen.

Folgende Parameter müssen in diesem Fall ebenfalls gesetzt werden. Die Werte werden an die automatisch ermittelte bzw. durch den Parameter URL definierte URL angehängt und für den Verbindungsaufbau berücksichtigt.               

• fs.url.hostname (optional): Über diesen Parameter kann ein Hostname für die Client-Verbindung angegeben werden.
• fs.url.socketport (optional): Über diesen Parameter kann der Port angegeben werden, wenn die Client-Verbindung im Socket-Modus hergestellt werden soll (Platzhalter %FIRSTspiritSOCKETURL% in Arbeitsablauf-E-Mails).
• fs.url.httpport (optional): Über diesen Parameter kann der Port angegeben werden, wenn die Client-Verbindung im HTTP-Modus hergestellt werden soll (Platzhalter %FIRSTspiritURL% in Arbeitsablauf-E-Mails).
• fs.url.usehttps (optional): Soll beim Aufruf der Url HTTPS berücksichtigt werden, muss dieser Parameter auf true gesetzt werden. Der Standardwert ist false.

Beispiel:
Aus folgender Konfiguration in der fs-server.conf

HTTP_PORT=5100
SOCKET_PORT=5110
URL=http://myServer:8000
fs.url.hostname=aliashost
fs.url.socketport=8300  
fs.url.httpport=8200
fs.url.usehttps=true

würde für den Platzhalter %FIRSTspiritURL%:                                         

http://myServer:8000/start/FIRSTspirit.jnlp?app=client&project=myProject&name
=null&type=Page&id=443977&host=aliashost&port=8200&mode=HTTP&usehttps=true

für den Platzhalter %FIRSTspiritSOCKETURL%:

http://myServer:8000/start/FIRSTspirit.jnlp?app=client&project=myProject&name
=null&type=Page&id=443977&host=aliashost&port=8300&mode=SOCKET&usehttps=true

Bei Verwendung in einem bereits gestarteten Projekt z. B. über die Funktion „Zu FirstSpirit Adresse wechseln“ im SiteArchitect haben diese Parameter in der Regel keine Auswirkung.

Sind die Verbindungseinstellungen auf der Startseite aktiviert (siehe Benutzer), werden gemäß der auf Seite Startseite beschriebenen Auswertungsreihenfolge die fs.url-Parameter nicht berücksichtigt. Entgegen dieser Auswertungsreihenfolge werden allerdings die entsprechenden Parameter, die in den Servereigenschaften in den Bereichen Webstart und Startseite definiert sind, bei deaktivierten Verbindungseinstellungen nicht berücksichtigt, sondern es kommen die fs.url-Parameter zum Tragen.

SOCKET_PORT

TCP-Port, auf dem der FirstSpirit-Server auf Verbindungen für das FirstSpirit-eigene Socket-Protokoll wartet. Wird für die interne Kommunikation zwischen Servlets und FirstSpirit-Server verwendet und, falls konfiguriert, für die Kommunikation mit dem FirstSpirit SiteArchitect. Dieser Parameter wird außerdem automatisch in die Datei web.xml der FirstSpirit-Servlets beim Start eingetragen.

Wird der Wert dieses Parameters geändert, so müssen auf dem Web-Server installierte Web-Anwendungen manuell gelöscht werden, damit diese beim FirstSpirit-Neustart mit dem geänderten Port neu ausgerollt werden.

INTERNAL_SERVLET_ENGINE (obsolet)

Dieser Parameter bezieht sich auf den nicht mehr unterstützten integrierten Webserver „InternalJetty“. Der Parameter wird nicht mehr benötigt und sollte entfernt werden.

Der Wert 0 bedeutete, dass der nicht mehr unterstützte „InternalJetty“ deaktiviert war (Standard). Der Wert 1 bedeutet, dass der nicht mehr unterstützte „InternalJetty“ verwendet wurde.

Zu weiteren Informationen zu Verwendung und Konfiguration von Webservern unter FirstSpirit siehe auch

• Seite Webserver
• Kapitel Einbinden in externen Webserver

SOCKET_HOST (optional)

Hostname für die Bindeadresse des SOCKET_PORT, um den Server, wenn notwendig, auf eine IP-Adresse zu beschränken. Wird kein Wert übergeben, bindet der Server an alle IP-Adresse des Hosts. Zu Hinweisen hinsichtlich der Verwendung von IPv6 siehe auch Seite IPv6-Unterstützung.

Der Parameter SOCKET_HOST (= das Interface, auf den sich der Socket-Listener binden soll) kann nur verwendet werden, wenn auch der Parameter HOST (= Hostname, über den der Server von außen erreichbar ist, siehe oben) korrekt konfiguriert wurde, d.h. auf dasselbe Netzwerk-Interface des Servers abgebildet wird.

SYMBOLIC_HOSTNAME (optional)

Symbolischer Hostname des FirstSpirit-Servers. Dieser Hostname dient nur zur Anzeige auf der Startseite und hat ansonsten keine weitere Funktion.

ALLOWED_ENCRYPTIONS (optional)

Über diesen Parameter kann dem Benutzer vorgegeben werden, welche Verschlüsselung er in seinen Verbindungseinstellungen verwenden muss. Für die Verwendung von TLS wird der Wert 1 gesetzt, für die Verwendung von ChaCha20 der Wert 2. Soll keine Verschlüsselung verwendet werden, muss der Wert 0 gesetzt werden. Auch beliebige Kombinationen der Parameter 0, 1 und 2 sind möglich. Beispiel: ALLOWED_ENCRYPTIONS=1,2
Stimmt die Verschlüsselung, die der Benutzer eingestellt hat, nicht mit der hier vorgegebenen Verschlüsselung überein, erhält der Benutzer bei der Anmeldung am SiteArchitect oder zur Anwendung des ServerManager eine Fehlermeldung, dass die Verbindungsparameter falsch gesetzt wurden; es ist keine Kommunikation zwischen Client und Server möglich.         
Weitere Möglichkeiten zur Parametrisierung der TLS-Verschlüsselung siehe Parametrisierung der Verschlüsselung.

Für den Parameter ALLOWED_ENCRYPTIONS kann keine TLS-Verschlüsselung (Parameterwert 1) verwendet werden, wenn Websphere als Application-Server für die Webanwendung fs5root eingesetzt wird. In diesem Fall bietet sich an, ChaCha20-Verschlüsselung (Parameterwert 2) für SOCKET oder HTTP einzusetzen oder HTTPS zu verwenden. Bei HTTPS ist keine zusätzliche Verschlüsselung notwendig, so dass dann der Parameterwert 0 einzusetzen ist.

Websocket-Endpoint

Bei einer Client-Verbindung im HTTP-Modus wird nach Möglichkeit ein Websocket für die Datenübertragung verwendet.

Der Websocket-Endpoint lässt sich über den Parameter websocket.endpoint.enabled deaktivieren:

websocket.endpoint.enabled=false

Standardwert: true

Hinweis zur internen Kommunikation (IP-Multicast)

Um festzustellen, welche Server innerhalb eines Netzwerks erreichbar sind, sendet und empfängt der FirstSpirit-Server IP-Multicast-Nachrichten. Die Multicast Nachrichten werden für IPv4 unter der Adresse 239.192.34.16 gesendet und empfangen und für IPv6 unter der Adresse ff15::efc0:2210 (jeweils mit dem TCP-Port 23416).

FirstSpirit Session Cookie

Allgemeine Informationen

FirstSpirit verwendet mehrere Standard-Webanwendungen (fs5root, fs5webedit, fs5webmon, fs5preview, fs5staging) sowie eventuell weitere, projektlokale Webanwendungen (fs5webedit_PROJECTID und fs5preview_PROJECTID) (siehe Servereigenschaften / Web-Applikationen).

Zur (Nutzer-)Authentifizierung verwendet FirstSpirit, wie die meisten anderen Webanwendungen auch, zufällig generierte Session-Cookies. Durch die Verwendung der Session Cookies müssen die Anmeldedaten des Benutzers nur einmalig vom Webbrowser zum FirstSpirit-Server übermittelt werden. Nach dem erfolgreichen Login verwendet der Webbrowser ausschließlich das zeitlich begrenzt gültige, eindeutige Session Cookie, dass dann bei jeder weiteren Serveranfrage, anstelle der Anmeldedaten, vom Webbrowser zum Server gesendet wird, um den Benutzer dort zu authentifizieren.

Das Session Cookie ist integraler Bestandteil der Servlet-API und wird neben der Authentifizierung noch für viele weitere Anwendungsfälle verwendet.

Konfiguration

servletSessionCookieName (optional)

Über den Parameter servletSessionCookieName kann ein FirstSpirit-spezifischer Name für das Session Cookie für alle Webanwendungen definiert werden (Standardwert: nicht definiert, es wird der vom WebApp-Server vorgegebene Cookie-Name verwendet, meistens JSESSIONID).    

Syntax: FS${FS_MAJOR}${FS_MINOR}SESSIONID                               
Beispiel:

servletSessionCookieName=fs52devsession       

Es ist aber auch möglich, für jede Webanwendung einen eigenen, spezifischen Cookie-Namen zu definieren:      
Beispiel:

servletSessionCookieName.fs5webmon=fs52webmonid
servletSessionCookieName.webapp1=fs52webappxid

Eine Änderung des Vorgabewerts ist nur notwendig, wenn zwei oder mehr FirstSpirit-Server auf demselben Host mit derselben URL betrieben werden. In diesem Fall sollte jedem FirstSpirit-Server ein eindeutiger Cookie-Name zugewiesen werden.

Die Vorbelegung der optionalen Parameter servletSessionCookieName und servletSessionCookieName.ROOT in der fs-server.conf wurde geändert:

servletSessionCookieName=FS${FS_MAJOR}${FS_MINOR}SESSIONID 
servletSessionCookieName.ROOT=FS${FS_MAJOR}${FS_MINOR}ROOTID

Für alle FirstSpirit-Neuinstallationen wird dann ein FirstSpirit-spezifischer Name für das Session Cookie für alle Webanwendungen und für die Rootanwendung vorbelegt. Das geänderte Verhalten wirkt sich ausschließlich auf Neuinstallationen aus. Für bestehende FirstSpirit-Installationen bleibt die bisherige Konfiguration erhalten.

servletSessionCookieSameSite (optional)

Über den Parameter servletSessionCookieSameSite kann das Attribut SameSite für das Session Cookie konfiguriert werden.

SameSite ist ein Standard, der Verhindern soll, dass Cookies bei sogenannten Cross-Site Requests automatisch vom Browser mitgesendet werden und bietet damit einen Schutz vor Cross-Site-Request-Forgery (CSRF). Neben diesem Sicherheitsaspekt ermöglicht das Attribut SameSite zu definieren, welche Cookies in welchem Kontext ausgelesen werden können.

In der Standard-Einstellung für das Attribut SameSite (in der Konfigurationsdatei fs-server.conf) wird SameSite=Lax als globaler Wert gesetzt (siehe unten). Eine abweichende Konfiguration ist aber möglich.

Crownpeak empfiehlt die Standard-Einstellungen der Konfigurationsdatei fs-server.conf beizubehalten. Die Standardeinstellung deckt in den meisten Fällen sowohl die Sicherheitsaspekte (guter Schutz vor Cross-Site-Request-Forgery) als auch die Belange des Nutzers (gute User Experience) ab.
Nur in Ausnahmefällen ist eine Änderung notwendig.

Das Attribut SameSite=None erfordert ein „Secure“-Flag. Cookies mit SameSite=None-Attribut ohne „Secure“-Flag werden vom Browser abgelehnt. Mit dem „Secure“-Flag wird definiert, dass ein Cookie immer über eine sichere HTTPS-Verbindung gesendet wird.

Wozu braucht man das Attribut SameSite?

Viele Browser schränken Cookies von Drittanbietern automatisch ein. Das bedeutet, alle Cookies, die nicht das Attribut SameSite tragen:

• verursachen mit diesen Browsern Warnmeldungen in der JavaScript-Konsole, z. B. :
  Das Cookie "FS52ID" wird bald als Cross-Site-Cookie (...) behandelt. oder
• diese Cookies werden direkt auf First-Level-Domains beschränkt.

Das würde zu Problemen führen, wenn FirstSpirit-Webanwendungen in andere Webanwendungen integriert würden (z. B. als IFrame). In diesem Fall würde das Standardverhalten der Browser dazu führen, dass die FirstSpirit Session Cookies vom Browser blockiert würden und die Benutzer in der eingebetteten FirstSpirit-Webanwendung beispielsweise nicht mehr über das Session Cookie authentifiziert werden könnten.

Konfiguration:

Der Wert für die FirstSpirit Session Cookies kann über die Konfigurationsdatei fs-server.conf gesetzt werden, sowohl global über den Parameter servletSessionCookieSameSite als auch einzeln für bestimmte WebApp-Pfade, z. B. servletSessionCookieSameSite.fs5webmon=None für das FirstSpirit ServerMonitoring. Eine WebApp-spezifische Konfiguration überschreibt dabei die globale Einstellung servletSessionCookieSameSite für diesen WebApp-Pfad.

# Servlet engine session cookie SameSite attribute. If left empty, the SameSite attribute for the session cookie is not 
# set and the servlet engine defaults apply. 
# Supported values: None, Strict, Lax 
servletSessionCookieSameSite=Lax 
# Servlet engine session cookie SameSite attribute for a specific webapp context path. 
# 'ROOT' is the reserved name for the root webapp context path. 
# servletSessionCookieSameSite.ROOT=None 
# servletSessionCookieSameSite.fs5webmon=None 
# servletSessionCookieSameSite.webappContextPath=None 

Mögliche Werte des Attributs SameSite:

• Strict:
  • Das Session Cookie wird nur im First-Party-Kontext gesendet (also nur, wenn die Seite für den Cookie mit der URL im Browser übereinstimmt) und
  • nicht zusammen mit Cross-Site-Requests, die von Websites Dritter initiiert werden.
• Lax (FirstSpirit Standardeinstellung):
  • Das Session Cookie wird nur im First-Party-Kontext gesendet (also nur, wenn die Seite für den Cookie mit der URL im Browser übereinstimmt) und
  • nur zusammen mit Cross-Site-Requests, die als sicher angesehen werden. Dies betrifft die sicheren HTTP-Methoden (GET, HEAD, OPTIONS und TRACE) und die Top-Level-Navigation (Aktionen, die eine Änderung der URL in der Adressleiste des Browsers veranlassen, wie z. B. Links). SameSite=Lax ist die Standardeinstellung in modernen Browsern.
• None:
  • Das Session Cookie wird in allen Kontexten (also auch im Third-Party-Kontext) gesendet, d.h. das Senden ist ursprungsübergreifend erlaubt.
  • In dieser Einstellung bietet das Attribut keinen zusätzlichen Schutz gegen CSRF.
  • Diese Einstellung kann aber sinnvoll sein, wenn eine FirstSpirit-Webanwendung in eine andere Webanwendung integriert werden soll.
• [leer] Wert nicht gesetzt:
  • Ist der Wert nicht gesetzt, werden die Standardeinstellungen der Servlet Engine verwendet.
  • Ist hier kein Wert für das Attribut SameSite konfiguriert, wird die Standardeinstellung des Browsers verwendet. Moderne Browser interpretieren ein nicht gesetztes SameSite-Attribut als SameSite=Lax.

clientCookieNames (optional)

Dieser Parameter ist nur notwendig, wenn FirstSpirit in Verbindung mit einem Applikationsserver bzw. einer Firewall (auf dem Applikationsserver) betrieben wird, die einen zusätzlichen Session-Cookie (z. B. zur Authentifizierung) setzt. Die Namen dieser zusätzlichen Session-Cookies müssen FirstSpirit über den Parameter clientCookieNames bekanntgemacht werden. Beim Start des SiteArchitect oder ServerManager übergibt FirstSpirit die hier definierten Cookies über die auf Client-Seite heruntergeladene Startdatei für den FirstSpirit Launcher (FirstSpirit.fslnch).
Die Cookies werden auch an die für das Projekt konfigurierte Browser-Engine weitergereicht und sind damit in der integrierten Vorschau des SiteArchitect verfügbar. Das gleiche Cookie wird dann in drei unterschiedlichen Sitzungskontexten (Webbrowser: HTTP-Client, SiteArchitect: Client/Server-Kommunikation, SiteArchitect: Integrierte Browser-Engine) verwendet.

Standardwert für ClientCookieNames: [leer]

Die kommaseparierte Liste der einzutragenden Cookie-Namen muss neben den Session-Cookie-Namen der WebApp-Firewall auch den Namen des Session-Cookies der FirstSpirit-WebApps enthalten. Um den Namen des Session-Cookies der FirstSpirit-WebApps eindeutig zu definieren, sollte bei Verwendung von clientCookieNames auch der Parameter servletSessionCookieName definiert sein, der den Namen des Session-Cookies definiert. Zur Übernahme in die Liste von clientCookieNames wird dann die Variable ${servletSessionCookieName} verwendet, siehe Beispiel:

servletSessionCookieName=fssessionid
clientCookieNames=${servletSessionCookieName},PD-ID,PD-H-SESSION-ID,PD-S-

Einige Funktionen des FirstSpirit SiteArchitect werden durch den Betrieb in Verbindung mit einer WebApp-Firewall eingeschränkt. Folgende vom Benutzer im SiteArchitect aufrufbare Funktionen erfordern anschließend einen manuellen Neustart des SiteArchitect: Projektwechsel, Wechsel des integrierten Browsers.

Die optionale Konfiguration spezifischer Werte für Session-Cookies ist möglich. Über diese Attribute können Werte für Domain, Pfad und Secure-Flag der Session-Cookies gesetzt werden, wenn diese Werte über die fremderzeugten Cookies selbst nicht ausgelesen werden können:

• clientCookie.{cookieName}.domain: Angabe einer Domain für den Session-Cookie. Wird kein Wert gesetzt, übernimmt der Cookie die URL, mit der der Client gestartet wurde (inkl. Hostname).
• clientCookie.{cookieName}.path: Angabe einer Pfades für den Session-Cookie. Standardwert /
• clientCookie.{cookieName}.secure: Das Secure-Flag schränkt die Übertragung der Session-Cookies ein. Ist der Wert true gesetzt, wird der Cookie nur zum Server geschickt, wenn der Benutzer eine HTTPS-Seite betritt (vorausgesetzt, die Domain-/Path-Einschränkung passt). Ist der Wert false gesetzt, wird der Cookie sowohl auf HTTP- als auch auf HTTPS-Seiten gesendet.

Beispiel (fs-server.conf):

clientCookieNames=cookieName1     
clientCookie.cookieName1.domain=*.domain.com      
clientCookie.cookieName1.path=/      
clientCookie.cookieName1.secure=true

Die WebApp-Firewall muss ihre eigenen Session-Cookies an die FirstSpirit-WebApps weitergeben. Bei IBM WebSeal ist dazu beispielsweise in der Konfiguration zur „Junction“ im Bereich Identity der Parameter „Include Session Cookie“ zu aktivieren. Außerdem muss das Session-Timeout der WebApp-Firewall genügend groß eingestellt werden, so dass die Zeitspanne zum Start des SiteArchitect ausreicht. Üblicherweise genügen hier 5 Minuten.