Accessing SuccessFactors OData APIs using OAuth 2.0 Client APIs
This article describes the process on how one can access SuccessFactors OData APIs from an ABAP program using the OAuth 2.0 Client API. The OAuth 2.0 client enables one to access protected services and resources that are offered by any external service providers. The communication between OAuth 2.0 client and server is secured by an HTTPS connection.
With the sunset (planned retirement) of HTTP Basic Authentication for API Calls (SFAPI and OData), one of the recommended alternative approaches is to use OAuth2 SAML Bearer Assertion.OAuth 2.0 client handles the storing of OAuth 2.0 tokens and client secrets in the secure store.During the authentication, OAuth 2.0 client passes the OAuth 2.0 scopes to the service provider which contains references to all the allowed resources. The objective of this article is to share a working sample of OAuth 2.0 with OData API calls required for custom development integrations involving SAP ERP system with SuccessFactors Employee Central.
This scenario involves accessing SuccessFactors OData APIs to create/update Employee and Employment details in the SuccessFactors Employee Central Instance by using the existing Employee and Employment details from SAP ERP HCM System using an ABAP Program that uses OAuth 2.0 Client APIs together with the OAuth 2.0 Authentication mechanisms.
We need to set up certain configurations on both Client (ABAP AS) and Server (SuccessFactors) side.
A. Configurations to be setup on the ERP HCM System:
- Define a Service Provider Type for SuccessFactors
The OAuth 2.0 client provides access from an AS ABAP to different service providers, for example, SAP HANA Cloud Platform, Google Cloud Platform, Microsoft Azure etc. Here we can as well register custom-defined ones in the AS ABAP by creating them in OAuth 2.0 Client Service Provider Types using the transaction OA2C_TYPES. Create a new entry and enter a new custom service provider type (eg. ZSFSF) and save the entry.
OAuth 2.0 Client Service Provider Types (source: transaction OA2C_TYPES)
- Create a BAdI implementation for the new custom Service Provider Type
Since we are not making use of the service provider type pre-defined by SAP, we need to perform some additional steps, including BAdI implementation during the configuration of an OAuth 2.0 client.
We need to create the below BAdI implementation:
- Create a new class in the customer namespace that inherits from CL_OA2C_SPECIFICS_ABSTRACT and redefine the methods as required. This is required to set the values for supported grant types, endpoint settings and certain additional parameters as expected by the service provider. For eg. In case of SuccessFactors Employee Central we need to set the request parameter company_id with a value which refers to the Employee Central Instance.
- Maintain class CL_OA2C_SPECIFICS_ABSTRACT as superclass. This class contains the standard settings for the OAuth 2.0 protocol implementation. Save your changes.
- Redefine the supported grant types method IF_OA2C_SPECIFICS~GET_SUPPORTED_GRANT_TYPES and replace the method implementation with the following code:
e_authorization_code = abap_false. e_saml20_assertion = abap_true. e_refresh = abap_true. e_revocation = abap_false.
- Redefine the configuration extension method IF_OA2C_SPECIFICS~GET_CONFIG_EXTENSION and replace the method implementation with the following code:
r_config_extension = ' '. "Fill with OAuth 2.0 client provider type eg. ZSFSF
- Redefine the Protected Resource Access Properties method IF_OA2C_SPECIFICS~GET_CONFIG_EXTENSION and replace the method implementation with the following code:
e_bearer_token_supported = abap_true. e_bearer_token_name = `Bearer`. e_form_field_supported = abap_false.
- Redefine the SAML 2.0 Get Access Token Request Parameter Names method IF_OA2C_SPECIFICS~GET_SAML_20_AT_REQU_PARAM_NAMES with the following code:
DATA: ls_add_param TYPE if_oa2c_specifics~ty_s_add_param. CALL METHOD super->if_oa2c_specifics~get_saml20_at_requ_param_names IMPORTING e_client_id = e_client_id e_client_secret = e_client_secret e_grant_type = e_grant_type e_grant_type_value = e_grant_type_value e_assertion = e_assertion e_scope = e_scope. ls_add_param-name = 'company_id'. ls_add_param-mode = 1. "Filled during configuration from F4. ls_add_param-default_value = ''."Fill the Employee Central Instance ID here INSERT ls_add_param INTO TABLE et_add_param_names.
- Redefine the SAML 2.0 Assertion: Use Base64 encoding instead of Base64url method IF_OA2C_SPECIFICS~GET_SAML_20_NO_B64URL_ENCODING and replace the method implementation with the following code:
r_no_b64url_encoding = abap_true.
- Redefine the Get supported client authentication method IF_OA2C_SPECIFICS~GET_SUPPORTED_CLIENT_AUTH and replace the method implementation with the following code:
e_basic_authentication = abap_false. e_form_fields = abap_true.
Save the changes and activate the above class.
- Create an OAuth 2.0 Client ProfileCreate a new OAuth 2.0 Client Profile to connect your ABAP program with a certain OAuth 2.0 Client which enables us to access services offered by of a service provider.
OAuth 2.0 Client Profile (source: transaction SE80)
With this step involving the creation of OAuth 2.0 Client Profile is completed, one can use this OAuth 2.0 Client Profile to link programs in the AS ABAP with the SuccessFactors OAuth 2.0 Client.
- Create an OAuth 2.0 Client configuration
The configuration of an OAuth 2.0 client in the AS ABAP ensures that users can access applications provided by a service provider.This step can be done in parallel along with the OAuth Client Application creation activity on the SuccessFactors Employee Central side as we are required to retrieve the API key that gets auto generated.Prerequisite for the system administrator is a profile that comprises of the authorization object S_OA2C_ADM OAuth 2.0 Client Configuration with all the necessary acitivities maintained.
- Open SAP GUI and Start transaction OA2C_CONFIG.Choose Create and select the OAuth2.0 client profile you created earlier. The OAuth 2.0 client profile already contains the service provider.
- Enter the OAuth 2.0 client ID that you configured in the service provider. Both the client secrets must be identical. This value is what we received as a client secret after registering the OAuth 2.0 client using Manage OAuth2 Client Applications at the service provider’s site. Save the changes. Enter the client secret.
- Go to Authorization Server Settings and enter the Token endpoint.
- Under Access Settings, select the checkbox ‘SAML 2.0 Bearer Assertion’.
- Enter the value ‘www.successfactors.com’ for the field SAML 2.0 Audience. Save the entries.
Creation of OAuth 2.0 Client configuration:
OAuth 2.0 Client configuration (source: transaction OA2C_CONFIG)
Generation of OAuth tokens using tcode:
- Configure SSL Settings
This step includes maintaining certificate of Service Provider.The certificate must be retrieved from the relevant target server of SuccessFactors Employee Central. Kindly refer to How to download an SAP SuccessFactors or API SSL Certificate for more details on how one can download the SAP SuccessFactors or API SSL Certificate.Once we download the certificate it needs to be imported under SSL Client SSL Client (Anonymous).
- Retrieve Client Certificate
We need to retrieve the client certificate that shall be registered at SAP SuccessFactors under node SSF OA2CS.Export this certificate (base.64 encoded).It is required to add the content between —–BEGIN CERTIFICATE—– and —–END CERTIFICATE—– into Employee Central X.509 field under manage OAuth client in later steps.
B. Configurations to be setup on the SuccessFactors Employee Central
- Perform User provisioning
Logon to the Employee Central instance.SuccessFactors provides User Import tools supported through the UI and API.One can import their users to EC system by using the OData API user entity and through the Upsert operation. We need to ensure that our User is associated with E-Mail ID and has the necessary permissions. The SF User will need to have permissions to access Manage Integration Tools -> Manage OAuth2 Client Applications.
- Register Application as OAuth Client
Switch to the Admin Center and search for Manage OAuth2 Client Applications under Tools.
- Create a new OAuth2 client application. It is recommended to use the naming convention SAP_<system>_<client>.
- Enter SSF OA2CS certificate from STRUST (without the starting row
and the ending row
- On saving, an API key is generated (GUID), which needs to be inserted as the client ID at OA2C_CONFIG later on. Manage OAuth2 Client Applications (source: SuccessFactors EC Instance)
This article provides a short overview on how one can access OAuth2.0 enabled external services using OAuth2.0 configuration. It outlines how a grant type can be triggered in the AS ABAP and how OAuth 2.0 tokens can be used.I hope this article can help in the implementation of integration scenarios in which APIs from external service providers can be consumed in ABAP programs.
Looking forward to your questions and valuable feedback or thoughts in the comments section.
2613670 – What are the available APIs for SuccessFactors?
2970369 – Sunset of basic authentication mode of SuccessFactors API (SFAPI, OData API)