Skip to Content
Actions

How to initiate an OAuth connection to SuccessFactors Employee Central?

March 5, 2017 | 4,097 Views |
 integrationoauth2saml assertion
Follow

Intro – What is OAuth?

OAuth 2.0 (or simply put OAuth) is an Authorization framework – when a user requests access to a resource from a Service Provider (without providing their credentials) and is authorized by an Identity Provider (IdP) to access the resource i.e. the user credentials are validated against the IdP – whereby one app acts on behalf of a user to interact with another app.

For example, I would like to subscribe to a news channel – SBS On Demand – using my Google ID – myuser@gmail.com – instead of registering a new profile on SBS.  In this instance OAuth lets an IdP – Google – to access a resource from the Service Provider – SBS On Demand. Since I am using my Google ID to access SBS it doesn’t have any knowledge of my password, it just sees me as myuser@gmail.com.

Why (and when) to OAuth?

OAuth underlines the concepts of Principal Propagation – where a user who performs a task in the source system is required to perform the same task in the target system (like a user who creates a Purchase Order in app A, that then gets approved and flows into app B, where it gets amended further by the same user who created it in app A in the first instance).

The below diagram helps illustrate how to arrive at a suitable use case for OAuth

How do we implement a basic OAuth scenario?

The below steps serve as a “how to guide” on how to implement OAuth in SuccessFactors EC, and test it using Postman (you can choose to use any other suitable REST client).

It is based on the official SAP document “SAP SuccessFactors HCM Suite OData API: Developer
Guide – About HCM Suite OData APIs”. This document is meant to complement the official guide.

Step 1 Create an interface User ID

We will start off with creating a user in the Provisioning instance. Typically all activities in Provisioning are performed by a SuccessFactors Certified Consultant.

Login to the Provisioning instance, then go to Company Name, click Company Settings, and fill in the below fields (all are required) and click on Create Admin to create an Admin user for our interfaces. We will call ours apiuser (First Name – API, Last Name – User).

Once we have completed this step we can log out of Provisioning and then log into BizX to execute the remainder of the steps.

Step 2 Grant the necessary permissions to the User ID

We will now grant the apiuser with permissions. We will follow the Role Based Permission (RBP) approach to set up the permissions for our apiuser. This involves creating a Permission Role and a Permission Group.

Go to Admin Centre, click on Set User Permissions, then click on Manage Permission Roles. Alternatively you can access Manage Permission Roles by entering it in the Search for actions or people box.

Create a new Role (click Create New), enter a meaningful Role Name – we will call ours API User (but feel free to use a name that is aligned to your Company’s naming standards). Enter a Description for the Role (we have called ours API User). Under Permission settings click Permission… scroll down to the link Manage Integration Tools, and select the following check boxes – Admin access to OData API and Manage OAuth2 Client Applications and click Finished.

As we have used our Role for a wider range of scenarios (that involve the Employee Central API, Integration Center etc.) you will see that we have activated many more permissions as reflected in the picture below.

Click Save Changes.

Now create a Permission Group.

Go to Admin Centre, click on Set User Permissions, then click on Manage Permission Groups. Alternatively you can access Manage Permission Groups by entering it in the Search for actions or people box.

As we did with the Permission Role call your group API User (to keep it simple), go to the People Pool section and select User Name from the drop down, type in apiuser on the next Search Results screen, select the checkbox next to the name, and click Finished. Click Finished once you return to the previous screen.

Now we shall assign our newly created Permission Group API User to Permission Role API User.

Once in the Permission Role, scroll to Grant this role to… section click Add, enter API User as the Permission Group and click Finished.

You can now navigate back to the Permission Group to confirm the assignment. Once you are in the API User group you will see Granted Permission Roles has an entry API User in the list of Permission Roles.

That takes care of our prerequisite set up of User ID and permissions.

Step 3 Register the OAuth2 Client 

Go to Admin Centre, click on Company Settings, you will see a link – Manage OAuth2 Client Applications, click on this link. Click on Register Client Application. This is the easiest step and requires little technical knowledge.

Enter an Application Name – give it an arbitrary but meaningful name – we will call it OAuthtest, provide a Description – Client to test OAuth, enter an Application URL – http://OAuthtest

Click on Generate X.509 Certificate button, enter a Common Name(CN) – Oauth, you may leave the rest of the fields empty as they are.

