Area: Communication

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

HOST (optional)

If an external application server is used, the host name or IP address of the FirstSpirit Server is entered here. Servlets on the external application server connect to the SOCKET_PORT of the FirstSpirit Server at this address. This parameter is entered automatically in the web.xml file of the FirstSpirit servlet during startup.

HTTP_PORT

HTTP port of the FirstSpirit server (required for standard communication between the FirstSpirit client and FirstSpirit server).

URL (optional)

the URL specified here for the FirstSpirit server start page is used at different places, for example

• in  automatically sent e-mail messages containing a URL when the client is started. These types of e-mail messages are sent within defined workflows (see Workflows (→FirstSpirit Online Documentation)), such as in the case of status changes.
• when using the “Copy FirstSpirit address” function in SiteArchitect (“Extras” menu, see Extras (→Documentation FirstSpirit SiteArchitect)).      
• for determining a reference within a FS_BUTTON input component.
• when switching from one web application to another (for example from fs5root in fs5webmon)

Usually, the URL is determined automatically, but this will not work if the server is recognized by many host names.

URL=http://fs5server.domain.net

The parameter URL always needs to be set in case of one of the above mentioned applications (for example workflow e-mails) and an external web application server (e.g. Tomcat) are to be used.

The following parameters also need to be set in this case. The values are appended to the automatically determined URL or to the URL defined by the URL parameter and taken into account when a connection is being established.       

• fs.url.hostname (optional): this parameter is used to specify a host name for the client connection.
• fs.url.socketport (optional): this parameter is used to specify the port when the client connection is to be established in socket mode (%FIRSTspiritSOCKETURL% placeholder in workflow e-mails).
• fs.url.httpport (optional): this parameter is used to specify the port when the client connection is to be established in HTTP mode (%FIRSTspiritURL% in workflow e-mails).
• fs.url.usehttps (optional): if the HTTPS URL is to be taken into account during a call, this parameter must be set to true. The default value is false.

Example:
From the following configuration in fs-server.conf

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

the placeholder %FIRSTspiritURL% would become:                                

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

the placeholder %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

These parameters usually do not have any impact when used e.g. via the function “Switch to FirstSpirit address” in SiteArchitect in a project that has already been started.

If the connection settings are activated on the start page (see User), according to the order of evaluation described in on page Start page, the fs.url parameter is not taken into account. Unlike this order of evaluation, even though the corresponding parameters defined in the server properties in the Webstart and Start page areas are ignored when the connection settings are disabled, the fs.url parameter is not.

SOCKET_PORT

TCP port where the FirstSpirit server waits for connections for FirstSpirit's own socket protocol. Used for internal communication between servlets and the FirstSpirit server and, if configured, for communication with FirstSpirit SiteArchitect. This parameter is also entered automatically in the web.xml file of the FirstSpirit servlet during startup.

If the value of this parameter is changed, web applications which are installed on the web server must be deleted manually so that they will be rolled out anew with the new port number during the next FirstSpirit start.

INTERNAL_SERVLET_ENGINE (obsolete)

This parameter refers to the no longer supported integrated web server “InternalJetty”. This parameter is no longer required and should be removed.

The value 0 meant that the no longer supported “InternalJetty” was deactivated (default). The value 1 meant that the no longer supported “InternalJetty” was used.

For further information on the use and configuration of web servers under FirstSpirit see also

• page Web server
• chapter Integration into an external web server

SOCKET_HOST (optional)

Host name for the SOCKET_PORT bind address in order to limit the server to one IP address when required. If no value is passed, the server binds to all of the host IP addresses. For notes about using IPv6 see also page IPv6 support.

The SOCKET_HOST parameter (= the interface to which the socket listener is to bind) can only be used when the HOST parameter (= host name over which the server can be reached externally, see above) has also been correctly configured, i.e. mapped to the same server network interface.

SYMBOLIC_HOSTNAME (optional)

Symbolic host name of the FirstSpirit server. This host name is only used for display on the start page and serves no other purpose.

ALLOWED_ENCRYPTIONS (optional)

