Web Application Characteristics

This chapter provides information about Web application characteristics.

Tomcat and Java Versions

Web Center runs with Tomcat 8.5 and 9.0. Web Center runs with Java 11.

Installed Files in the Tomcat Folder

The (initial) DirX Identity Configurator copies some files to folders below Tomcat’s home directory, represented in this description as tomcat_home.Note that the Web Center application itself is not copied to Tomcat.

Automatic integration into Tomcat requires that the DirX Identity Configurator has the appropriate access rights to create and delete files and folders below Tomcat’s home directory, and to adjust file and folder permissions.If the access rights are insufficient, the automatic integration will fail.In this case, complete the integration by performing the steps listed below manually.

Tomcat 8.5 / 9.0

The context descriptor file install_path/web/webCenter-domain/webCenter.xml is copied to the folder tomcat_home/conf/[enginename]/[hostname] under the new name webCenter-domain.xml.The folder and its parent folder are created if they don’t exist.

The Java archive install_path/web/webCenter-domain/endorsed/lib/dmxStorageURL.jar is copied to the folder tomcat_home/dxilib.The folder is created if not yet existing.

The Java classpath for Tomcat is extended with the jar files copied to tomcat_home/dxilib.This is a replacement for the endorsed mechanism used by earlier versions of DirX Identity.Java 11 no longer supports the endorsed mechanism.Make sure the Java system property “java.endorsed.dirs” is not set for Tomcat.

The work folder tomcat_home/work/[enginename]/[hostname]/webCenter-domain is deleted (if it exists.)

On UNIX, the files are created with permissions 644 and the folders with permissions 755. The files must at least be readable for the Tomcat service.For file password.properties see the corresponding section in the chapter “Security”.

enginename and hostname vary with the Tomcat installation.The engine name is usually Catalina or Standalone, the host name localhost.

Tomcat Configuration

Web Center encodes any HTTP request and response data based on UTF-8 in order to support the full range of Unicode characters.This applies also to the values of HTTP GET request parameters.Tomcat, however, decodes such values by default based on ISO-8859-1. Therefore, parameter values containing characters outside 7-bit ASCII are incorrectly passed to Web Center.

To fix the problem, open file tomcat_home/conf/server.xml and add attribute “useBodyEncodingForURI” with value “true” to any connector in use (like HTTP, HTTPS, AJP), For example:

<Connector port="8080" protocol="HTTP/1.1"

useBodyEncodingForURI="true" …

Note that Web Center sends most HTTP requests via POST.Since POST requests are not affected the problem may take some time to show up after installation.

Running Tomcat behind a Proxy or Load Balancer

Tomcat may run behind a proxy server (or a load balancer).The browsers send their HTTP requests to the proxy, and the proxy forwards them to Tomcat.The responses are sent by Tomcat to the proxy, and then forwarded from the proxy to the browsers.

If the browsers connect to the proxy via HTTPS while proxy and Tomcat are connected via HTTP, a problem with redirected requests might occur.

Tomcat generates redirect URLs starting with “http://<tomcat-host>:<tomcat-port>”.Some proxies replace the host but leave protocol and port untouched: “http://<proxy-host>:<tomcat-port>”.The browsers then follow the redirect using HTTP instead of HTTPS to the proxy, and also probably with the wrong port.

You can fix this by changing the HTTP connector in Tomcat’s configuration file tomcat_home*/conf/server.xml*.Set the “scheme” to “https” and set attributes “proxyName” and “proxyPort” to the host name and port of the proxy server, respectively.

<Connector port="8080" protocol="HTTP/1.1" …
scheme="https"
proxyName="<proxy-host>"
proxyPort="443"
/>

Setting the scheme to “https” does not mean that Tomcat and the proxy use HTTP over SSL.

In case the browsers connect to the proxy via HTTPS and the proxy to Tomcat via HTTP, you should also tell Tomcat to add the secure-flag to session-cookies.This tells the browsers to send session-cookies only over secure connections.By default, Tomcat does not set the secure-flag in such cases because it’s contacted by the proxy via an unsecured connection.You can enable the secure-flag in file WEB-INF/web.xml:

<session-config>
…
<cookie-config>
<secure>true</secure>
</cookie-config>
</session-config>

Deploying Web Center on a Remote Server

Web Center may run on a remote server other than the central DirX Identity server with the provisioning store.

You don’t have to install DirX Identity on the remote server.But doing so makes configuration a bit easier.In both cases, configuration involves steps on the central and the remote machine.

Remote Server with DirX Identity Installation

Central Server

  • Install and configure DirX Identity (with or without Web Center) on the central server.

  • Make sure that remote access to any server to be contacted by the remote Web Center is not prohibited by a firewall. This affects directory, message broker and request workflow server (See section Socket Ports below.)

Remote Server

  • Install DirX Identity on the remote server. As components to install, select only “Provisioning directory schema and data” and “Web Center”.

  • Configure DirX Identity on the remote server. As configuration options, select “Web Center Configuration” only.

  • On the following pages, enter host, port etc. of the central directory server for provisioning, and the domain information. For Web Center, enter the local Tomcat’s installation directory and service name.

  • If applicable, set up single sign-on as described in the User Interface Guide.

Remote Server without DirX Identity Installation

Central server

  • Install DirX Identity.

  • If you don’t have a Tomcat installation on the central server or don’t want to deploy Web Center into that installation, create a dummy Tomcat installation as described at the end of this section.

  • Configure DirX Identity, thereby deploying Web Center into the (dummy) Tomcat installation on the central server. When deploying Web Center into a dummy Tomcat installation, do not enter a Tomcat service name and don’t check the flag to start the Tomcat service after installation.

  • Make sure that remote access to any server to be contacted by the remote Web Center is not prohibited by a firewall. This affects directory, message broker and request workflow server (See section Socket Ports below.)

  • Copy the webCenter-domain folder from the central server’s install_path/web folder to any folder on the remote machine.

