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 premises systems but requires custom development.

Outbound mTLS

For Stibo Systems SaaS environments, a default truststore and keystore is automatically configured and the SSL Client Certificates functionality can be used to manage certificates and download the client public key provided by Stibo Systems. For more information, refer to the SSL Client Certificates topic.

Configuration properties are required only when using 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 keystore and truststore to use across all features via case-sensitive properties in sharedconfig.properties file on the STEP application server.

The mTLS functionality has been tested with the gateway integration endpoint REST plugin, the REST and REST Direct outbound integration endpoint delivery plugins, and the URL Connections 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 table below lists the Default case-sensitive configuration property for mTLS and their descriptions. The 'SSL.Default.*' properties are the global settings that are applied in OIEP and GIEP configurations where truststore 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) 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 keystore file in the file system. For clusters, the keystore 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 truststore 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'.

To ensure TLS is used without mutual authentication (using a self-signed certificate), no keystore is required and only the truststore configuration properties must be set. If no truststore 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 and the 'Certificate Key Store' parameter are empty since a default keystore 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 integrates with multiple systems that use different CNames (the STEP system name as defined by another system).

As shown in the following table, multiple case-sensitive certificate / keystore properties can be added after the certificates have been created. An alias, indicated by '[certificate]' in the table, is used to identify a specific certificate.

  • For on-prem systems, add properties in the sharedconfig.properties file on the application server.

  • For Stibo Systems SaaS environments, one or more additional certificates can be configured using this method. For example, for certian integrations, instead of using the client public key provided by Stibo Systems, a custom client public key can be used.

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 keystore file in the file system. For clusters, the keystore 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 configuration 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.