Technical Articles
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:
- https://api.sap.com/odata/1.0/catalog.svc/ContentEntities.ContentPackages(‘SAPS4HANACloud’)/Artifacts?$format=json&$select=Name,Type
- https://api.sap.com/odata/1.0/catalog.svc/ContentEntities.ContentPackages(‘SAPS4HANACloud’)/Artifacts?$format=json&$select=Name,SubType
The APIs breakdown by subtype is as follows:
Good to know:
Before we start.Pre-requisites:
Disclaimer:
|
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.peme. convert PKCS7 certificate chain into x509 pem certificate chain
$ openssl pkcs7 -inform PEM -in Quovadis-x509-PKCS7.pem -print_certs -out Quovadis-x509-chain.pemf. 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 | base64Please 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:
|
 |
| 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.
Good to know:
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 applicationWhen 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 CloudWhat 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
|
A comprehensive BTP security tutorial: https://developers.sap.com/tutorials/s4sdk-secure-cloudfoundry.html
__________
|
Detailed Blog with everything captured in this context !!
Appreciate your efforts in putting this down and enabling others to excel !
Hi,
This scenario seems to be relevant to connection between BTP and S/4HANA Cloud. Will this work if we try to consume an API from S4HANA Cloud system using ABAP program developed on stack? Meaning both the API and the ABAP program are from the same S4HANA Cloud system.
Thanks.
Hi Kah Choon Simon Yong , it's a fair question;
What I demonstrated in this blog is how to set up the mTLS communication with SAP S/4HANA Cloud tenant with the ODATA APIs regardless of the client environment.
And thus the reason why I used SAP API Management to implement one of the APIs as an API proxy; And a HTTPS API proxy can be called from any environment; Here what you can read in the blog's conclusion:
I hope that helps;