Background
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.
Procedure
- 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.
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.
Procedure
- In the SAP BTP cockpit, navigate to your extension subaccount in the Cloud Foundry environment.
- 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 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
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.
Procedure
- 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."
Procedure
- 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.
Summary:
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/
- SAP Managed Tags:
11 Comments
| User | Count |
|---|---|
| 13 | |
| 3 | |
| 2 | |
| 2 | |
| 1 | |
| 1 | |
| 1 | |
| 1 | |
| 1 | |
| 1 |