Remote server

  • Copy the Java archives in folder webCenter-domain/endorsed/lib to folder tomcat_home/dxilib. Create the folder if it does not exist.

  • Extend Tomcat’s Java classpath with the full path names of the jar files in the folder tomcat_home/dxilib.

  • Adjust the configuration parameters in file webCenter-domain/webCenter/WEB-INF/web.xml:

  • com.siemens.webMgr.ldap.host

  • com.siemens.webMgr.ldap.port

  • com.siemens.webMgr.ldap.ssl

  • com.siemens.webMgr.requestworkflow.keystoreName – If applicable; note that the placeholder @DIRXIDENTITY_INST_PATH@ cannot be replaced at runtime since there is no installation.

  • If applicable, set up SSL to the directory server, message server or Java-based Server as described in the DirX Identity Connectivity Administration Guide.

  • If applicable, set up single sign-on as described in the User Interface Guide.

  • Copy the context descriptor file webCenter-*domain/webCenter.xml* to folder tomcat_home/conf/[enginename]/[hostname] and rename the copy to webCenter-domain (or any other name you want to use to access the Web Center application in a browser.) Create the folder if not yet existing. Open the file and change the docBase to the full path name of the webCenter-domain/webCenter folder.

  • Make sure that all files and folders have the appropriate access rights. The files must be readable for Web Center, which means for the Tomcat server Web Center is deployed into. For file password.properties see the corresponding section in chapter “Security”.

  • If existing, delete folder tomcat_home/work/[enginename]/[hostname]/webCenter-domain.

  • Restart Tomcat.

enginename and hostname vary with the Tomcat installation. The engine name is usually Catalina or Standalone, the host name localhost.
Dummy Tomcat Installation

A dummy Tomcat installation is any folder with the following subfolders:

  • bin

  • dxilib

  • conf

  • conf/Catalina

  • conf/Catalina/localhost

Hints on Tomcat

  • Tomcat is delivered with some sample applications.In a productive environment, most sample applications are not needed, and you should undeploy them by removing the respective files from folders tomcat_home/webapps and tomcat_home/conf/[enginename]/[hostname].

  • On some systems, Tomcat may log error messages “SEVERE: Error filterStart” during start-up.These messages are caused by some of the sample applications and do not affect Web Center.

  • For a slight but easy performance improvement, set the initialization parameter trimSpaces of the JSP servlet (with servlet name jsp) in tomcat_home/conf/web.xml to “true”.

  • When running under Tomcat on a UNIX or Linux system, Web Center pages may occasionally be broken due to a failed attempt to access an X display server.In Tomcat’s log file, you will find an error message like "Can’t connect to X11 window server using '0:0' as the value of the display".Since access to an X display server is not really required, we recommend setting the Java system property java.awt.headless to true on such systems; for example, in tomcat_home/bin/catalina.sh:
    JAVA_OPTS=-Djava.awt.headless=true.

Peculiarities and Restrictions

This section provides information about peculiarities and restrictions.

Reloadability

Web Center is reloadable.If you reload (or stop and restart, or re-deploy) the application in the Tomcat Web Application Manager, Tomcat will log some messages about threads and ThreadLocals that might cause a memory leak but you can safely ignore them.

Undeployment

If you undeploy a Web Center application in the Tomcat Web Application Manager, its context descriptor file is deleted.

On changes to a context descriptor file, Tomcat re-deploys the respective application, which leads to the same warnings as mentioned above.

Session Persistence

Web Center sessions are not serializable.That means if you reload the application or restart Tomcat, all sessions get lost.

Tomcat, by default, attempts to persist sessions on application unload.This feature is disabled in Web Center’s context descriptor webCenter-domain.xml.

Distributability

Since the sessions are not serializable they are also not distributable among several servers in a Tomcat cluster.You may run Web Center behind a load balancer with sticky sessions only.

Socket Connections

Web Center interacts with several servers via socket connections.It reads the servers’ host names, ports and SSL flags from web.xml or the configuration database.

The host names must be appropriately specified.Names like “localhost” and “127.0.0.1” or simple host names will not work if Web Center and the server reside on different machines or in different domains.We recommend using fully qualified host names or IP addresses.

Also, if a server is located on a different host than Web Center, any intermediate firewall must grant Web Center access to the server port.

Directory Server for Provisioning

Host, port and SSL flag are taken from web.xml.The default ports are 389 for non-SSL connections and 636 for SSL-connections.

Directory Server for Connectivity

Host, port and SSL flag are taken from the provisioning directory. In the DirX Identity Manager, open view “Provisioning/Domain Configuration” and select tab “General” of the domain object.

The default ports are 389 for non-SSL connections and 636 for SSL-connections.

Message Broker

Web Center contacts the message broker for sending events like password change events.

Host, port and SSL flag are taken from the connectivity directory. In the DirX Identity Manager, open view “Connectivity/Expert View” and go to object “Configuration/Services/System/Message Broker index”.

The default port is 61616 for non-SSL and 61617 for SSL connections.

In a high availability scenario, ensure access to primary and secondary message broker.

Java-based Server

Web Center contacts the Java-based Server for processing request workflows.

Host, port and SSL flag are taken from the Connectivity directory. In the DirX Identity Manager, open the view “Connectivity → Expert View”. For port and SSL flag, go to object “Configuration → Services → System → Java-based Server name”. For the host name, open the system object that is referenced on that page.

The default port is 40000 for both SSL and non-SSL connections.

In a high availability scenario, ensure access to primary and secondary Java-based Servers.