mTLS integration with SAP Successfactors and SAP BTP
mTLS stands for mutual Transport Layer Security. It is a security protocol that provides encrypted communication between client and server, ensuring that the data transmitted over the network cannot be intercepted, read or modified by any unauthorized entity.
Unlike traditional SSL/TLS, which only authenticates the server to the client, mTLS authenticates both the server and the client to each other, thereby providing mutual authentication. This is achieved by using digital certificates to verify the identities of both the client and server.
In mTLS, the client presents its own digital certificate to the server during the SSL/TLS handshake process, and the server verifies the certificate to authenticate the client. Similarly, the server presents its own certificate to the client, which is then verified by the client.
By using mTLS, organizations can add an additional layer of security to their network communication, helping to prevent attacks such as man-in-the-middle (MITM) attacks and unauthorized access to resources.
When configuring the BTP extension applications’ connectivity to SAP SuccessFactors, use these procedures to enable mTLS.
- X509 Certificate Generation in SAP BTP.
- Creating HTTP Destination using Client Certificate Authentication.
- In SAP SuccessFactors, create an X509 Certificate mapping.
- POSTMAN API call for testing mTLS
“Image/data in this blog is from SAP internal systems, sample data, or demo systems. Any resemblance to real data is purely coincidental.”
Generating X509 Certificate in SAP BTP
You must first generate an X509 certificate for your subaccount before you can create the HTTP destination. so that you can choose it as a key store location when creating the HTTP destination.
- Login to your SAP BTP account, from the cockpit navigate to your extension subaccount in the Cloud Foundry environment.
- Select .
- Select Certificates then Generate Certificate to generate the certificate for your subaccount.
- In the Generate new certificate dialog box:
Enter a name for the certificate in the Certificate File Name field.
Select PEM in the File Name Extension dropdown menu.
- Enter the name of the technical user consuming the SAP SuccessFactors HXM Suite OData API in the Certificate Common Name field.
To determine which permissions you need to assign to the technical user, go to the SAP API Business Hub, find the SAP API Business Hub you want to access, and from the Overview tab, go to the Documentation section and open the help.sap.com link. There, you’ll find the appropriate information for each API. These permissions are determined by the use case and the API that you wish to access.
NOTE: The technical user can be any user with the respective permissions.
- Select whether you want to set a validity for the certificate in days, months, or years in the Certificate Validity Time Unit dropdown menu. (optional)
- Specify the validity of the certificate in the Certificate Validity Value. (optional)
- Choose a Password for the certificate (This will be required later in Postman to use the certificate there)
- Select the Enable automatic renewal checkbox. (optional)
Finally select Generate Certificate and then choose Cancel to close the wizard.
Creating HTTP Destination using Client Certificate Authentication
To use client certificate authentication while calling the SAP SuccessFactors HXM Suite OData APIs, an HTTP destination is required.
- In the SAP BTP cockpit, navigate to your extension subaccount in the Cloud Foundry environment.
- Select .
- Select New Destination and fill in the following properties:
Name: Enter a name for the destination. For example, sap_hcmcloud_core_odata.
URL: Enter the URL of the SAP SuccessFactors OData API you want to consume with cert. before successfactors.com. For a list of the API Endpoint URL for the SAP SuccessFactors environments. Refer List of SAP SuccessFactors API Servers | SAP Help Portal
Proxy Type: Internet
Key Store Location: Select the certificate you have generated for the destinations in your subaccount in SAP BTP. Refer Using Mutual Transport Layer Security (mTLS) | SAP Help Portal
Save the changes.
Select Export to download the certificate that you created and assigned to this destination.
Extract the PEM file from the ZIP file and save it to your local system. (When you open the PEM file, it may be Base64-encoded and require decoding. It can then be decoded and uploaded without the private key.)
NOTE: Because private keys allow access to your system, they must be handled with extreme caution. It is preferable to keep them within your network. To demonstrate, we use notepad++ on a desktop computer to decode the private key. Please use the appropriate tools to meet your organization’s security requirements. (Using online tools is the worst option and should never be used to manage your private keys.)
Open the PEM file in your preferred editor and delete everything between the lines ——-BEGIN PRIVATE KEY——- and ——-END PRIVATE KEY——-, including these lines. Save the document.
After that, insert the cut-out section back into the PEM file, so you have two PEM files: one that is complete and one that does not include the private key (Be sure to remove any extra character spaces that may have been missed during this step.)
Example: mTLS_edited.PEM and mTLS_original.PEM
In SAP SuccessFactors, create an X509 Certificate mapping.
You must have enabled the Access to X509 Certificate Mapping permission in the Security Center before creating the X509 certificate mappings.
To do this, navigate to Admin Center and search for “Manage Permission Roles”. Select the desired Permission Role from the displayed roles. Once at the desired Permission Role Detail, click Permission Settings and then search for Manage Security Center and enable the “Access to X.509 Certificate Mapping” and click Done.
- Navigate to Admin Center and search for Security Center in the SAP SuccessFactors system.
- Choose the X.509 Public Certificate Mapping tile.
- Select Add.
- Fill in the following fields:
- Enter a meaningful name for your X509 certificate mapping in the Configuration Name field.
- Select Business Technology Platform from the Integration Name dropdown menu.
- Upload the certificate you downloaded and edited when creating the HTTP destination in the SAP BTP cockpit in the Certificate File field. (In our case: mTLS_edited.PEM)
- Enter the same technical user that you used to create the HTTP destination in SAP BTP cockpit in the Login Name field for consuming the SAP SuccessFactors HXM Suite OData API. Refer Using Mutual Transport Layer Security (mTLS) | SAP Help Portal
POSTMAN API call for mTLS testing
Using postman to test the Destination and X.509 Mapping configurations outside of BTP is just one option we use here for demonstration purposes. The ultimate goal is to consume MTLs within a BTP application without exposing the private key.
Testing the configuration outside of BTP may aid in root cause analysis by distinguishing between incorrect configuration and incorrect coding using the configuration. It enables the error to be isolated.
Postman is one option for running this test, and it is used here for demonstration purposes. We do not recommend doing this in any production or productive data system because it would expose the private key.”
- Open POSTMAN and click on the hamburger icon at the top left hand corner
- Select File > Settings
- Select Certificates > Add Certificate (Optionally, press Ctrl+Comma to navigate to this dialog box)
- Fill in the required fields:Host: <https://<API URL>.cert.successfactors.com>CRT file: <In our case, mTLS edited.PEM is the original unedited PEM file.>
KEY file: <In our case, mTLS edited.PEM is the original unedited PEM file.>
PFX file: <Nothing should be changed here.>
Passphrase: <Enter the password that was assigned during the certificate creation process.>
Finally, use an API call to see if mTLS has been incorporated.
NOTE: in the Headers section of your API call in POSTMAN please assign KEY = “successfactors-companyid” VALUE = “your SuccessFactors companyID”
The API call:
In my case, I’ll make a simple API call to query the user entity and then check to see if mTLS is included in the results.
We can see in the API call results that we have a section with the “Client Certificate” to deduce that mTLS incorporation has been successfully embedded in the API call. This setup can be achieved following the above detailed steps for implementation.
Kindly share your thoughts and feedback in the comment section.
Do not forget to follow the SAP SuccessFactors HXM Suite environment Topic page https://community.sap.com/topics/successfactors, post and answer questions https://answers.sap.com/tags/67838200100800004730, and read other posts on the topic https://blogs.sap.com/tags/67838200100800004730/
Thanks for sharing, John.
Is this new? Since when is this possible?
I wasn't aware SF supported this authentication scheme. It's not included in the SuccessFactors OData V2 developer guide...
Edit: I found some mTLS related changes in the H2 2022 release notes, however there is no mention of an inbound mTLS feature for SF Platform...
"We provided certificate-based authentication to support a more secure method for our API integrations."
Also good to note that this is limited to pre-provided admin users. We cannot add our own.
mTLS as an authentication technology for SuccessFactors was released for BTP Destinations, IAS/IPS and EC-Payroll in the previous release. See also the BTP Configuration guide here: Using Mutual Transport Layer Security (mTLS) | SAP Help Portal. This is also the reason why the SAP SuccessFactors reference and developer guide have new URLs mentioned SAP SuccessFactors API Server URLs.
The major use case for mTLS is system-2-system communication with a fixed API user. For integrations with named users and principal propagation oAuth2 is still the right authentication type of choice.
It is not released yet for any other consumptions outside of the three options above which is also the reason that the X.509 mapping does not offer a 4th option yet. As soon as it becomes available for consumption outside of the three mentioned above we will update the SuccessFactors guides accordingly.
Hello Gerald Reinhard,
Can we consider this as an alternate for Basic authentication to SAP SuccessFactors from BTP?
Yes, this is the only alternative for Basic Authentication for BTP Destinations using SAP SuccessFactors at the moment. The reason for this is that using oAuth2 in Destinations in CF and Neo is only an option in case of UI access (principal propagation) but not a good option for system to system communication using a fixed API user, here mTLS is the more secure approach.
In some of our other BTP services, such as SAP Integration Suite (Cloud Integration), oauth2 with SuccessFactors Connector is still an option tough and good to use.
We will update our authentication recommendations soon with the information above. You will find all our API authentication best practices here:
This is an implementation design principle document we publish on this page: Implementation Design Principles | SAP SuccessFactors | SAP Community
Good stuff John and many thanks for sharing