This blog describes how to setup secure inbound communication using client certificates when using SAP Cloud Integration in the Cloud Foundry environment. It describes the different configuration options available and gives a step by step description what needs to be configured where. Additional focus of the blog is using custom roles for inbound authorization.

Setup Secure HTTP Inbound Connection with Client Certificates and Custom Roles in Cloud Foundry

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 let’s 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 around.

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 in the Cloud Foundry environment. Inbound communication in Neo environment is described in blog ‘How to Setup Secure HTTP Inbound Connection with Client Certificates’. Outbound communication configuration for Neo and Cloud Foundry is described in blog ‘How to Setup Secure Outbound HTTP Connection using Keystore Monitor’.

Secure Inbound Communication

For HTTPS based communication towards a Cloud Integration tenant no keystore needs to be maintained in the Integration tenant. Sender system and load balancer need to get the certificates and keys configured as described below. This setup can be used with basic authentication with user and password.

For client certificate-based authentication and authorization in the Cloud Integration tenant in Cloud Foundry the private key pair provisioned with the tenant (alias sap_cloudintegrationcertificate) needs to be available in the keystore and the client certificate used for the inbound call needs to be maintained in the service key. In case the deprecated option to configure the client certificate directly in the integration flow is used, the client certificate is required additionally in the service instance. This is different to the configuration in the Neo environment.

Configurations in Sender System

Add Root Certificate from Load Balancer

For secure inbound communication via HTTPS the sender system must trust the load balancer. Therefore the root certificate of the load balancer needs to be part of its trust store.

The easiest way to get the load balancer root certificate is to use the Connectivity Test on the Cloud Integration tenant. The Connectivity Test is available in the Operations View in Web, in section Manage Security. Selecting the Connectivity Tests tile from the 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>.cfapps.<data center>.hana.ondemand.com. You can find this URL by selecting a tile under Manage Integration Content in the Operations view and selecting the integration flow which should be called.

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.

Create Client Certificate

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.

Download the client certificate as PEM-encoded X.509 certificate, this is required later when the service key is created.

Configurations on Cloud Integration Tenant in CF

For secure inbound communication using client certificates, on the Cloud Integration tenant the provisioned private key pair with the alias sap_cloudintegrationcertificate is required in the keystore of the Cloud Integration tenant. Furthermore the client certificate needed for the client certificate-based authorization check needs to be configured. In general, there are two configuration options available:

• Role based authorization
• Maintaining certificates directly in the integration flow (not recommended)

Note: SAP does not recommend to use basic authentication because of security aspects, details can be found in documentation chapter ‘Basic Authentication’.

1. Option: 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 during service key creation.

Get JSON File for Role in the User Role Monitor

First you need to decide if you want to use the SAP pre-delivered role ESBMessaging.send or use a user-defined role for calling the integration flow.

Use Role ESBMessaging.send

The easiest option for role-based authorization is to use the SAP pre-delivered role ESBMessaging.send. Differently to the Neo environment, where the user roles are configured in the cloud platform cockpit, in the Cloud Foundry environment a monitor exists in the Cloud Integration monitoring to maintain user roles. Open the User Role monitor in section Manage Security in the Monitoring section in the Cloud Integration tenant.

Select the pre-delivered role ESBMessaging.send and choose Download JSON.

The format of the downloaded JSON file looks like this:

{"roles":["ESBMessaging.send"]}

You need this JSON snipped later in the creation of the service instance.

Use User-defined Role

If you want to secure the integration flow by a user-defined role you need to create a new role. In the Cloud Foundry environment a monitor exists in the Cloud Integration monitoring to maintain user roles. Open the User Role monitor in section Manage Security in the Monitoring section in the Cloud Integration tenant.

Create a new role by selecting the Add option.

In the creation dialog enter the role name and a description.

Select the newly created role and choose Download JSON.

The format of the downloaded JSON file looks like this:

{"roles":["Role1"]}

You need this JSON snipped later in the creation of the service instance.

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. See above how to create the custom user role in the User Roles monitor in the Cloud Integration monitoring page in section Manage Security.

Authorization

To configure and deploy Integrations flows in WebUI your user needs the role AuthGroup_IntegrationDeveloper.

Check for Key Pair ‘sap_cloudintegrationcertificate’ in Keystore Monitor

As already stated, in the Cloud Foundry environment the SAP key pair provisioned on the tenant is required in the tenants keystore in order to use client certificate-based inbound authentication and authorization. Check in the Keystore monitor in section Manage Security that the key pair with alias sap_cloudintegrationcertificate is available and that the key is not expired.

