Configure Runtime access and security

Overview

With its default configuration, xDI Runtime only listens to connections from localhost on its default ports. It only accepts commands and requests from users defined in the configuration file.

To configure and secure access to your runtime, you can customize the following Runtime settings in the engineParameters.xml configuration file:

Configuration example

The following example demonstrates a basic secure configuration with the following elements:

  • A non-standard port

  • An encryption key

  • Multiple accounts with role assignments

  • IP address restrictions

<parameters>
<...>
  <engineParameters>
  <...>
   <parameter name="httpServerPort" value="42205"/>
   <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. You must define at least one user.
4 Optional network access restrictions by IPv4, IPv6, or hostname address.

Change the port used by the runtime

By default, xDI Runtime listens for connections on port 42200.

To change this port, find the httpServerPort parameter, and set the value to the desired port. Make sure it does not overlap with other applications.

<parameters>
<...>
  <engineParameters>
   <...>
   <parameter name="httpServerPort" value="42200"/>
   <...>
  </engineParameters>
<...>
</parameters>

When using a non-default port, the stopengine script requires the -port argument to reach the runtime.

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 necessary to secure all HTTP endpoints (REST and SOAP) with TLS.
Table 1. Communication Security Parameters
Parameter Default value Description

webServiceSecureProtocol

Protocol used to secure the endpoints. The value should follow the SSLContext naming convention in Java. For example: TLS or TLSv1.2.

webServiceKeyStoreFile

Path to the Java keystore containing the certificate used to secure the endpoints.

webServiceKeyStoreType

Java keystore type, such as JKS.

webServiceKeyStorePassword

Password of the keystore file.

webServiceKeyAlias

Alias of the key in the keystore.

webServiceKeyPassword

Password of the key.

enableAccessRestrictionOverHTTP

false

Defines whether runtime access restrictions can be changed when the Runtime is not secured with HTTPS. This parameter defaults to false for security purposes.

HTTP connections are not secure, and allow attackers to monitor your network traffic and bypass access restrictions. You should never set this parameter to true, except if you are certain that no attacker can intercept network traffic in your environment.

For more information, see the section about runtime access restriction.

Configure the clients

When 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:

  • 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.

You must define at least one user in the Runtime configuration file. The Runtime cannot start if there is no security element or no user defined in the configuration.

Standard users

Define users as in the following example:

Example 1. User configuration
<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>
Table 2. User configuration properties
Parameter Description

name

User name to use as login credential.

password

Encrypted password for the user.

uncryptedPassword

Unencrypted (plain text) password for the user.

roles

Space-separated list of roles for the user. The possible roles are:

  • Connect: adds permissions to connect to the Runtime (required)

  • View: adds permissions to list and view all the sessions of the Runtime.

  • Execute: adds permissions to execute deliveries on the Runtime from xDI Designer, xDI Analytics, and the command line.

  • ExecuteAPI: adds permission to execute deliveries on the Runtime through the API endpoints (REST and SOAP).

  • Monitor: adds permission to access Runtime metrics and health information from an HTTP endpoint.

  • Admin: full permissions on the Runtime. This is required for operations such as purging the sessions or scheduling deliveries.

  • Passwords are encrypted using the encrypt <password> command on the Runtime engine console (engine command line tool).

  • You should set either the password or uncryptedPassword property, but not both.

  • A user can have multiple roles, separated by space characters.

Anonymous user

Optionally, you can define a single anonymous user who can access the runtime without authentication. Not all roles are available to this user account.

Example 2. Anonymous user configuration
<parameters>
<...>
  <security>
   <...>
   <user anonymous="true" roles="Connect View"/>
   <...>
  </security>
<...>
</parameters>
Table 3. Anonymous user configuration properties
Parameter Description

anonymous

Defines that this user is the anonymous user. Must be set to true.

roles

Space-separated list of roles for the user. The possible roles are:

  • Connect: the user can connect to the runtime (required).

  • View: the user can list and view all the sessions of the runtime.

  • Execute: the user can execute deliveries on the runtime

  • Admin: the user has the full permissions on the runtime. This is required for operations such as purging the sessions or scheduling deliveries.

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 fails.

Restrict access by hostname/IP address

The default configuration only allows connections to the runtime from localhost. You can add more entries to the configuration file to allow other devices to connect, or disable access restriction altogether.

The configuration file supports hostnames, IPv4, and IPv6 addresses, or IP addresses in single or CIDR notation.

You can only change access restrictions 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.
Example 3. Hostname/IP address configuration
<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.
Example 4. Disabled hostname or IP address configuration
<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.

Example 5. Hostname/IP address configuration file reference
<!-- Security Configuration (users and IP/Hostname Filtering) -->
<security file="./security-access.xml"/>
Example 6. Sample hostname/IP address restriction configuration file (security-access.xml)
<security>
  <...>
  <allow address="localhost"/>
  <allow address="192.168.0.42"/>
  <allow address="Hostname or IP Address"/>
<security>