PLANTA secure New from S 39.5.22

Information

• PLANTA secure provides a high security standard using the two-factor authentication (2FA) as recommended by the German Federal Office for Information Security.
• For more information, please contact your PLANTA consultant.

PLANTA Secure Components

Overview

• For wrapping a TCP connection in HTTP, the BOSH protocol is employed. It keeps both latency and overhead low, and the basic principle of a connection manager is just what we need. Its development and widespread use is pretty XMPP centric, though it is capable of transporting arbitrary payloads.
• Please refer to http://www.xmpp.org/extensions/xep-0124.html for a detailed specification of the protocol per se. The implementation by PLANTA focuses on a single stream, protocol version 1.6, and leaves out the support for legacy counterparts or even polling clients. Acknowledgements are not used, though might be implemented in case this should improve reliability. So far, resends are also not employed; if the connection is interrupted and HTTP requests fail, the PLANTA session will be terminated as per the normal TCP connection.

Installation Instructions

• The Server Adapter needs to be configured as outlined in its specific section below, and deployed in a servlet container. A direct TCP connection to a preexisting PLANTA Server is required, and for single sign-on via proxy authentication, S 39.5.20 or newer with a small configuration change.
• The Client Adapter can be used as-is after setting the application configuration as outlined in its specific section below. An existing PLANTA Client needs to be available.
• Common authentication methods of the company, like smart cards, can be addressed via respective plug-ins. For more information, please contact your PLANTA consultant.

PLANTA Server

• The configuration of the PLANTA Server can remain unchanged, unless single sign-on via proxy authentication is desired.
• In the config/globals.conf configuration file, the 'proxy' additionextension must be added to the authentication method directive in order to permit proxy pre-authentication. This will grant trust to the incoming connection, log on the specified user ID without any further checks.
  • The risk is thus the same as in OS user-login, with the difference that the server adapter is the party which is trusted blindly here instead of the client. Hence, the connection to the Server Adapter needs to be encrypted and authenticated for this scenario to be secure!
• In the Python module ppms.proxy_auth, there is a predefined method proxy_auth_resolve_username(proxy_user) that will be called from the Server. It is supposed to return the PLANTA user ID to log on to the system. The default implementation will pass on the proxy user ID.

Server Adapter

• The Server Adapter comes as a Java Servlet that can be configured
  • in terms of deployment: via the standard WEB-INF/web.xml,
  • in terms of the backend: via the self-documenting WEB-INF/classes/config.properties and
  • in terms of logging: via WEB-INF/classes/logback.xml.

Details

• A prerequisite for a secure setup is a preexisting application server in which the servlet can be made available. The environment must support the Java Servlet API version 3.0 or later and Java version 1.8 or later. In order to satisfy security requirements, this application server instance must be configured to allow only trusted requests from the reverse proxy, i.e. HTTPS with mutual authentication. Here it is exemplified how Let's Encrypt certificates are stored in the tomcat server.
• The TCP connection between the Server Adapter and the PLANTA Server is not encrypted by default. SSL can be activated by carrying out the following steps:
  • replacement of keystore.jks and truststore.jks in the web archive
  • execution of planta_ssl as a back-end protocol and
  • configuration of the respective password in config.properties
    • An encrypted PLANTA Server instance wrapped via STunnel is required.

Reverse Proxy

• The BOSH protocol does not work with HTTP pipelining, and it is disabled in the Client Adapter. Hence the reverse proxy must not employ HTTP pipelining when forwarding requests to the Server Adapter.
• Persistent connections as of HTTP 1.1 / keepalive should be enabled for improved latency and throughput, esp. when using SSL-encrypted connections.

Details

• The value specified for bosh.session.max_wait in the config.properties of the servlet must be smaller than the "request timeout" oder "read timeout" of the reverse proxy; otherwise polling requests may be aborted with a "504 gateway timeout error".
  • This can just as well be taken care of the other way around - if a lower maximum request timeout is desired, max_wait should be slightly below that value in order for polling requests not to run into trouble.
• If proxy authentication is enabled in the Server Adapter, the name of a HTTP header containing the user ID can be configured. The value of this field is passed on to the PLANTA Server as-is. Further processing is subject to customizing. See the "PLANTA Server" section for further information.

Here is a sample nginx configuration excerpt for a working reverse proxy setup

http {
    server {
        location /planta {
            # servlet location as defined during deployment
            proxy_pass http://servletcontainer.example.com:8080/PlantaServerAdapter/;

            # read timeout needs to be be set >= the value of
            # bosh.session.max_wait in the servlet's config.properties, which
            # defaults to 900
            proxy_read_timeout  900s;

            # persistent connections as per http keepalive improve both latency
            # and throughput, esp. with SSL connections
            proxy_http_version  1.1;
            proxy_set_header Connection  "";

            # just push some dummy value as proxy-authenticated user
            proxy_set_header iv-user nobody;
        }
    }
}

Client Adapter

• The Client Adapter comes as a .NET client application that can be configured via self-documenting application configuration, PlantaClientAdapter.exe.config.
• The Client Adapter will pass on all command line arguments to the client. A potential server= parameter will be removed since the Client Adapter provides its own host and port, effectively rerouting the client connection to itself.