Mutual Transport Layer Security

STEP supports Transport Layer Security (TLS) with or without 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.

STEP supports inbound mTLS on Stibo Systems SaaS environments. Inbound mTLS is possible for on premise systems but requires custom development.

Outbound mTLS

For Stibo Systems SaaS environments, a default trust store and keystore is automatically configured and the SSL Client Certificates functionality can be used to manage certificates and download the Stibo Systems provided client public key. For more information, refer to the SSL Client Certificates topic. Configuration properties are only required to use a custom client public key, as defined in the Using Multiple Certificates section below.

For on-prem environments, a set of configuration properties must be configured for the key store and trust store to use across all features via case-sensitive properties in sharedconfig.properties file on the STEP application server.

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 case-sensitive 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 case-sensitive configuration property SSL.Default.TrustStore.Location supersedes the case-sensitive legacy properties RESTGateway.SSLTrustStoreLocation and RESTDeliverySSLKeyStoreLocation (there is no period before SSL for this property), and also when using TLS without mutual authentication. The legacy properties were used in releases prior to 11.0.

Restart the server after making changes to the SSL.* properties.

Important:  

  • Keystores must each only hold a single key / certificate.

  • Keystore imports must include a private key and public key (Entry type: PrivateKeyEntry).

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

When using TLS without mutual authentication (using a self-signed certificate), no key store is required and only the trust store configuration properties must be set. If no trust store is configured, the connection is established using a certificate signed by a recognized Certification Authority, such as Verisign or Thawte.

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 a GIEP with REST:

SSL.Default.KeyStore.Location=/shared/customer-config/keystore/keystore.jks
SSL.Default.KeyStore.Password=password

In this image, below the 'MTLS Authentication' heading, the 'Certificate Key Store' parameter is empty since a default key store has been configured.

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.

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.

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.

For Stibo Systems SaaS environments, one or more additional certificates can be configured using this method, for example, for certain integration, to use a custom client public key instead of the client public key provided by Stibo Systems.

Note: A system restart is required when adding certificates or when changing property values in the sharedconfig.properties file.

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: The legacy properties do not apply to endpoints configured to use one of the keystores defined using the SSL.[alias].KeyStore properties.

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=/shared/customer-config/keystore/keystore.jks

SSL.Cert1.KeyStore.Location=/shared/customer-config/keystore/Cert1.jks
SSL.Cert1.KeyStore.Password=password
SSL.Cert2.KeyStore.Location=/shared/customer-config/keystore/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.

Inbound mTLS for Stibo Systems SaaS

Setting up inbound mTLS on a Stibo Systems SaaS environment includes working with Stibo System Technical Support, as defined below.

Inbound mTLS is available for RESTAPI, GraphQL, and SOAP.

To use inbound mTLS on your Stibo Systems SaaS environment:

  1. Create a ticket in the Stibo Systems Service Portal:

    • Request configuration of STEP Inbound mTLS Authentication.

    • Attach public certificate(s) for use with mTLS.

      Important: Never share private certificates.

  2. Technical Services configures the SSL profile, attaches the provided certificates, and creates a CName for mTLS requests.

    mTLS requests must use the <environment>+'-mtls' suffix: acme-mtls.mdm.stibosystems.com

  3. Technical Services configures the following sharedconfig.properties for your environment and will need to schedule a restart of your system(s) to complete the setup:

    • HTTP.Service.MTLS.CertificateSubject.Template

    • HTTP.Service.MTLS.CertificateSubject.UserMap

    • HTTP.Service.MTLS.Enabled

  4. When instructed by Technical Services, verify your connection and authentication.

    Since you retain your private certificate, Technical Services cannot test your connection.

  5. Update the Stibo Systems Service Portal ticket to communicate success or issues.