General prerequisites for SAP SuccessFactors HCM Suite
Before you set up the connector in Sapho you need to do a few things.
1: Create a dedicated User ID
You need to create an Admin user in the Provisioning instance. Typically all activities in Provisioning are performed by a SuccessFactors Certified Consultant. Give the user a distinguishable name e.g. Username - saphoapiuser, First Name - Sapho, Last Name - API User.
Note: Our advice is to create a separate dedicated user for connecting SAP SuccessFactors to Sapho. However, you might also use an already existing Admin user.
2: Grant the necessary permissions to the User ID
Log in the SF BizX instance. You will need to follow the Role Based Permission (RBP) approach to set up the permissions for the dedicated User ID. This involves creating a Permission Role and a Permission Group.
3.1: Create a Permission Role
Go to Admin Centre. Access Manage Permission Roles by entering it in the search box at the top of the page.
Click Create New to add a new role.
Enter a meaningful Role Name, for example, Sapho API User (but feel free to use a name that is aligned to your Company’s naming standards).
Under Permission settings, click Permission… button. Scroll down to the link Manage Integration Tools and check the first checkbox - Select All. Click Done on the dialog.
Click Save Changes at the bottom of the Permission Role Detail page.
3.2: Create a Permission Group
Go to Admin Centre. Access Manage Permission Groups by entering it in the search box at the top of the page.
Click Create New to add a new role.
Give the group a meaningful name (e.g. to keep it simple you can call it Sapho API User). Go to the People Pool section and select Username from the dropdown.
On the Search Results screen, enter the username of the dedicated user (e.g. saphoapiuser), select the checkbox next to the name, and click Done.
You’ll return on the previous screen. Click Done again.
3.3: Assign the new Permission Group to the Permission Role
Go back to Permission Roles by entering Manage Permission Roles in the search box at the top of the page.
Click on the previously created permission role (e.g. Sapho API User).
Once in the Permission Role, scroll to Grant this role to… section and click the Add button.
On the Grant this role to… screen, click the Select… button.
Search for the previously created group (e.g. Sapho API User), select the checkbox next to the name, and click Done.
You’ll return on the previous screen. Click Done again. And then click Save Changes at the bottom of the Permission Role Detail page.
You can now navigate back to the Sapho API User Permission Group to confirm the assignment. Once you are in the API User group, you will see Granted Permission Roles has an entry Sapho API User in the list of Permission Roles.
4: Register the OAuth2 Client
Go to Admin Centre. Access Manage OAuth2 Client Applications by entering it in the search box at the top of the page.
Click Register Client Application.
Enter Application Name - Sapho.
Enter Application URL -
Click on Generate X.509 Certificate.
Enter a Common Name (CN) - Sapho. You may leave the rest of the fields empty as they are. Click the Generate button.
Click the Download button to download a copy of the X.509 certificate on your machine. Store it in a secure place for later reference.
Finally, click the Register button.
The new application will be listed on the Manage Oauth2 Client Applications page. Click View.
On the detail page, you will find the API Key. Copy & paste it in a secure place for later reference.
Prerequisites for the Learning module
1: Get your company ID
Log in the SAP SuccessFactors Learning administration environment for your tenant and go to System Admin > Configuration > OAuth Token Server.
Copy the Company ID from the page and paste it in a secure place for later reference.
2: Generate a new client secret
Click on the "Generate a new Client Secret" button and then hit OK on the confirmation box. The client secret will be displayed below the client ID.
Copy the newly generated client secret and paste it in a secure place for later reference. The secret is not stored, so if you navigate away from OAuth Token Server page, the secret will disappear from the page.
How to set up the SAP SuccessFactors connector in Sapho
The instructions below assume that you are on “What is the connection information?” screen for SAP SuccessFactors and that you have set the dropdown labeled Are you using the Learning module? to "Yes".
Step 1: Enter the API endpoint URL of the data center hosting your SuccessFactors instance
Your SuccessFactors support representative can tell you the location of the data center hosting your instance. When you know the location, refer to the table on this page to obtain the API endpoint URL.
For example, if your production instance is hosted in Ashburn, Virginia (USA), the API endpoint URL you need to enter is
Step 2: Enter the Company ID
This is the Company ID assigned by SuccessFactors to your organization.
Step 3: Enter the User ID
This is the ID of the dedicated admin user (e.g. saphoapiuser) you created as a prerequisite.
Step 4: Enter the Client ID
This is the API Key that you copied earlier from the OAuth2 Client Application detail page.
Step 5: Enter the Client Private Key
To get the Client Private Key, open the certificate file downloaded from SuccessFactors using Notepad (or any such app). The X.509 certificate has 2 parts – the private key and the certificate. Copy the characters between —–BEGIN ENCRYPTED PRIVATE KEY—– and —–END ENCRYPTED PRIVATE KEY—– and paste them in Sapho.
Step 2: Enter the Learning URL
This is the URL of the admin environent of your Learning instance.
Step 3: Enter the Learning Company ID
This is the company ID that you copied earlier from the OAuth Token Server page.
Step 4: Enter the Learning User ID
You must enter the ID of an account that:
- has a recognized ID and password for LMS
- is an admin user
- is active
- is not locked.
Step 5: Enter the Learning Client Secret
This is the client secret that you obtained and copied earlier from the OAuth Token Server page.
Step 6: Finish the creation of the connector
Step 7: Wait for Sapho to sync with SAP SuccessFactors
It might take a while to load data from SAP SuccessFactors. While this happens, there is going to be a spinner inline with the connector on the Connectors page.
Possible issue #1: If Sapho Server runs on premises behind a corporate firewall, it might not be able to connect to the SAP SuccessFactors cloud.
Solution: Identify the location of the data center hosting your SuccessFactors instance and refer to the table on this page to obtain the API endpoint URL specific to that data center. Trim the
/odata/v2 part of the URL. In your firewall, allow access to the remaining URL with port 443.
For example, if your production instance is hosted in Ashburn, Virginia (USA), the API endpoint URL specific to that data center is
https://api8.successfactors.com/odata/v2/. So, you need to allow access to hostname
https://api8.successfactors.com with port 443.
Possible issue #2: The OData API is disabled.
Solution: The OData API is set to enabled by default, unless you manually turn it off in Provisioning. Check with your SAP SuccessFactors partner or support representative if the OData API is enabled in Provisioning.
Possible issue #3: There is incomplete configuration of Jam in LMS Admin.
Solution: If you're getting an error saying "Access denied to the requested resource", try disabling the Jam integration with the LMS as explained here.
Possible issue #3: The user account used to connect SAP SuccessFactors to Sapho does not have enough privileges for accessing OData APIs.
Solution: First, check the permissions assigned to the given user by doing the following steps:
1- Go to Admin Center in the SAP SuccessFactors HCM Suite.
2 - In the search box, enter "View User Permission" and select it.
3 - In Advanced Search, enter the username of the given user and click Search.
4 - Click View Permission next to the username.
5 - A list of permissions is displayed along with the roles that grant those permissions. Scroll to the section labeled "Manage Integration Tools."
6 - Check if the user has all the permissions listed below.
If the user account doesn't have all permissions, follow closely steps 2 and 3 from the section called General prerequisites for SAP SuccessFactors HCM Suite.