When deploying applications servers, security is a very important consideration. Apama contains some security features, but predominantly uses the native features of the platform it runs on to secure access to it. This enables us to concentrate on the functionality of our product and to reuse a trusted security mechanism.
Correlator management port
The most important thing to secure is the correlator management port (by default 15903). Access to this port gives you the ability to inject and run arbitrary EPL or Java code within the correlator. It also lets you send any event to the application running in the correlator. Therefore access to the management port must be restricted only to trusted users. It must not be exposed to the public internet.
Binding to localhost
The first and most common way to secure the management port is to have the correlator bind to the localhost address. The means that only users who can run on the server can connect to the correlator. Use the operating system access controls to restrict access to the server only to authorized users.
To bind the correlator to a specific address use the configuration file:
server:
bindAddress: 127.0.0.1
If you use this option then EPL code and events will also only be able to be delivered to the correlator from localhost using the Apama client library and tools. For production deployments we recommend use of the configuration file to deploy your application into the correlator:
correlator:
initialization:
list:
- ${PARENT_DIR}/Events.mon
- ${PARENT_DIR}/Application.mon
This configuration can be generated using the engine_deploy tool to convert from a project built in Software AG Designer or can be written by hand for your application.
For event delivery it is recommended that applications use In-process connectivity adapters as an alternative to external applications connecting to the correlator mangement port. Outbound connections from the correlator are acceptable but where possible incoming connections should be avoided. Where that can not be avoided or for more fine-grained access controls see the sections on the HTTP server and Universal Messaging below.
Use within Docker
When Apama is deployed within a Docker container the management port is exposed within the Docker network that container is part of or any containers its linked to. Use the Docker networking to connect together parts of your application which should have access to the correlator’s management port without exposing it to any other users. We do not recommend using Docker to map the management port to a publically-accessible port.
Access to the Docker containers / host must be restricted to only authorized users.
Deploying applications in a Docker container should use the same patterns as deploying to a localhost-bound correlator in the previous section. In addition, if you do have processes that must directly connect they can be deployed in containers which are linked to the correlator container:
docker run -d --link correlator_container:correlator connecting_application
Operating system / network firewall
If you have to deploy your correlator management port to be accessible from other machines then you need to setup firewalling to correctly restrict access. For Windows, use the Windows firewall. For network firewalls consult your vendor. This approach is not recommended for an untrusted network since an unauthorized user might be able to spoof the address from which they are sending data. Instead use a VPN or other overlay network which provides data authenticity.
On Linux you can use iptables to control the firewall on the host. The following commands will create a chain in iptables which permits connections from a list of addresses:
# Create a new chain for the correlator that defaults to reject
iptables -N correlator-permit
iptables -P correlator-permit REJECT
# Direct new connections on port 15903 to the new chain, but accept all packets for existing connections
iptables -A INPUT -j correlator-permit -p tcp --dport 15903 --syn
iptables -A INPUT -p tcp !--syn -j ACCEPT
# Add authorized hosts to the new chain
iptables -A correlator-permit --source 10.0.0.1 -j ACCEPT
iptables -A correlator-permit --source 10.0.0.2 -j ACCEPT
Filesystem access
Application code, configuration and internal databases are stored on the filesystem of your server. You need to ensure that none of these are writeable by other users. To do this you should create a user account which only your correlator will run under. Once you have done that you should change the ownership of all your configuration and application files to this new user. It is also recommended that you make them not world readable as well as not world writeable.
On Windows you can do this using the security dialog in Windows explorer. On Linux you can run the following commands:
chown correlatoruser -R ${APAMA_WORK}
chmod og -rwx -R ${APAMA_WORK}
Storing passwords
Several components within the correlator can be provided passwords via the configuration file – typically for the correlator to authenticate against external services. When you provide these secrets via the configuration file they will be in plain text in the configuration file. You must use standard operating system controls to make the file unreadable by any untrusted people, particularly if the filesystem is shared or the backup server has a different set of authorized users. To make a file non-world-readable on Windows use the Windows security interface.
On Linux you can run:
chmod o-r config.yaml
If you don’t want to store your passwords on disk, you can instead pass them on the command line at startup time. To do this you need to use a replacement property in the configuration file and then define it on the command line with -D. Note that in this case while the password will not be stored on disk, it will be visible to other users on the machine, so may not be suitable for all use cases.
httpclient:
authentication:
user: myuser
password: ${HTTP_PASSWORD}
correlator --config application/ -DHTTP_PASSWORD=hunter2
Universal Messaging
Software AG Universal Messaging (UM) is our recommended solution for when you need to apply user access controls to message delivery. UM supports TLS encryption on all communications, authenticated by client certificates and keys. It can be configured to filter messages based on users or other criteria. The correlator makes an outgoing connection to UM so it can be configured to have no inbound connections.
Universal Messaging can be added to your project via the Universal Messaging bundle in Software AG Designer. Alternatively, provide a variation on the following configuration file:
connectivityPlugins:
UMTransport:
libraryName: UMConnectivity
class: UMTransport
dynamicChainManagers:
UMManager:
transport: UMTransport
managerConfig:
rnames: nsps://umhost:9000
authentication:
username: myuser
certificateFile: ${PARENT_DIR}/um.pem
certificatePassword: ${UM_CERT_PASSWORD}
HTTP server
The correlator provides an in-process HTTP server transport to provide a REST API for other processes to deliver events to the correlator. While this is a supported way to deliver events across an untrusted network we recommend that any deployment on the internet is behind a reverse HTTP proxy such as Nginx or Apache. In addition you must configure authentication and TLS on the HTTP server transport.
The HTTP server provides two built-in security mechanims.
TLS
TLS provides confidentiality and integrity of events being delivered to the REST API. It also provides authentication of the server to the clients. We recommend all deployments across an untrusted network enable TLS. To do this provide the following options when configuring your HTTP server transport:
dynamicChainManagers:
httpServer:
transport: httpServer
managerConfig:
port:443
tls: true
tlsKeyFile: ${PARENT_DIR}/servername.key.pem
tlsCertificateFile: ${PARENT_DIR}/servername.cert.pem
You must create the key and certificate yourself, signed by a certificate authority which will be trusted by all connecting clients.
HTTP basic authentication
TLS secures the contents of the messages, but does not identify the clients to the host. If your transport is connected over a network to which untrusted users have access then you must also enable authentication. The HTTP server only supports HTTP basic authentication configured via a static file provided in the correlator configuration file.
The password file can be created using the httpserver_passman tool provided with Apama. Alternatively it is also compatible with Apache’s htpasswd -B tool. Passwords are stored in a hashed (using bcrypt) + salted file for security.
To enable authentication add the following configuration to your HTTP server transport:
dynamicChains:
... (mapping rules)
- httpServer:
authentication:
authenticationType: HTTP_BASIC
allowedUsersFile: ${PARENT_DIR}/userfile.txt
Further information
For further information about any of these topics see the full documentation at: Software AG Product Documentation and questions and discussion to the forums.
– Matt