Enterprise Resource Planning Blogs by SAP
Get insights and updates about cloud ERP and RISE with SAP, SAP S/4HANA and SAP S/4HANA Cloud, and more enterprise management capabilities with SAP blog posts.
cancel
Showing results for 
Search instead for 
Did you mean: 
quovadis
Product and Topic Expert
Product and Topic Expert





















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')/Artifact...
ODATAv4 196 https://api.sap.com/odata/1.0/catalog.svc/ContentEntities.ContentPackages('SAPS4HANACloud')/Artifact...
SOAP 262 https://api.sap.com/odata/1.0/catalog.svc/ContentEntities.ContentPackages('SAPS4HANACloud')/Artifact...
TOTAL 676 https://api.sap.com/odata/1.0/catalog.svc/ContentEntities.ContentPackages('SAPS4HANACloud')/Artifact...







Good to know:

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.

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:


 

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.

  1. Open Postman client

  2. Goto "Settings"

  3. Navigate to "Certificates" tab

  4. Choose "Add Certificates"

  5. Provide the host domain and keystore with the Export password (or certificate file and key file in lieu of the keystore)

  6. Choose"Add".

  7. 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.

__________

 

Appendix


Example of enrolment with SAP's internal CA











Global PKI Certificate Management Web Enrolment is the SAP Certificate Authority service available internally at SAP for SAP employees only.




Select the matching CA and paste the CSR


 

Submit the CSR to the Certificate Authority and retrieve a signed x509 certificate


 

Select the PKCS7 format and resubmit the CSR



 




 

Additional resources



3 Comments