Skip to Content
Technical Articles
Author's profile photo John Isaboke

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.

  1. X509 Certificate Generation in SAP BTP.
  2. Creating HTTP Destination using Client Certificate Authentication.
  3. In SAP SuccessFactors, create an X509 Certificate mapping.
  4. 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.


  1. Login to your SAP BTP account, from the cockpit navigate to your extension subaccount in the Cloud Foundry environment.
  2. Select Connectivity > Destinations.
  3. Select Certificates then Generate Certificate to generate the certificate for your subaccount.

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


NOTE: If you choose to assign a password when generating a new certificate, you must enter the same password in “Key Store Password” when creating “HTTP Destination using Client Certificate Authentication” as well as in “POSTMAN API call for mTLS testing – step number 4 in “Passphrase”.

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.


  1. In the SAP BTP cockpit, navigate to your extension subaccount in the Cloud Foundry environment.
  2. Select Connectivity > Destinations.
  3. Select New Destination and fill in the following properties:

Name: Enter a name for the destination. For example, sap_hcmcloud_core_odata.

Type: HTTP

URL: Enter the URL of the SAP SuccessFactors OData API you want to consume with cert. before 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

Authentication: ClientCertificateAuthentication

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

Make sure to include Additional Properties <url.headers.successfactors-companyid> and set the value of your <companyID>.

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 that 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. (We are only deleting the private key, notice that we will be left with a certificate chain containing three certificates which are the server/client certificate, intermediate CA and root CA) 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.


  1. Navigate to Admin Center and search for Security Center in the SAP SuccessFactors system.
  2. Choose the X.509 Public Certificate Mapping tile.
  3. Select Add.
  4. 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.”


  1. Open POSTMAN and click on the hamburger icon at the top left hand corner
  2. Select File > Settings
  3. Select Certificates > Add Certificate (Optionally, press Ctrl+Comma to navigate to this dialog box)
  4. Fill in the required fields:Host: <https://<API URL>>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, post and answer questions, and read other posts on the topic

Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Pieter Janssens
      Pieter Janssens

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

      Certificate-Based Authentication for Learning APIs (Inbound mTLS) Inbound mTLS for SF LMS, not HXM Core.
      "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 (X509 Certificate) Based Authentication Support in Integration Services Registration Center Integration Service Registration Center - So, not inbound OData
      Availability of mTLS OAuth 2.0 Authentication Flow For Integrations "In Integration Center, REST-based integrations that are inbound or outbound can use such OAuth Mutual Authentication defined in Security Center" - "inbound REST" wait.. what..??


      - Pieter

      Author's profile photo Gerald Reinhard
      Gerald Reinhard

      Hi Pieter,

      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.


      Best regards




      Author's profile photo Ranjith kumar
      Ranjith kumar

      Hello Gerald Reinhard,


      Can we consider this as an alternate for Basic authentication to SAP SuccessFactors from BTP?

      Author's profile photo Gerald Reinhard
      Gerald Reinhard

      Hi Ranjith,

      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:

      SAP SuccessFactors Integration: Migrating SAP SuccessFactors API calls from Basic Authentication to oAuth2.0

      With Basic Authentication being deprecated for OData and SOAP API calls for SuccessFactors, all custom integrations have to switch from Basic Authentication to a oAuth 2.0 flow using SAML Assertions. Learn in this IDP what integrations are affected and see what the required steps are to migrate API calls for custom integrations in SAP Integration Suite. In addition get firsthand information what options there are for migrating custom integrations on 3rd party integrations platforms or for custom integration code.
      Document | Blog Post | Webinar Part 1 | Webinar Part 2

      This is an implementation design principle document we publish on this page: Implementation Design Principles | SAP SuccessFactors | SAP Community

      Best regards


      Author's profile photo Chris Paine
      Chris Paine

      Gerald Reinhard

      whilst "It is not released yet for any other consumptions outside of the three options above" - it clearly works outside of BTP (the use in postman shows this). Is there any restriction in using BTP as a cert generator and then using the generated cert outside of BTP? (other than it being a PITA or regenerate certs annually?)



      Author's profile photo Gerald Reinhard
      Gerald Reinhard

      You summarized it nicely. Till today, I thought of PITA being bread only :-). Using mTLS outside of BTP is technically possible, but depending on how you use BTP to get the certificate, this will cause more or less trouble. One option is to generate the certificate in BTP and use this one and face the pain of replacing it yearly without notice. Another option is to use the destination service API to retrieve the same information dynamically, which creates a BTP dependency. I would call this technical possible at the moment, but it is far from a good solution if your application does not run on BTP. We are discussing this internally and can hopefully provide some news soon. I will keep everybody posted here.

      Author's profile photo Frank Meertens
      Frank Meertens

      Hi Gerald,

      Thanks for clarifying.

      Question related to the dynamic calling of the destination service. The downside you mention is dependency having a destination service running on a BTP sub account. If your application runs on BTP or if you are accessing the destination from SAP API Management (running on BTP), the dynamic destination would be a suitable option to use the mTLS?





      Author's profile photo Gerald Reinhard
      Gerald Reinhard

      Hi Frank,

      when your application is running on BTP or your are using BTP services accessing mTLS based Destinations you should be all good to use it and benefit from the features of the destination service. The feature is officially documented and released:

      It becomes a hassle only, when you are outside of BTP, here I would consume it only with caution.

      Best regards


      Author's profile photo Rowland Simiyu
      Rowland Simiyu

      Good stuff John and many thanks for sharing

      Author's profile photo Chris Paine
      Chris Paine

      Thanks for this!

      I finally got fed up with requesting OAuth tokens every time I used Postman, so gave this a go. Pretty happy with it. It does make me wonder why exporting the destination in BTP allows you to export the full cert when there has clearly been made a choice not to allow exporting the cert from the cert generation area. But nevertheless, that works for me right now.

      I think allowing for use of self signed certificate would be good - I tried and it didn't work. But until that is possible, using BTP as a cert generator works for me 🙂