This parameter can be set for the user to specify what type of encryption must be used in his user's connection settings. When using TLS, the value 1 is set; when using ChaCha20, 2 is set. If no encryption is to be used, the value 0 must be set. Any combination of the parameters 0, 1 and 2 may be used. Example: ALLOWED_ENCRYPTIONS=1,2
If the encryption set by the user does not match the encryption specified here, when logging onto SiteArchitect or when attempting to use the ServerManager, the user will receive an error message stating that the connection parameters were not set correctly; communication between the client and server will not be possible.
For more options for parameterizing TLS encryption please see Parameterizing encryption.

TLS encryption (parameter value 1) cannot be used for the ALLOWED_ENCRYPTIONS parameter if WebSphere is used as the application server for the fs5root web application. In this case, ChaCha20 encryption (parameter value 2) is available for SOCKET or HTTP implementation or HTTPS use. When using HTTPS, encryption is not necessary and therefore parameter value 0 is to be set.

Websocket-Endpoint

For a client connection in HTTP mode, a web socket is used for data transfer if possible.

The websocket endpoint can be deactivated via the websocket.endpoint.enabled parameter:

websocket.endpoint.enabled=false

Default value: true

Note on internal communication (IP multicast)

The FirstSpirit Server sends and receives IP multicast messages to determine which servers are accessible within a network. The multicast messages are sent and received under the address 239.192.34.16 for IPv4 and under the address ff15::efc0:2210 for IPv6 (each with the TCP port 23416).

FirstSpirit Session Cookie

General information

FirstSpirit uses several standard web applications (fs5root, fs5webedit, fs5webmon, fs5preview, fs5staging) as well as possibly additional, project-local web applications (fs5webedit_PROJECTID and fs5preview_PROJECTID) (siehe Server properties / Web applications).

For (user) authentication FirstSpirit, like most other web applications, uses randomly generated session cookies. Through the use of session cookies, the user's login data only has to be transferred once from the web browser to the FirstSpirit server. After the successful login, the web browser uses exclusively the unique session cookie, which is valid for a limited period of time, and which is then sent from the web browser to the server with every further server enquiry, instead of the login data, in order to authenticate the user there.

The session cookie is an integral part of the Servlet API and is used for many other use cases besides authentication.

Configuration

servletSessionCookieName (optional)

The parameter servletSessionCookieName can be used to define a FirstSpirit-specific name for the session cookie for all web applications (default value: not defined; the cookie name specified by the web app server is used – normally JSESSIONID).                                

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

servletSessionCookieName=fs52devsession

However, it is also possible to define a separate specific cookie name for each web application: 
Example:

servletSessionCookieName.fs5webmon=fs52webmonid
servletSessionCookieName.webapp1=fs52webappxid

It is only necessary to change the default value if two or more FirstSpirit servers are operated on the same host with the same URL. In this case, a unique cookie name should be assigned to each FirstSpirit server.

The preconfigured setting for the optional parameters servletSessionCookieName and servletSessionCookieName.ROOT in fs-server.conf was changed:

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

For all FirstSpirit new installations, a FirstSpirit-specific name is preset for the session cookie for all web applications and the root application. This new behavior only affects new installations. The previous configuration will remain active in existing FirstSpirit installations. 

servletSessionCookieSameSite (optional)

The servletSessionCookieSameSite parameter can be used to configure the SameSite attribute for the session cookie.

SameSite is a standard that is intended to prevent cookies from being automatically sent by the browser with so-called cross-site requests and thus offers protection against cross-site request forgery (CSRF). In addition to this security aspect, the SameSite attribute allows you to define which cookies can be read in which context.

In the default setting for the SameSite attribute (in the fs-server.conf configuration file), SameSite=Lax is set as a global value (see below). However, a different configuration is possible.

Crownpeak recommends retaining the default settings of the fs-server.conf configuration file. In most cases the default setting covers both security aspects (good protection against cross-site request forgery) and user concerns (good user experience).
Only in exceptional cases a change is necessary.

The SameSite=None attribute requires a “Secure” flag. Cookies with SameSite=None without a “Secure” flag are rejected by the browser. The “Secure” flag defines that a cookie is always sent over a secure HTTPS connection.

Why do we need the SameSite attribute?

Many browsers automatically restrict third-party cookies. This means all cookies that do not have the SameSite attribute:

• are causing warning messages in the JavaScript console with these browsers, e.g. :
  The cookie "FS52ID" will soon be treated as a cross-site cookie (...). or
• these cookies are automatically restricted to first-level domains