Note: the X.509 certificate is issued by SuccessFactors.

Click Generate, then Download a copy of the X.509 certificate on your machine.

Open the certificate file using notepad (or any such app). The X.509 certificate has 2 parts – the private key and the certificate. We shall copy and paste the characters between —–BEGIN ENCRYPTED PRIVATE KEY—– and —–END ENCRYPTED PRIVATE KEY—– in the next step

Click Register.

Go into the OAuth application now and take note of the API secret key.

Step 4 Generate a SAML assertion

Open a new window in Postman and enter the following details

Operation POST

URL https://api10preview.sapsf.com/oauth/idp – this is the endpoint URL of the data center where this instance of SuccessFactors is hosted. For a complete list of URLs of other data centers please refer to – http://help.sap.com/saphelpiis_cloud4hr/EN/SF_HCMS_OData_API_User_en/frameset.htm?03e1fc3791684367a6a76a614a2916de.html

Authorization No Auth

Headers

Content-Type application/x-www-form-urlencoded

Body raw

Request payload, formulate the payload as such –

client_id – this is the API Key that was generated earlier

user_id – User ID to call the API

token_url – https://api10preview.sapsf.com/outh/token

private_key – this is the private key from the X.509 certificate

Your request payload should now look like –

client_id=Njk2ZjAzNjY5MDVlZGVlMWU3NzFmMWQ3NzgwYg&user_id=apiuser&token_url=https://api10preview.sapsf.com/outh/token&private_key=<enter the private key from the X.509 certificate here>

Click Send.

You should get back a Base64-encoded response that looks like the below. Note the Status of 200 OK.

The response you will get will be a Base64 encoded SAML assertion. You can use a free online tool – https://www.base64decode.org to decode the response.

Here you see the User ID apiuser being returned in the response (decoded) –
<saml2:NameID Format=”urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified”>apiuser</saml2:NameID>

If you want to use an email address instead of an User ID then mark use_email = true and replace the User ID with the Email ID.

This requires the Email ID to be uniquely mapped to a single user in EC.

client_id=Njk2ZjAzNjY5MDVlZGVlMWU3NzFmMWQ3NzgwYg&user_id=<emailid@company.com>&token_url=https://api10preview.sapsf.com/outh/token&private_key=<enter the private key from the X.509 certificate here>

Click Send.

If the Email ID isn’t uniquely mapped to a user in EC then it will error with – Unable to map \”emailid@company.com\” to a valid BizX User ID.

Once you decode the Base64-encoded response you will see an Email ID in the response (as opposed to the User ID earlier)
<saml2:NameID Format=”urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified”>emailid@company.com</saml2:NameID>

Step 5 Request a User Token using the SAML Assertion

Open a new window in Postman and enter the following details

Operation POST

URL https://api10preview.sapsf.com/oauth/token

Authorization No Auth

Headers

Content-Type application/x-www-form-urlencoded

Body raw

Request payload,

formulate the payload as such –

company_id – SuccessFactors Company ID

client_id – this is the API Key that was generated earlier

grant_type – urn:ietf:params:oauth:grant-type:saml2-bearer

user_id – User ID to call the API

assertion – Base64-coded SAML assertion from the response in the earlier step

Your request payload should now look like –

company_id=MyCompanyDevAu&client_id=AzNjY5MDVlZGVlMWU3NzFmMWQ3NzgwYg&grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer&assertion=<enter the response from the previous step here>

Please note – DO NOT include api_key here in the Request.

Response

This tells us that the token expires in 85114 seconds or close to 24 hours.

Make a note of this Bearer token, we will validate it in the next step.

Step 6 Validate Bearer Token

Open a new session in Postman. We will use the GET operation to validate the Bearer token.

URL https://api10preview.sapsf.com/oauth/validate

Authorization No Auth

Headers
Authorisation Bearer followed by the token string from the earlier step

This ascertains the validity of the token.

Step 7 Use the Bearer Token to Query an OData Entity

Open a new session in Postman.

Authorization No Auth

Headers

Authorisation Bearer followed by the token string from the earlier step

Use the GET operation with the Query –

https://api10preview.sapsf.com:443/odata/v2/Country(code=’AUS’,effectiveStartDate=datetime’1900-01-01T00:00:00′)?

Response

The OData Query will return you with a list of Countries that are configured in your SuccessFactors instance like in the above screenshot.

