Configuring SuccessFactors OData API Authentication¶

SuccessFactors supports the OAuth 2.0 SAML Bearer Assertion flow. This flow provides user-constrained authorization, exchanging SAML assertions for access tokens as described in the following specification:

https://tools.ietf.org/html/draft-ietf-oauth-saml2-bearer-23

This document covers the following tasks:

1. Register Vinyl as a SuccessFactors OAuth2 Client Application
2. Register SuccessFactors as a Vinyl security provider.
3. Register the SAP OData Service data source server.

Requirements¶

In order to proceed, you will need the following:

• An existing SuccessFactors account.
• Administrator access to SuccessFactors account.
• Administrator access to Vinyl.

Register Vinyl as a SuccessFactors OAuth2 Client Application¶

Vinyl will need to be registered within SuccessFactors as an OAuth2 Client Application. To register Vinyl as an OAuth2 Client Application, you will need the following information:

To register Vinyl as a SuccessFactors OAuth2 Client Application:

1. Sign into SuccessFactors as an administrator
2. Navigate to the Admin Center
3. Select Company Settings → Manage OAuth 2 Client Applications
4. Click the Register Client Application button
5. Provide the Application Name and Application URL
6. Click the Generate X.509 Certificate button
7. Provide the Common Name(CN)
8. Click the Generate button
9. Click the Download button to save the certificate
10. Click the Register button

Once registered, SuccessFactors will assign an API Key. The API Key, along with the certificate, will be needed to complete the remaining procedures.

Convert Certificate¶

SuccessFactors generates a PEM formatted certificate; Vinyl requires a base64 encoded, PKCS#12-formatted certificate. A full discussion of this topic is outside the scope of this document. However, by way of example, the OpenSSL command line utility can be used to convert a certificate from PEM to PKCS#12:

openssl pkcs12 -in certificate.pem -export -out certificate.pfx

Note that you will be prompted to provide a password. Record the password as it will be needed later.

To base64 encode the certificate:

openssl base64 -in certificate.pfx -out certificate.txt -A

For additional information regarding SuccessFactors OAuth2 Client Application certificates, consult the following document:

http://help.sap.com/saphelpiis_cloud4hr/EN/SuccessFactors_HCM_Suite_OData_API_Handbook_en.pdf

Register SuccessFactors as a Vinyl Security Provider¶

To register SuccessFactors as a Vinyl security provider, you will need the following information:

To register SuccessFactors as a Vinyl security provider:

1. Log into Vinyl as an Administrator
2. Navigate to the IDE
3. Click the Security Providers button
4. From the Data Source Authentication panel, click the + Data Source Authentication button

5. Provide the following:

   • Name: A unique security provider name.
   • Example: SuccessFactors
   • Type: SuccessFactors OData

   • Priority: A unique integer between 10 and 100. Note that this value must be unique.

     Example: 40

6. Click the Save button

7. Set the following properties (In the Properties panel, click the + Property button → Select the Parameter → Provide the Value → Click the Save icon):

   • AuthenticationType: Saml
   • CompanyID: Company ID
   • ApiKey: API Key
   • InstanceApiUrl: Instance API URL
   • SigningCertificate: Signing Certificate
   • SigningCertificatePassword: Signing Certificate Password

8. Click the Edit button in the Providers panel

9. Check the Enabled option
10. Click the Save button

Register the SAP OData Service Data Source Server¶

To register SuccessFactors as a Vinyl data source server, you will need the following information:

To register SuccessFactors as a Vinyl Data Source Server:

1. Log into Vinyl as an administrator
2. Navigate to the IDE
3. Select the Data Servers button
4. In the Data Servers panel, click the + Server button

5. Provide the following:

   • Name: A unique, logical server name.
   • Example: SuccessFactors
   • Type: SuccessFactors

   • URL: {OData Endpoint}

     Example: https://api8.successfactors.com/odata/v2

   • Example: https://api8.successfactors.com/odata/v2

   • Security Provider: {Security Provider Name}

6. Click the Save button

Once the data source server has been registered, click the Test Connection button to ensure that everything is configured correctly. You may be prompted to sign in with Okta at this time.

Troubleshooting¶

A list of SuccessFactors OAuth 2.0 error responses is available from the following page:

http://help.sap.com/saphelpiis_cloud4hr/EN/SuccessFactors_HCM_Suite_OData_API_Handbook_en.pdf

The following "OAuth 2.0 Related Error Messages" appendix contains additional errors:

http://help.sap.com/saphelpiis_cloud4hr/EN/SF_HCMS_OData_API_User_en/2ff9b29c3b774ebdaf367526a5444072.html

See the following for additional troubleshooting information:

Security Provider - SuccessFactors OData

"Either the server is unavailable or the connection information is incorrect." when testing connection

Ensure that the data source server URL ends with a trailing slash. For instance:

https://api8.successfactors.com/odata/v2/

As of March 2016, SuccessFactors requires a trailing slash.

"Accessing OData API using Basic authentication or External OAuth on non-API servers is forbidden." when testing connection

It is possible that the API endpoint has been replaced with a new endpoint. For instance, the following endpoints have been replaced:

• In November 2015, the API endpoint https://salesdemo4.successfactors.com/ was replaced with https://apisalesdemo4.successfactors.com/.
• In March 2016, the API endpoint https://hcm8preview.sapsf.com/ was replaced with https://api8preview.sapsf.com/.