This would lead to problems when FirstSpirit web applications were integrated into other web applications (e.g. as IFrame). In this case the standard browser behavior would ensure that the FirstSpirit session cookies would be blocked by the browser and that the users in the embedded FirstSpirit web application could no longer be authenticated via the session cookie, for example.

Configuration:

The value for the FirstSpirit Session Cookies can be set via the configuration file fs-server.conf, both globally via the parameter servletSessionCookieSameSite and individually for specific WebApp paths, e.g. servletSessionCookieSameSite.fs5webmon=None for FirstSpirit ServerMonitoring. A WebApp-specific configuration overwrites the global setting servletSessionCookieSameSite for this WebApp path.

# 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 

Possible values for the SameSite attibute:

• Strict:
  • The session cookie is only sent in the first-party context (i.e. only if the page for the cookie matches the URL in the browser) and
  • not together with cross-site requests initiated by third-party websites.
• Lax (FirstSpirit default setting):
  • The session cookie is only sent in the first-party context (i.e. only if the page for the cookie matches the URL in the browser) and
  • only together with cross-site requests that are considered safe. This applies to secure HTTP methods (GET, HEAD, OPTIONS, and TRACE) and top-level navigation (actions that cause the URL in the browser address bar to change, such as links). SameSite=Lax is the default setting in modern browsers.
• None:
  • The session cookie is sent in all contexts (i.e. also in the third-party context), i.e. sending is allowed across origins.
  • In this setting, the attribute does not provide any additional protection against CSRF.
  • However, this setting can be useful if a FirstSpirit web application is to be integrated into another web application.
• [empty] Value not set:
  • If the value is not set, the default settings of the Servlet Engine are used.
  • If no value is configured here for the SameSite attribute, the browser default setting is used. Modern browsers interpret an unset SameSite attribute as SameSite=Lax.

clientCookieNames (optional)

This parameter is only necessary if FirstSpirit is operated in conjunction with an application server or a firewall (on the application server) which sets an additional session cookie (e.g., for authentication purposes). The names of these additional session cookies must be communicated to FirstSpirit via the parameter clientCookieNames. When SiteArchitect or ServerManager starts up, FirstSpirit transfers the cookies defined here via the start file – downloaded on the client side – for the FirstSpirit Launcher (FirstSpirit.fslnch).
These cookies are also passed to the browser engine used for the project and are thus available in the SiteArchitect integrated preview. The same cookie is then used in three different session contexts (web browser: HTTP client; SiteArchitect: client/server communication; SiteArchitect: integrated browser engine).

Default value for ClientCookieNames: [empty]

The comma-separated list of cookie names to be entered must include the name of the session cookie for the FirstSpirit web apps as well as the session cookie names for the web app firewall. To define a unique name for the session cookie for the FirstSpirit web apps, the parameter servletSessionCookieName, which defines the name of the session cookie, should also be defined when using clientCookieNames. The variable ${servletSessionCookieName} can be used for including it into the list of clientCookieNames, for example:

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

Certain FirstSpirit SiteArchitect functions are restricted when operated in conjunction with a web app firewall. The following functions, which can be called by the user in SiteArchitect, require SiteArchitect to be restarted manually afterward: changing projects, changing the integrated browser.

The optional configuration of specific values for session cookies is allowed. These attributes can define values for domain, path, and the secure flag of the session cookies, when the corresponding values cannot be read directly from these non-FirstSpirit session cookies:

• clientCookie.{cookieName}.domain: Specifies the domain used for the session cookie. If no value is given, the cookie will carry the URL from which the client was started (including the host name).
• clientCookie.{cookieName}.path: Specifies the path of the session cookie. Default value: /
• clientCookie.{cookieName}.secure: The secure flag limits the transmission of the session cookie. If the value is true, the cookie will only be sent to the server if communication takes place via HTTPS (if the URL meets the domain and path requirements). If the value is false, the cookie will be sent in both HTTP and HTTPS communications.

Example (fs-server.conf):

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

The web app firewall must pass on its own session cookies to the FirstSpirit web apps. In the case of IBM WebSeal, for example, the parameter “Include Session Cookie” must be activated in the Identity area in the “Junction” configuration. Furthermore, the length of the session timeout for the web app firewall must be set to ensure that the time frame is long enough for SiteArchitect to start. 5 minutes is generally sufficient.