Conclusion…

So now that we have seen what OAuth is, what its capabilities are, and how it can be easily implemented we must isolate use cases where OAuth is not suited and hence should not be used.

If your integration doesn’t occur in real-time, doesn’t require Principal Propagation and Single Sign-On then it is best to persist with Basic Authentication (using a suitable System ID).

Last but not the least – a word of thanks to my dear friends – Yash Agarwal for his encouragement to write this blog, Neelesh Kamath for his support and Sascha Wenninger for his guidance.

To report this post you need to login first.

15 Comments

You must be Logged on to comment or reply to a post.

  1. Kok Chuan Wong

    Hi Arijit,

    Thanks for sharing your experience on how to make the OAuth 2.0 calls to SAP EC in such a concise step by step approach.

    Cheers,

    KC

    (1) 
  4. Luke Marson

    Very good blog. My only comment is that this is not specific to SAP SuccessFactors Employee Central, but to the SAP SuccessFactors Platform.

    (1) 
    1. Arijit Das Post author

      Hi Luke

      Thank you for your compliments, it means a lot to me and all the more so coming from a SuccessFactors Guru, SAP Mentor and SAP Community Moderator like you!

      I concur with you that the same overall principles would apply to implement OAuth across the entire SAP SuccessFactors suite or for that matter on any other platform (and not just in SAP SuccessFactors Employee Central). However, the steps (like actions, screenshots, RBP etc.) used for this demo happened to be all out of EC  🙂

      Regards

      Arijit

      (0) 
  5. Chris Paine

    Hi,

    Firstly, a great effort in explaining an incredibly complex topic so well.

    Now, let’s look at what we are attempting to achieve! The main reason for using OAuth auth is to be able to restrict the scope of access that one grants an application.

    However, what SuccessFactors does is use OAuth2 SAML2 Bearer authentication to allow any system to log in with any user’s auths. Thus you can set up a trust relationship between two systems and make API calls to SAPSF using the user that is logged into your application.

    Note that this is different to OAuth although it shares a common name.

    However, what is perhaps what I’d most like to say, is that the SAP Cloud Platform can do all of this for you, automatically 😀!

    The whole provisioning of OAuth tokens, connection and making connections using OAuth2 SAML Bearer Token is taken care of behind the scenes, leaving us developers to get on with the important task of building cool apps that integrate with SAP SF. 😎

    Cheers!

    Chris

    (2) 
  6. manoj caisucar

    Hi Arijit,

    This blog is very good and helpful. We did the same steps from postman, and finally the access token was generated. But when this token is generated it has some time to live. What if i want to reduce that time to live for that token.

    Also is there any java code what you can point me to generate the access token based on the api key and token url of the server?

     

    Thanks

    Riju Bhasker

    (1) 
    1. Arijit Das

      Hi Riju

      I believe the validity of the token is controlled by the SuccessFactors application; not sure if it can be controlled or not. Best to raise an incident with SAP on this.

      Unfortunately I do not have any Java code to implement this. This exercise was done as a POC.

      Regards

      Arijit

      (0) 
  8. Pallavi gupta

    Hi Arijit,

     

    Thanks for the awsome blog (full of information).

     

    I have a question is OAuth & Meta Data both are the same, if yes please let me how to set up the Meta data tag for an Item / curriculum.

     

    Regards,

    Pallavi

    (1) 
    1. Arijit Das

      Hi Pallavi

      No OData and Medatdata are not the one and same.

      OData is an authentication and authorisation protocol (it identifies you and grants you access to functionality / scope in the target application).

      Metadata could be defined as the raw data structure of an object or application with attributes such as mandatory / optional, data type, length, cardinality etc. One way to you could think of it is as data dictionary for a database.

      Regards

      Arijit

      (0) 
  9. Francisco Martínez

    Hi Arjit,

     

    Thank you for your information. I wonder if it could be possible to create a SSO scenario between SuccessFactors and SAP ERP, without using SAML. Is it possible that SuccessFactors issues a X.509 certificate which can be valid for SAP ERP?

     

    Thanks and Regards

    (1) 
    1. Arijit Das

      Hi Francisco

      SAML is the most common and tested and trusted means to linked SuccessFactors with SAP ERP (using Cloud Connector is one options). Is there any reason why you would not want to use SAML?

      Regards

      Arijit

      (0) 

Leave a Reply