This blog describes how to setup secure outbound connections with client certificates using the keystore monitor (available with 24-June-2017 release (2.29*)) for maintaining the keys and certificates in the cloud integration system. It gives a step by step description what needs to be configured where. Furthermore, test options are described for testing outbound connectivity.
Setup Secure Outbound HTTP Connection using Keystore Monitor
A typical task in an integration project is to connect remote systems to the SAP Cloud Integration Tenant. Before going into detailed configuration of the outbound communication lets first have a short look at the basics.
Basics of Secure System Configuration
The remote system can act either as a sender or a receiver of messages. The setup and the detailed configuration procedure differ according to the communication direction that is being set up: whether a remote system is supposed to send a message to the integration platform or the other way round.
For more detailed information about the different authentication and authorization options refer to the SAP Cloud Platform Integration Documentation, section ‘Connecting a Customer System to Cloud Integration’.
As Secure inbound communication does not need a keystore we focus only on the outbound communication in this blog. Inbound Communication is described in blog ‘How to setup secure HTTP Inbound Communication’.
Secure Outbound Communication
For HTTPS based outbound communication with client certificate authentication, keys and certificates have to be maintained in the receiver system and in the cloud integration tenant keystore.
Configure Connection in Receiver and Cloud Integration Tenant
Download Root Certificate from Receiver System
For HTTPS based communication the receiver system needs to have a private key and its certificate chain, which typically consists of the server certificate and the intermediate certificate. The intermediate certificate is signed by a CA’s root certificate. The integration tenant trusts the backend server if the CA’s root certificate is available in its keystore.
For the configuration as a first step this root certificate needs to be downloaded from receiver system or provided by the receiver system administrator to add it to the cloud integration tenant in the next step.
Configurations in Cloud Integration Tenant
For HTTPS based communication in the cloud integration tenant, the root certificate of the receiver system provided in previous step is needed in the cloud integration tenant’s keystore. Furthermore, for using client certificate authentication, a signed key pair including complete certificate chain is required in the cloud integration tenant’s keystore.
Maintain Keystore in Keystore Explorer
As the first version of the Keystore Monitor is not able to import single certificates or keys the root certificate of the backend and the signed private key including certificate chain have to be maintained in an external keystore maintenance tool, for example the Keystore Explorer.
As all newly provisioned cloud integration tenants already have a private key pair pre-delivered by SAP, which you can use this for your communications. But, if required, you can also create your own private key pairs for the cloud integration tenant as described in detail in SAP Cloud Platform Integration Documentation in chapter ‘Creating X.509 keys’.
To add the root certificate of the receiver systems private key, open an existing keystore in Keystore Explorer or create a new keystore. Easiest is to just create a new one, select JCEKS as type for the new keystore.
Under Tools select Import Trusted Certificate and add the root certificate of the receiver backend. Give it an alias in the customer namespace; you are not allowed to use aliases with prefix sap_, hcicertificate and hcimsgcertificate. More information about the naming conventions can be found in blog ‘How to use Keystore Monitor to maintain your keys and certificates’.
Add additional certificates, if required, and save the keystore with a password as .jks file. Remember the password as this will be needed during import in Keystore Monitor.
Import Keystore in Keystore Monitor
To import the created keystore file open the Keystore Monitor available in the Operations View in Web in section Manage Security. All certificates and private key pairs contained in the tenant keystore are shown, the ones pre-delivered by SAP cannot be changed.
Upload the keystore via Add button on the top of the monitor. Browse the *.jks file and enter the password you gave in previous step. The root certificates contained in the keystore file will be added to the existing entries for owner Tenant Administrator with the aliases used in Keystore Explorer.
More information about maintaining keys and certificates in Keystore Monitor, about migration of existing keystores into the new monitor and about existing naming conventions can be found in blog ‘How to use Keystore Monitor to maintain your keys and certificates’.
To maintain keys and certificates in Keystore Monitor your user needs the Group Role AuthGroup.Admin or Single Roles IntegrationOperationServer.read, NodeManager.read and
Download Certificate Chain from Keystore Monitor
For client certificate based authentication at the receiver system the root certificate and the client certificate of the cloud integration tenants private key are needed in the receiver system. For this, export the certificate chain of the private key pair in the Keystore Monitor. This option is available as single line option, select Download from the actions Button in the line of the private Key Pair.
Download for a Key Pair will create a file with the name <alias>.p7b in the download directory. The file contains the whole certificate chain assigned to the private key. The certificate chain file can, for example, be opened with the Certificates Snap-in of Microsoft Management Console (Certmgr.msc), which is usually available on Windows systems.
Open the downloaded <alias>.p7b file with the Certificates Snap-in on your system and open the tab Certificate Path. There, the whole certificate chain can be seen.
The entry on the top is the root certificate. Open the root certificate via double click. This will open the root certificate. In the tab Details export the root certificate into a file via Copy to File. In the Certificate Export Wizard export the root certificate as DER encoded binary X.509 file. Use any arbitrary file name to save the certificate as *.cer file.
The same way you exported the root certificate, also export the client certificate, which is the one at the bottom of the certificate chain.
Both certificates need to be imported into the receiver system in the next step.
To download entries from Keystore Monitor your user needs the Group Role AuthGroup.IntegrationDeveloper or Single Roles IntegrationOperationServer.read and NodeManager.read.
Import Certificates to Receiver System
For outbound communication using client certificate authentication, in the receiver system the root certificate and the client certificate of the cloud integration tenant’s private key are to be imported into the backend.
For this, import the root certificate retrieved in previous step into the trust store of the receiver system. In addition, you normally need to import the client certificate into a user to certificate mapping in the receiver backend.
With this last step the configuration of the outbound communication using client certificates is completed. To test the connectivity, continue as described below.
Alternative configuration options
Beside the recommended and most used configuration option to have the whole certificate chain including the root CA certificate assigned to the server’s private key available in the server keystore and only the root certificate in the client’s trust store, there are other configuration options possible with which the client can establish a trust relation to the server:
- If the server keystore contains only the server certificate including intermediate certificate, the client keystore also needs to contain only the root certificate in its keystore.
- If the server keystore contains only the server certificate without the certificate chain the client keystore needs to contain the intermediate and root certificate.
- If the server uses a self-signed certificate the client keystore needs to contain this certificate.
Similar options are possible when the server has to trust the client certificate in the client certificate authentication use case.
After setting up the connection toward the backend system, the connectivity test feature can be used to test the communication or even to download server certificates.
TLS Connectivity Test
The Connectivity Test is available in Operations View in Web, in section Manage Security Material. Selecting the Connectivity Test tile from Overview Page will open the test tool offering tests for different protocols. To test the HTTPS based outbound communication the TLS option is to be selected.
Enter the address of your cloud backend (Tests to On-Premise backends via cloud Connector cannot be done) as used in the outbound channel and execute the test. The test will give a success message or an error with detailed error information.
If there is an error with the SSL connectivity it is possible to execute the test without the option to Validate Server Certificate. In this case the server certificate is not checked, but can be downloaded via Download Button and added to the keystore in Keystore Monitor as described in the above chapter.
Client Certificate based authentication can be checked via option Authenticate with Client Certificate. It is possible to enter a specific alias contained in the keystore or to leave the field empty, in this case the first alias fitting to the server request will be used.