Configure Runtime security
Overview
A Runtime with a default configuration only listens to connections from localhost
. In order to run commands and control you have to log in with a user defined in the configuration file.
You can enhance and customize the following Runtime security settings in the engineParameters.xml
configuration file:
-
Secure communications with TLS for HTTP (REST and SOAP) endpoints.
-
Configure authenticated access with roles and permissions.
A basic secured configuration sample is given below.
<parameters>
<...>
<engineParameters>
<...>
<parameter name="webServiceSecureProtocol" value="TLSv1.1"/>(1)
<parameter name="webServiceKeyStoreFile" value="D:/keystore/mykeystore.jks"/>
<parameter name="webServiceKeyStoreType" value="JKS"/>
<parameter name="webServiceKeyStorePassword" value="keystore_password"/>
<parameter name="webServiceKeyAlias" value="key_alias"/>
<parameter name="webServiceKeyPassword" value="key_password"/>
<...>
</engineParameters>
<...>
<security> (2)
<user name="admin" uncryptedPassword="admin-password" roles="Admin"/> (3)
<user name="developer" uncryptedPassword="developer-password" roles="Connect View Execute"/> (3)
<user name="api-user" uncryptedPassword="api-user-password" roles="Connect ExecuteAPI"/> (3)
<user name="viewer" uncryptedPassword="viewer-password" roles="Connect View"/> (3)
<allow address="192.168.0.42"/> (4)
<allow address="192.168.0.43"/> (4)
<allow address="2001:db8:3c4d:0::abee"/> (4)
</security>
<...>
</parameters>
1 | Secure HTTP (REST and SOAP) endpoints with TLS. |
2 | Security node that holds users, roles, and network restrictions. A security configuration is mandatory. |
3 | User definition with associated roles. At least one user must be defined. |
4 | Optional network access restrictions by IPv4, IPv6, or hostname address. |
Secure communications with TLS
Configure the Runtime
To enable TLS for HTTP (REST and SOAP) endpoints, you have to define the following parameters:
<parameters>
<...>
<engineParameters>
<...>
<parameter name="webServiceSecureProtocol" value="TLSv1.1"/>
<parameter name="webServiceKeyStoreFile" value="D:/keystore/mykeystore.jks"/>
<parameter name="webServiceKeyStoreType" value="JKS"/>
<parameter name="webServiceKeyStorePassword" value="keystore_password"/>
<parameter name="webServiceKeyAlias" value="key_alias"/>
<parameter name="webServiceKeyPassword" value="key_password"/>
<...>
</engineParameters>
<...>
</parameters>
Keystore and certificate details are mandatory for TLS. They are needed to secure all HTTP endpoints (REST and SOAP). |
Parameter | Default value | Description |
---|---|---|
|
Protocol to be used to secure the endpoints. For example, TLSv1.1. |
|
|
Path to the Java keystore containing the certificate used to secure the endpoints. |
|
|
Java keystore type, such as |
|
|
Password of the keystore file. |
|
|
Alias of the key in the keystore. |
|
|
Password of the key. |
|
|
false |
Defines whether runtime access restrictions can be changed when the Runtime is not secured with HTTPS. This parameter defaults to HTTP connections are not secure, and allow attackers to monitor your network traffic and bypass access restrictions. You should never set this parameter to For more information, see the section about runtime access restriction. |
Configure the clients
When the Runtime endpoints are secured with TLS and a certificate, clients such as Designer, Analytics, or command line scripts use that certificate to communicate with the Runtime.
The clients that connect to the Runtime must therefore:
-
Use the HTTPS protocol:
-
When connecting to the runtime, make sure to use HTTPS instead of HTTP in all URLs. As an example, see Runtime
connect
command and Runtime configuration in Analytics.
-
-
Provide the certificate to the client, if necessary:
-
If you use a certificate signed by an authority, you do not need to provide it to the clients.
-
If you use a self-signed certificate, you must provide it to the clients, because Java refuses connections with a self-signed certificate by default, for security purposes. For this, add the certificate to the Truststore of the JVM used by the clients.
-
Configure authenticated access
Summary
You must define users and their associated roles that will be used to connect to the Runtime.
At least one user must be defined in the Runtime configuration file. The Runtime will not start if there is no security element or no user defined in the configuration. |
Standard users
Users are defined as shown below:
<parameters>
<...>
<security>
<...>
<user name="user01" password="xxxxxx" uncryptedPassword="password" roles="Connect View Execute"/>
<user name="user02" password="xxxxxx" uncryptedPassword="password" roles="Connect View Execute ExecuteAPI"/>
<user name="user03" password="xxxxxx" uncryptedPassword="password" roles="Connect View Monitor"/>
<...>
</security>
<...>
</parameters>
Parameter | Description |
---|---|
|
User name to use as login credential. |
|
Encrypted password for the user. |
|
Unencrypted (plain text) password for the user. |
|
Space-separated list of roles for the user. The possible roles are:
|
|
Anonymous user
You can define an anonymous user to give access to the Runtime without authentication, with default roles. This is optional, and only one anonymous user can be defined.
When the anonymous user is defined, the Runtime can be accessed with no authentication, and the tasks associated with the defined roles can be performed.
<parameters>
<...>
<security>
<...>
<user anonymous="true" roles="Connect View"/>
<...>
</security>
<...>
</parameters>
Parameter | Description |
---|---|
|
Defines that this user is the anonymous user. Must be set to |
|
Space-separated list of roles for the user. The possible roles are:
|
You can define both an anonymous user with limited privileges and authenticated users with more privileges. |
To connect using the anonymous user, no user/password pair should be sent to the Semarchy xDI Runtime, otherwise the connection will fail. |
Restrict access by hostname/IP address
The default configuration only allows connections to the runtime from localhost
. You can add new entries to the configuration file to allow other devices to connect, or disable access restriction altogether.
The configuration file supports hostnames, IPv4 and IPv6 single addresses, or IP addresses in CIDR notation.
Note that access restrictions can only be changed when the Runtime is secured with HTTPS. If the Runtime uses HTTP, access is limited to localhost for security purposes. You can override this security policy by changing the enableAccessRestrictionOverHTTP
parameter.
If you try to connect to the runtime locally by using the IP address of the local machine instead of localhost , the connection may fail because the runtime interprets it as an external connection. You can get around this restriction by adding a new entry with this IP address, or use localhost for all local connections.
|
<parameters>
<...>
<security>
<...>
<allow address="localhost"/> (1)
<allow address="192.168.0.42"/> (2)
<allow address="192.168.0.0/16"/> (3)
<allow address="2001:db8:3c4d:1::/64"/> (3)
<allow address="Hostname, IP Address or Subnet Mask"/>
<...>
</security>
<...>
</parameters>
1 | Allows the specified Hostname to access the Runtime. |
2 | Allows the specified IP Address to access the Runtime. |
3 | Allows any address of the specified Subnet Mask to access the Runtime. |
<parameters>
<...>
<security>
<...>
</security>
<...>
</parameters>
You can also configure access restriction in an external file, referenced by a single tag in the engineParameters.xml
configuration file.
The path to this file is relative to the engineParameters.xml
location.
<!-- Security Configuration (users and IP/Hostname Filtering) -->
<security file="./security-access.xml"/>
<security>
<...>
<allow address="localhost"/>
<allow address="192.168.0.42"/>
<allow address="Hostname or IP Address"/>
<security>