This blog describes how to setup secure inbound communication using client certificates, it describes the different configuration options available and gives a step by step description what needs to be configured where.
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 inbound communication lets first have a short look at the basics.
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 Integration Documentation, section ‘Connecting a Customer System to Cloud Integration’.
This blog focuses on inbound communication. Outbound communication configuration is described in blog ‘How to Setup Secure Outbound HTTP Connection using Keystore Monitor’.
For HTTPS based communication towards Cloud Integration Tenant no keystore in the Integration tenant needs to be maintained. Sender system and Load Balancer need to get the certificates and keys configured as described below. In Integration Tenant only certificates for Client Certificate based authorization are to be maintained, either in Certificate-to-User Mapping or directly in the integration flow.
For secure inbound communication via HTTPS the sender system must trust the Load Balancer, for this it must have the root certificate of the load balancer in its trust store.
The easiest way to get the Load Balance root certificate would be to use the Connectivity Test in the cloud integration tenant. The Connectivity Test is available in Operations View in Web, in section Manage Security Material. Selecting the Connectivity Tests tile from Overview page opens the test tool offering tests for different protocols. To connect to a cloud integration tenant via the load balancer to get the root certificate select the TLS option. Enter the URL of your runtime node (the URL you want to call from your sender backend) in the Host field. The host name of the runtime node has the format: <tenant>-iflmap.<data center>.hana.ondemand.com:
Execute the connectivity test. If there is in error you may have to uncheck the option 'Validate Server Certificate'. The response screen provides the list of certificates from the load balancer because the SSL/TLS connection is terminated by the load balancer. You can use the Download option to download the certificates. A certificates.zip file is created in your local download directory containing all the certificates. From the *zip file select the *.cer file of the root certificate and import this into the trust store of the sender system.
Furthermore, if you want to use Client Certificate authentication, the sender system keystore needs to contain a key pair signed by one of the CAs supported by the load balancer.
Note, that only root certificates are being imported into the Keystore of the SAP Load Balancer ! Therefore you as a customer must always assign the whole certificate chain to the certificate to enable the connected component to evaluate the chain of trust.
More information on the supported CAs: Load Balancer Root Certificates Supported by SAP.
For secure inbound communication using Client Certificates, in the cloud integration tenant only the certificates needed for the Client Certificate based authorization check need to be configured. In general, there are two configuration options available:
Note: SAP does not recommend to use Basic authentication because of security aspects, details can be found in documentation chapter 'Basic Authentication'.
The recommended configuration is to use User Role as authorization option in the integration flow sender channel and import the client certificates in the Certificate-to-User Mapping monitor.
You configure the authorization option in the sender channel in the integration flow. For the adapters supporting client certificate based authorization you find the authorization configuration option in the Connection tab. If User Role is selected an additional entry field for the role to be checked is shown.
The default role provided by SAP is ESBMessaging.send, this role can be used if no additional, integration flow specific authorization checks are needed. In case only specific certificates/users shall be allowed to send messages to this integration flow you can enter your own role in this field and create the role in the Cloud Platform Role Management as described further down in the blog.
With the May-13-2018 update user roles created in the Cloud Platform Role Management are offered as help function using the Select button for the User Role field.
Authorization
To configure and deploy Integrations flows in WebUI your user needs the Group Role AuthGroup.IntegrationDeveloper or Single Roles WebToolingWorkspace.Read,
WebTooling.IntegrationFlowConfigure, GenerationAndBuild.generationandbuildcontent and
NodeManager.deploycontent.
The client certificates, that will be used to send messages to the integration flow, have to be configured in the Certificate-to-User Mapping Monitor. The monitor is available in the Operations View in section Manage Security.
In the monitor a user name is assigned to the client certificate. To setup the client certificate based communication upload the client certificate via the Add Button at the top of the monitor and assign a user name. The user name does not need to exist in the SAP Identity Provider as SAP Community Network (SCN) user.
Note that with the 12-May-2019 update expired client certificates are highlighted in red for easy spotting in the monitor.
To get alerted before a client certificate expires follow blog post Automated Notification for Client Certificates Reaching Expiry.
Authorization
To configure Certificate-to-User Mappings your user needs the Group Role AuthGroup.Admin or Single Roles IntegrationOperationServer.read, NodeManager.deploysecuritycontent and
NodeManager.read.
The user created in the Certificate-to-User Mapping has to be assigned to the user role configured in the sender channel to allow sending messages to the integration flow. This is to be done in SAP Cloud Platform Cockpit.
Under Subscriptions select the application for the worker node, the one with the suffix iflmap or hcioem (depending on profile). In section Roles you can create your own roles. The only SAP delivered role on the worker node is ESBMessaging.send. You add additional roles using the New Role option at the top of the monitor. Afterwards assign the new role to the user set in the User-to-Certificate mapping.
You can also create groups for users and assign the groups to the custom role.
Authorization
To configure roles in SAP Cloud Platform Cockpit you need to be administrative member of the subscriber account.
The second option is to configure the certificates for the authorization check directly in the integration flow. But this option is not recommended because changes to the certificate will always cause short downtimes as the integration flow needs to be restarted.
In the sender channel in the integration flow authorization can be configured for the adapters supporting client certificate based authorization. The authorization configuration option is available in the Connection tab of the channel. If Client Certificate is selected a table is shown, where you can add the client certificates. Via Add Button add a new row to the table, in the row you can open the upload dialog for a certificate. Via Upload from File System you can browse the certificate file and add it to the channel.
You can add several certificate to the integration flow sender channel. But be aware that each update in the integration flow needs a redeployment of the integration flow and so is always causing a short downtime. This means, also during certificate renewal of the client certificate you must redeploy the integration flow, causing a short downtime. Exactly because of this disadvantage SAP recommends to use the Role Based Authorization option with user to certificate mapping.
Authorization
To configure Integrations flows your user needs the Group Role AuthGroup.IntegrationDeveloper or Single Roles WebToolingWorkspace.Read, WebTooling.IntegrationFlowConfigure, GenerationAndBuild.generationandbuildcontent and NodeManager.deploycontent.
If the configuration is not correct, you encounter errors either during SSL handshake or during authorization check.
To analyze such problems, you need to check the detailed error messages in the sender system. In addition, you can check if the request reaches the Cloud Integration tenant at all and if there are errors in the trace file of the runtime node.
To find out if the request reaches the Cloud Integration tenant at all, first check in the HTTP Access Log if you can find the request there. You can access this log from the Monitoring Dashboard. In the section Access Logs select the System Log Files tile. You get a list of log files with the most recent files at the top. There are one or more HTTP Access Log files with nearly the same time stamp, one for each runtime node started in your tenant. Because you don't know at which runtime node the request arrives you need to check all of those files.
For each inbound call reaching the Cloud Integration runtime node one line is written into the HTTP Access Log containing the IP address of the calling system, the certificate or user contained in the request, the date, the path and the HTTP return code. The line in the log file has the following format:
<IP Address> – <certificate or user> [<Date>] GET <path> HTTP/1.1 <return code>
Important for the analysis is to check the return code and the certificate or user entry. If a certificate is passed along with the request, the entry should have either the certificate mentioned like this:
<IP Address> – <CN of subjectDN>@<CN of Issuer DN> [<Date>] GET <path> HTTP/1.1 <return code>
Or, if for this certificate a user is created in the Certificate-to-User Mapping, the entry contains not the certificate but the user name maintained in the Certificate-to-User Mapping. The entry should look like this if you try to use Role-based Authorization using client certificate.
<IP Address> – <user> [<Date>] GET <path> HTTP/1.1 <return code>
If the request reaches the Cloud Integration tenant without a certificate, neither the certificate nor the user is shown:
<IP Address> – – [<Date>] GET <path> HTTP/1.1 <return code>
In this case, either the sender does not send the client certificate or the Load Balancer does not accept it, so it is not forwarded. In this case you should check:
If the certificate is received, but there is an error during authorization check, you should consult the LJS Trace (also known as CP Default Trace) for more details about the error.
You can access the LJS Trace from the Monitoring Dashboard. In the section Access Logs select the System Log Files tile. In addition to the HTTP Access Logs there are one or more CP Default Trace files with nearly the same time stamp, one for each runtime node started in your tenant
Check the name of the HTTP Access Log file, where you found the request (see above), to get the ID of the runtime node. The name of the file has the following format: http_access_<Node ID>_<date>.log. The Node ID is the ID of the runtime node, that received the request. Search for the corresponding CP Default Trace with the same node ID, file name format: ljs_trace_<Node ID>_<date>.log.
In this file search for the error and check the details. It could be that the user mapped fron the certificate does not have the role assigned which is configured in the integration flow sender channel.
Setup Secure HTTP Inbound Connection with Client Certificates
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 inbound 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 Integration Documentation, section ‘Connecting a Customer System to Cloud Integration’.
This blog focuses on inbound communication. Outbound communication configuration is described in blog ‘How to Setup Secure Outbound HTTP Connection using Keystore Monitor’.
Secure Inbound Communication
For HTTPS based communication towards Cloud Integration Tenant no keystore in the Integration tenant needs to be maintained. Sender system and Load Balancer need to get the certificates and keys configured as described below. In Integration Tenant only certificates for Client Certificate based authorization are to be maintained, either in Certificate-to-User Mapping or directly in the integration flow.
Configurations in Sender System
For secure inbound communication via HTTPS the sender system must trust the Load Balancer, for this it must have the root certificate of the load balancer in its trust store.
The easiest way to get the Load Balance root certificate would be to use the Connectivity Test in the cloud integration tenant. The Connectivity Test is available in Operations View in Web, in section Manage Security Material. Selecting the Connectivity Tests tile from Overview page opens the test tool offering tests for different protocols. To connect to a cloud integration tenant via the load balancer to get the root certificate select the TLS option. Enter the URL of your runtime node (the URL you want to call from your sender backend) in the Host field. The host name of the runtime node has the format: <tenant>-iflmap.<data center>.hana.ondemand.com:
Execute the connectivity test. If there is in error you may have to uncheck the option 'Validate Server Certificate'. The response screen provides the list of certificates from the load balancer because the SSL/TLS connection is terminated by the load balancer. You can use the Download option to download the certificates. A certificates.zip file is created in your local download directory containing all the certificates. From the *zip file select the *.cer file of the root certificate and import this into the trust store of the sender system.
Furthermore, if you want to use Client Certificate authentication, the sender system keystore needs to contain a key pair signed by one of the CAs supported by the load balancer.
Note, that only root certificates are being imported into the Keystore of the SAP Load Balancer ! Therefore you as a customer must always assign the whole certificate chain to the certificate to enable the connected component to evaluate the chain of trust.
More information on the supported CAs: Load Balancer Root Certificates Supported by SAP.
Configurations in Cloud Integration Tenant
For secure inbound communication using Client Certificates, in the cloud integration tenant only the certificates needed for the Client Certificate based authorization check need to be configured. In general, there are two configuration options available:
- Role based Authorization
- Maintain Certificates directly in the integration flow
Note: SAP does not recommend to use Basic authentication because of security aspects, details can be found in documentation chapter 'Basic Authentication'.
Role Based Authorization
The recommended configuration is to use User Role as authorization option in the integration flow sender channel and import the client certificates in the Certificate-to-User Mapping monitor.
Configure Sender Channel
You configure the authorization option in the sender channel in the integration flow. For the adapters supporting client certificate based authorization you find the authorization configuration option in the Connection tab. If User Role is selected an additional entry field for the role to be checked is shown.
The default role provided by SAP is ESBMessaging.send, this role can be used if no additional, integration flow specific authorization checks are needed. In case only specific certificates/users shall be allowed to send messages to this integration flow you can enter your own role in this field and create the role in the Cloud Platform Role Management as described further down in the blog.
With the May-13-2018 update user roles created in the Cloud Platform Role Management are offered as help function using the Select button for the User Role field.
Authorization
To configure and deploy Integrations flows in WebUI your user needs the Group Role AuthGroup.IntegrationDeveloper or Single Roles WebToolingWorkspace.Read,
WebTooling.IntegrationFlowConfigure, GenerationAndBuild.generationandbuildcontent and
NodeManager.deploycontent.
Configure Client Certificate in Certificate-to-User Mapping Monitor
The client certificates, that will be used to send messages to the integration flow, have to be configured in the Certificate-to-User Mapping Monitor. The monitor is available in the Operations View in section Manage Security.
In the monitor a user name is assigned to the client certificate. To setup the client certificate based communication upload the client certificate via the Add Button at the top of the monitor and assign a user name. The user name does not need to exist in the SAP Identity Provider as SAP Community Network (SCN) user.
Note that with the 12-May-2019 update expired client certificates are highlighted in red for easy spotting in the monitor.
To get alerted before a client certificate expires follow blog post Automated Notification for Client Certificates Reaching Expiry.
Authorization
To configure Certificate-to-User Mappings your user needs the Group Role AuthGroup.Admin or Single Roles IntegrationOperationServer.read, NodeManager.deploysecuritycontent and
NodeManager.read.
Assign Role to User in Authorization Management
The user created in the Certificate-to-User Mapping has to be assigned to the user role configured in the sender channel to allow sending messages to the integration flow. This is to be done in SAP Cloud Platform Cockpit.
Under Subscriptions select the application for the worker node, the one with the suffix iflmap or hcioem (depending on profile). In section Roles you can create your own roles. The only SAP delivered role on the worker node is ESBMessaging.send. You add additional roles using the New Role option at the top of the monitor. Afterwards assign the new role to the user set in the User-to-Certificate mapping.
You can also create groups for users and assign the groups to the custom role.
Authorization
To configure roles in SAP Cloud Platform Cockpit you need to be administrative member of the subscriber account.
Configure Certificates directly in Integration Flow
The second option is to configure the certificates for the authorization check directly in the integration flow. But this option is not recommended because changes to the certificate will always cause short downtimes as the integration flow needs to be restarted.
Configure Sender Channel
In the sender channel in the integration flow authorization can be configured for the adapters supporting client certificate based authorization. The authorization configuration option is available in the Connection tab of the channel. If Client Certificate is selected a table is shown, where you can add the client certificates. Via Add Button add a new row to the table, in the row you can open the upload dialog for a certificate. Via Upload from File System you can browse the certificate file and add it to the channel.
You can add several certificate to the integration flow sender channel. But be aware that each update in the integration flow needs a redeployment of the integration flow and so is always causing a short downtime. This means, also during certificate renewal of the client certificate you must redeploy the integration flow, causing a short downtime. Exactly because of this disadvantage SAP recommends to use the Role Based Authorization option with user to certificate mapping.
Authorization
To configure Integrations flows your user needs the Group Role AuthGroup.IntegrationDeveloper or Single Roles WebToolingWorkspace.Read, WebTooling.IntegrationFlowConfigure, GenerationAndBuild.generationandbuildcontent and NodeManager.deploycontent.
Analyze Problems
If the configuration is not correct, you encounter errors either during SSL handshake or during authorization check.
To analyze such problems, you need to check the detailed error messages in the sender system. In addition, you can check if the request reaches the Cloud Integration tenant at all and if there are errors in the trace file of the runtime node.
HTTP Access Log
To find out if the request reaches the Cloud Integration tenant at all, first check in the HTTP Access Log if you can find the request there. You can access this log from the Monitoring Dashboard. In the section Access Logs select the System Log Files tile. You get a list of log files with the most recent files at the top. There are one or more HTTP Access Log files with nearly the same time stamp, one for each runtime node started in your tenant. Because you don't know at which runtime node the request arrives you need to check all of those files.
For each inbound call reaching the Cloud Integration runtime node one line is written into the HTTP Access Log containing the IP address of the calling system, the certificate or user contained in the request, the date, the path and the HTTP return code. The line in the log file has the following format:
<IP Address> – <certificate or user> [<Date>] GET <path> HTTP/1.1 <return code>
Important for the analysis is to check the return code and the certificate or user entry. If a certificate is passed along with the request, the entry should have either the certificate mentioned like this:
<IP Address> – <CN of subjectDN>@<CN of Issuer DN> [<Date>] GET <path> HTTP/1.1 <return code>
Or, if for this certificate a user is created in the Certificate-to-User Mapping, the entry contains not the certificate but the user name maintained in the Certificate-to-User Mapping. The entry should look like this if you try to use Role-based Authorization using client certificate.
<IP Address> – <user> [<Date>] GET <path> HTTP/1.1 <return code>
If the request reaches the Cloud Integration tenant without a certificate, neither the certificate nor the user is shown:
<IP Address> – – [<Date>] GET <path> HTTP/1.1 <return code>
In this case, either the sender does not send the client certificate or the Load Balancer does not accept it, so it is not forwarded. In this case you should check:
- if the client certificate is sent by the sender system (check logs/traces of the sender system)
- if you really use a signed client certificate, self-signed certificates are not supported by the Load Balancer
- if the root certificate of the CA that signed the client certificate is really supported by the Load Balancer. The supported CAs are listed here Load Balancer Root Certificates Supported by SAP.
- if the whole certificate chain is sent by the sender system.
- if you have configured a custom domain/SSL host check that the trusted CAs are uploaded to your custom domain and that the authentication profile is configured as described here Managing Client Certificate Authentication for Custom Domains.
LJS Trace
If the certificate is received, but there is an error during authorization check, you should consult the LJS Trace (also known as CP Default Trace) for more details about the error.
You can access the LJS Trace from the Monitoring Dashboard. In the section Access Logs select the System Log Files tile. In addition to the HTTP Access Logs there are one or more CP Default Trace files with nearly the same time stamp, one for each runtime node started in your tenant
Check the name of the HTTP Access Log file, where you found the request (see above), to get the ID of the runtime node. The name of the file has the following format: http_access_<Node ID>_<date>.log. The Node ID is the ID of the runtime node, that received the request. Search for the corresponding CP Default Trace with the same node ID, file name format: ljs_trace_<Node ID>_<date>.log.
In this file search for the error and check the details. It could be that the user mapped fron the certificate does not have the role assigned which is configured in the integration flow sender channel.
- SAP Managed Tags:
56 Comments