Note that in Trial accounts no SAP key pair is provisioned. Because of this client certificate-based inbound authentication and authorization cannot be used. You can only use basic authentication.

Configure Client Certificate-Based Authentication and User Role in the Service Instance in SAP Cloud Platform Cockpit

In order to use client certificate-based inbound authentication, this authentication option has to be activated in the service instance in SAP Cloud Platform Cockpit. When creating the service instance to be used for client certificated-based authentication in the SAP Cloud Platform Cockpit, you need to specify client_credentials as grant type. Furthermore, specify the user role you defined in the integration flow in your sender channel.

The easiest way to configure this is to use the downloaded JSON snipped for the user role and extend it with the grant type client_credentials and the redirect-uris like shown here. Note that the grant type needs to be client_credentials even if you want to configure client certificates.

{
    "roles": ["ESBMessaging.send"],
    "grant-types":[ "client_credentials"],
    "redirect-uris":[],
}

More details on creating service instances in Cloud Foundry can be found in the SAP online documentation at Creating Service Instance and Service Key for Inbound Authentication.

Configure Client Certificate in the Service Key in SAP Cloud Platform Cockpit

The client certificates that will be used to send messages to the integration flow, have to be configured in the service key in the SAP Cloud Platform Cockpit.

After the service instance is available, a service key for the instance needs to be created. In the Create Service Key dialog select the Form based key creation. To upload the external client certificate for the sender system select ‘External Certificate’ as Key Type, provide a Name and in the External Certificate field add the client certificate in the following PEM-encoded format:

-----BEGIN CERTIFICATE-----MIIHyDCCBrCgAwIB[...]CAq8Tn7kSFDmVnrXe6v8hcQ==-----END CERTIFICATE-----

Note that the client certificate is a PEM-encoded X.509 certificate.

Note that you can create multiple service keys for one service instance with different client certificates. But a client certificate can be assigned to one service instance only once.

More details on defining service keys in the Cloud Foundry environment can be found in the SAP online documentation at Creating Service Instance and Service Key for Inbound Authentication.

In future a view in the Cloud Integration monitoring section will make this configuration more user-friendly.

2. Option: 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. Furthermore, in the Cloud Foundry environment the client certificate has to be added to the service key additionally.

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. Select Add to 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 certificates 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 User Role Authorization option with user to certificate mapping.

Authorization

To configure Integrations flows your user needs the role AuthGroup_IntegrationDeveloper.

Check for Key Pair ‘sap_cloudintegrationcertificate’ in Keystore Monitor

As already stated, in the Cloud Foundry environment the SAP key pair provisioned in the tenant is required in the keystore in order to use client certificate-based inbound authentication. Check in the Keystore monitor that it is available and that the key is not expired.

Note that in Trial accounts no SAP key pair is provisioned. Because of this client certificate-based inbound authentication cannot be used. You can only use basic authentication with clientid and clientsecret generated in the service key.

.

Configure Client Certificate Based Authentication in the Service Instance in SAP Cloud Platform Cockpit

If you like to use client certificate-based inbound authentication, you have to activate this option in the service instance in SAP Cloud Platform Cockpit. When creating the service instance to be used for client certificated-based authentication in the SAP Cloud Platform Cockpit, you need to specify client_credentials as grant type.

Note that the grant type needs to be client_credentials even if you want to configure client certificates.

{
    "grant-types":[ "client_credentials"],
    "redirect-uris":[],
}

More details on creating service instances in Cloud Foundry can be found in the SAP online documentation at Creating Service Instance and Service Key for Inbound Authentication.

Configure Client Certificate in the Service Key in SAP Cloud Platform Cockpit

Configure the client certificate that will be used to send messages to the integration flow in the service key in the SAP Cloud Platform Cockpit.

After the service instance is available, a service key for the instance needs to be created. In the Create Service Key dialog select the Form based key creation. To upload the external client certificate for the sender system select ‘External Certificate’ as Key Type, provide a Name and in the External Certificate field add the client certificate in the following PEM-encoded format:

-----BEGIN CERTIFICATE-----MIIHyDCCBrCgAwIB[...]CAq8Tn7kSFDmVnrXe6v8hcQ==-----END CERTIFICATE-----

Note that the client certificate is a PEM-encoded X.509 certificate.

Note that you can create multiple service keys for one service instance with different client certificates. But a client certificate can be assigned to one service instance only once.

More details on defining service keys in the Cloud Foundry environment can be found in the SAP online documentation at Creating Service Instance and Service Key for Inbound Authentication.

How to setup OAuth client credential grant for API clients is described in Setup Inbound OAuth Client Credential Grant Authentication for API Clients.