Technical Articles

Piotr Tesny

December 1, 2021 8 minute read

S/4HANA Cloud APIs with ClientCertificateAuthentication.

S/4HANA Cloud APIs with ClientCertificateAuthentication

What is mTLS with S/4HANA Cloud APIs?

mTLS stands for mutual Transport Layer Security and is a better term to describe the SSL Client Certificate authentication method with S/4HANA Cloud APIs.

Out of many hundreds and counting, SAPS4HANACloud APIs still only a subset of these APIs support the principal business user propagation with either OAuth2SAMLBearerAssertion and/or SAMLAssertion flow.

Sometimes, within one same API family or communication scenario, there are APIs that support OAuth2SAMLBearerAssertion with business users and some other only support OAuth2SAMLBearerAssertion with a communication user.

Still, the immense majority of APIs support x509 client certificate authentication (with regard to a SAPS4HANACloud communication user).

Let’s have a look at the line-up of the APIs on SAP_API_BUSINESS_HUB using its ODATA catalog service:

The APIs breakdown by subtype is as follows:

SubType	Count	TOP 10
ODATA	218	https://api.sap.com/odata/1.0/catalog.svc/ContentEntities.ContentPackages(‘SAPS4HANACloud’)/Artifacts?$format=json&$filter=SubType%20eq%20%27ODATA%27&$select=Name&$top=10
ODATAv4	196	https://api.sap.com/odata/1.0/catalog.svc/ContentEntities.ContentPackages(‘SAPS4HANACloud’)/Artifacts?$format=json&$filter=SubType%20eq%20%27ODATAV4%27&$select=Name&$top=10
SOAP	262	https://api.sap.com/odata/1.0/catalog.svc/ContentEntities.ContentPackages(‘SAPS4HANACloud’)/Artifacts?$format=json&$filter=SubType%20eq%20%27SOAP%27&$select=Name&$top=10
TOTAL	676	https://api.sap.com/odata/1.0/catalog.svc/ContentEntities.ContentPackages(‘SAPS4HANACloud’)/Artifacts/$count

Good to know:

With merely knowing the name of an API it is easy to look up its definition on API Business Hub as follows: https://api.sap.com/api/{<Name>}/overview, for instance, https://api.sap.com/api/API_CUSTOMER_RETURN_SRV/overview
or https://api.sap.com/odata/1.0/catalog.svc/APIContent.APIs(‘API_CUSTOMER_RETURN_SRV’)/$value?type=json

Before we start.

Pre-requisites:

Admin access to a S/4HANA Cloud tenant and access to a Certificate Authority.

Disclaimer:

Please note all the code snippets below are provided “as is”.
All the x509 certificates, bearer access and/or refresh tokens and the likes have been redacted.
Images/data in this blog post is from SAP internal sandbox, sample data, or demo systems. Any resemblance to real data is purely coincidental.
Access to some online resources referenced in this blog may be subject to a contractual relationship with SAP and a S-user login may be required.

Putting it all together.

That’s a relatively simple task and the official SAP Help documentation is excellent.

Please refer to pages 13 onwards in the Set Up Authentication for SAP S/4HANA Cloud Extensions | SAP Help | PDF document.

Step1. Prepare your CA-signed x509 certificate keypair.

a. Create a certificate signing request (CSR) and the private key

Please make sure you provide a meaningful DN (Distinguished Name) definition as subject of the below command where CN (Common Name) must typically obey your network domain rules.

-subj "/C=DE/ST=Gauteng/L=Heidelberg/O=SAP/OU=SAP/CN=QUOVADIS-X509.sap.biz"

$ openssl req -new -newkey rsa:4096 -nodes -out CSR.csr -keyout PrivateKey.key -subj "/C=DE/ST=Gauteng/L=Heidelberg/O=SAP/OU=SAP/CN=QUOVADIS-X509.sap.biz"
Generating a 4096 bit RSA private key
.........++
...................................++
writing new private key to 'PrivateKey.key'
-----

b. submit the CSR to your certificate authority (cf appendix for further details)

$ pbcopy < CSR.csr

..............sign the CSR with your CA....................

You need to get the Quovadis-x509-PKCS7.pem that contains the full certificate chain!

c. optionally, if applicable, remove the passphrase from the private key

$ mv PrivateKey.key PrivateKey.key.original
$ openssl rsa -in PrivateKey.key.original -out PrivateKey.key
writing RSA key

d. convert the private key from PKCS1 (RSA) into PKCS8 pem format:

openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in PrivateKey.key -out pkcs8.pem

e. convert PKCS7 certificate chain into x509 pem certificate chain

$ openssl pkcs7 -inform PEM -in Quovadis-x509-PKCS7.pem -print_certs -out Quovadis-x509-chain.pem

f. create the .p12 format keystore

Please make sure you can remember your keystore Export (Transport) password!

$ openssl pkcs12 -export -in Quovadis-x509-chain.pem -inkey pkcs8.pem  -out S4HC.p12 -name  QUOVADIS-X509.sap.biz
Enter Export Password:
Verifying - Enter Export Password:

Last but not least, optionally, base64-encode the keystore. (Then it could be uploaded it into your destination service instance if you were considering to use ClientCertificateAuthentication with a destination service destination and the BTP application router.)

cat S4HC.p12 | base64

Please note:

S/4HANA Cloud cannot accept self-signed x509 certificates.Thus your x509 must be signed with a CA (Certificate Authority) known to your S/4HANA Cloud backend system.
You can use the following Fiori App to verify if your CA is known to your S/4HANA Cloud system. In case it weren’t you would need to upload your CA to your S/4HANA Cloud:
- https://my3xxxxx.s4hana.ondemand.com/ui?sap-client=100#PersonalSecurityEnvironment-maintainTrustList

Step2. Upload the CA-signed x509 certificate to the communication user.

On S/4HANA Cloud side have an existing or create a new communication user and upload a CA-signed x509 client certificate into it, as follows:

Please notice this is the x509 certificate with the full chain of certificates!

Please make sure the Authentication method is SSL Client Certificate

Please note:

one CA-signed x509 certificate can only be assigned to one single technical communication user.
your client application will then rely on this CA-signed x509 certificate trust (bound to this technical communication user as opposed to using a dynamically propagated business user identity) for password-less communication with S/4HANA Cloud.

Step3. The communication arrangement.

Let’s take an existing communication arrangement and the following API, namely API_MANAGE_WORKFORCE_TIMESHEET

The API supports the x509 client certificate authentication. Thus let’s make the communication arrangement use the SSL Client Certificate as the Authentication method, as depicted below:

Step4. Test S/4HANA Cloud API with x509 Client Certificate

a. Using Quovadis_x509 with API Management

Upload S4HC.p12 keystore into APIM certificate keystore
Create API Provider based on the APIM certificate keystore from the previous step.
Configure the API Provider connection as follows: Type is Internet Host is your S/4HANA Cloud host name Port number is 443 Use SSL must be ticked Select the Key Store Certificate created in the first steps.
Let’s use it this API Provider in the API Proxy

b. Using Quovadis_x509 with Postman.

Postman settings.

Pre-requisites: you have created your .p12 or .pfx keystore.

Open Postman client
Goto “Settings”
Navigate to “Certificates” tab
Choose “Add Certificates”
Provide the host domain and keystore with the Export password (or certificate file and key file in lieu of the keystore)
Choose”Add”.
Repeat 4-6 as many times as many different host name/keystores combinations as depicted below.

Good to know:

Overall that does resemble very much the SAP API Management provider configuration.

Subsequently, whenever you send a request to a configured host domain its client certificate is sent automatically by Postman.

How to check if the certificate was sent with the request?

Postman console,

Open the console in Postman tool and send a request to the S/4HANA Cloud service endpoint.

Send a request:

Conclusion.

A case for a 3rd party application

When a 3rd party client wants to talk to S/4HANA Cloud over mTLS with ODATA APIs all that is needed is to have a client application’s https client agent use the key-store with the full chain x509 certificate and the private key….

For instance, this can be quite easily done in nodejs with axios and http agent. Or with the API Provider in API Management or using Postman.

On the other hand, if one uses the destination service with the ClientCertificateAuthentication type of a destination, when the destination is called all it does is to return the certificate key-store as a base64-encoded string. This way one can easily base64-decode the key-store and extract the public and private keys to be passed to your application’s http client agent.

A case for SAP API Management as a framework to implement your extensions with S/4HANA Cloud

What is the real advantage of using APIM to implement your extensions with S/4HANA Cloud ?

First of all there is no code to be written at all.

Furthermore, one can group S/4HANA Cloud APIs (combining different authentication methods) into API Products and publish the API Products into the Developer portal.

Then developers can create an application subscribing to the API Products and then get access to only those APIs which are grouped/associated within that API Products.

__________