STEP supports Transport Layer Security (TLS) with mutual authentication (mTLS) for outbound HTTP traffic. Since mTLS requires trusted certificates from both the server and the client, mTLS can be used instead of basic authentication for additional security.
This functionality is controlled via a set of configuration properties for the key store and trust store to use across all features. These configurations must be set via case-sensitive properties in sharedconfig.properties file on the STEP application server.
Changes to the properties file are implemented when the file is saved. No server restart is required.
mTLS functionality has been tested with the gateway integration endpoint REST plugin, the REST and REST Direct outbound integration endpoint delivery plugins, and URLConnections directly from business rule JavaScript.
Note: The properties starting with SSL.* do not work in combination with the legacy properties RESTDeliverySSLKeyStoreLocation, RESTDeliverySSLKeyStorePassword, RESTDeliverySSLKeyStoreType, and RESTGateway.SSLTrustStoreLocation. SSL.Default properties do not apply to endpoints configured using the legacy properties. Refer to the following section for details on using the SSL.* properties.
mTLS Configuration Properties
The following table lists the default case-sensitive configuration properties for mTLS and their descriptions. The 'SSL. Default.*' properties are the global settings that are applied in OIEP and GIEP configurations where trust store parameters are not available or cannot be edited. To use multiple certificates, refer to the Using Multiple Certificates section below.
Note: The configuration property SSL.Default.TrustStore.Location supersedes the legacy property RESTGateway.SSLTrustStoreLocation. The legacy properties were used in releases prior to 11.0.
| Configuration Property | Description |
|---|---|
SSL.Default.KeyStore.Location |
Full path to the key store file in the file system. For clusters, the key store must be in a directory accessible from all application servers. |
SSL.Default.KeyStore.Password |
Password for the keystore. |
SSL.Default.KeyStore.Type |
The type of keystore. This defaults to 'JKS.' |
SSL.Default.TrustStore.Location |
Full path to the trust store file in the file system. For clusters, the truststore must be in a directory accessible from all application servers. |
SSL.Default.TrustStore.Password |
Password for the truststore. |
SSL.Default.TrustStore.Type |
The type of truststore. This defaults to 'JKS'. |
As an example, the following properties would work together to provide options for selection in the Configuration tab of an OIEP with REST Direct delivery or GIEP with REST:
SSL.Default.KeyStore.Password=password SSL.Default.KeyStore.Location=/home/myDir/keystore.jks
To learn more about the GIEP REST plugin, refer to the Configuring a Gateway Integration Endpoint - REST topic in the Gateway Integration Endpoint section of the Data Exchange documentation here.
To learn more about the OIEP REST Direct delivery method plugin, refer to the REST Direct Delivery Method topic in the OIEP Delivery Methods section of the Data Exchange documentation here.
Using Multiple Certificates
More than one certificate / keystore is useful when each integration requires a different certificate or integrating with multiple systems that use different CNames (the STEP system name as defined by another system). As shown in the following table, add multiple certificates / keystores in the sharedconfig.properties file on the application server after the certificates have been created. An alias, indicated by '[certificate]' in the table, is used to identify a specific certificate.
Note: Adding certificates requires a system restart for the certificates to be used. Changing property values in the sharedconfig.properties file does not require a system restart.
| Configuration Property | Description |
|---|---|
SSL.[certificate].KeyStore.Password |
Password for the keystore. For the [certificate] text, add a unique identifier, for example, 'Cert1'. This case-sensitive text is also required to implement the related location property, RestDirect property, and RestGateway property. |
SSL.[certificate].KeyStore.Location |
Full path to the key store file in the file system. For clusters, the key store must be in a directory accessible from all application servers. For the [certificate] text, add a unique identifier, for example, 'Cert1'. This case-sensitive text is also required to implement the related password property, RestDirect property, and RestGateway property. |
RestDirect.Mtls.CertificateKeyStores |
Keystores available for mTLS with the REST Direct delivery method. |
RestGateway.Mtls.CertificateKeyStores |
Keystores available for mTLS with REST gateway integration endpoints. |
Important: For endpoints configured to use one of the keystores defined using the SSL.[alias].KeyStore properties the legacy properties do not apply.
As an example, the following properties would work together to provide options for selection in the Configuration tab of an OIEP or GIEP:
SSL.Default.KeyStore.Password=password SSL.Default.KeyStore.Location=/home/myDir/keystore.jks SSL.Cert1.KeyStore.Location=/home/myDir/Cert1.jks SSL.Cert1.KeyStore.Password=password SSL.Cert2.KeyStore.Location=/home/myDir/Cert2.jks SSL.Cert2.KeyStore.Password=password RestDirect.Mtls.CertificateKeyStores=,Cert1,Cert2 RestDirectDeliveryURL=1=https://prod.idrix.eu/secure/,2=https://yourDeliveryUrl.com RestGateway.Mtls.CertificateKeyStores=,Cert1,Cert2 RESTGateway.ServerURL=1=https://prod.idrix.eu/secure/,2=https://yourDeliveryUrl.com
Adding a leading comma to the 'CertificateKeyStores' properties (as shown above) allows for selecting no certificate via an empty value in the parameter dropdown. When the empty value is selected in the dropdown, it indicates 'no certificate', but if a default mTLS configuration exists, that default is used. If no default is configured, and the empty value is selected in the dropdown, mTLS is not used.
