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?03e1fc3791684367a6...
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-0...')?
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 - yashagarwalfor his encouragement to write this blog, neelesh.kamath for his support and 5cea1755d05648198f37ee2c4c14eede for his guidance.
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?03e1fc3791684367a6...
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-0...')?
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 - yashagarwalfor his encouragement to write this blog, neelesh.kamath for his support and 5cea1755d05648198f37ee2c4c14eede for his guidance.
- SAP Managed Tags:
33 Comments
