Testing SAP SuccessFactors' API's: How to use Insomnia to automate the generation of SAML Assertions

[EderSouza]

Hello SAP community,

If you regularly call the SAP SuccessFactors' OData API's for test purposes using your API test tool of choice, chances are that you are already aware that the Basic Authentication is deprecated and must not be used; instead, the authentication using OAuth 2.0 is the preferred method to access its API's. The steps involved in enabling an OAuth2 client are described in the SAP SuccessFactors Documentation and this blog is focused on the step 2 - Request SAML assertion of the flow diagram that is depicted in there:

Assuming that you use a third-party Identiy Provider (short IdP) to issue SAML Assertions, then you might have already adjusted your SAP SuccessFactors test cases and authentication flows according to your IdP request/response expectations. However, if you are using the SAP SuccessFactors Offline SAML Generator, then you are probably relying on the external Java tool available in the SAP Note 3031657 - SAP SuccessFactors SAML Assertion format demonstration using SAP Provided offline tool - S..., which might not be well-integrated to your API test tool as you have to manually copy/paste the externally generated SAML assertion to your test cases. Or even worse: you might be using the /oauth/idp API from SuccessFactors to get your SAML Assertions generated, which is also going to be deprecated due to security risks! Check this SAP SuccessFactors Documentation to more information on that: Deprecation of OAuth IdP API /oauth/idp | SAP Help Portal.

The challenge is then set: how to integrate this process of generating SAML Assertions to the API test clients?

Postman is the ubiquitous test tool for API's nowadays and it I was decided to embed the SAML Assertion routines in its Pre-Request Scripts. Unfortunately, it was easier said than done... 😞 The Node.js sandbox of Postman is quite restrictive and does not allow the usage of well-established npm libraries for SAML Assertion / XML signature. Even when I somehow managed to workaround it, Postman's Node.js sandbox has limited cryptographic capabilities, which turned the signature of the SAML Assertions impossible. Would that then be a reason to lose sleep? 😄

At this point I decided to give another API test tool called Insomnia a try. And what a pleasant surprise! Their plugin concept is quite powerful and allowed me the usage of external npm libraries to develop a Template Tag for generating the SAML Assertion right before the request is sent to the endpoint - exactly what I wanted! Besides, the seamlessly integrated Chrome V8 JS engine made debugging way easier, which was key during the plugin development process. Moreover, it allows to import Postman's Collection files, which speeds up the tool onboarding. The downsides I've recognized so far are that the Insomnia's Free version does not allow team collaboration and test collections are not saved in the cloud.

Insomnia Plugin: Installation and Configuration

Here are the Insomnia/npm links of the SuccessFactors SAML Assertion plugin:

https://insomnia.rest/plugins/insomnia-plugin-sfsf-samlassertion

https://www.npmjs.com/package/insomnia-plugin-sfsf-samlassertion

Once the plugin is properly installed, the Template Tag SAML Assertion - SFSF will be available for use. Here are some steps to install the SAP SuccessFactors SAML Assertion plugin:

1. 
   
   
   
   1. Once you have downloaded and installed Insomnia (https://insomnia.rest/download), you will find under the link https://insomnia.rest/plugins/insomnia-plugin-sfsf-samlassertion the Install Plugin button that will start the Insomnia application and the plugin installation process. Once Insomnia is opened, you have to confirm the installation by clicking in the Install button:
      Alternatively, you can also open the Insomnia application under the menu Application -> Preferences , tab Plugins and install the plugin by entering its corresponding npm package name insomnia-plugin-sfsf-samlassertion under the npm-package-name field and pressing the Install Plugin button:
   
   
   2. In this example I am going to import Postman's exported collection into Insomnia to add the Template Tag SAML Assertion - SFSF to existing testing cases (check the documentation https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-collection... for more details on how to do that in Postman). Go to My Collection -> Import/Export:Select the Import Data -> From File option. A modal screen will be shown so that you can select the collection exported from Postman - click on Import and you must receive a confirmation that the collection was successfully imported:
      
   
   
   3. Add the SAML Assertion - SFSF Template Tag where required. In this example, we are going to add it to the assertion form parameter of the POST request https://apisalesdemo2.successfactors.eu/oauth/token, but depending on where your SAP SuccessFactors data center is located this URL might change - check the SAP Note 2215682 - Successfactors API URLs for different Data Centers - SAP for Me to verify the correct API URL for your case.Template Tags can be added to a target field by pressing the Ctrl + Space keys, and their configuration is shown once you click on them. Once it is properly configured, it will generate Base64 encoded SAML Assertions and assign it to the assertion form field:
      As a side note, I had to change the Content-Type header for this operation manually to application/x-www-form-urlencoded, thing that wasn't necessary in Postman.
   
   
   4. Once you hit the Send button, you must be able to retrieve the OAuth token with the generated SAML Assertion.
      To use this access token in other requests, the built-in Template Tag Response => Body Attribute from Insomnia can be used so that it automatically extracts an information from a response body for usage in other requests . In this example, I use this Template Tag to extract the $.access_token attribute from the response above so that it can be used for authentication in another GET request:
      
   
   
   
   

Template Tag SAML Assertion - SFSF

The parameters of the SAML Assertion - SFSF Template Tag are displayed once you double click it, and you can see live the generated Base64 encoded SAML Assertion on the Live Preview field after you configure it:

The list of parameters of the SAML Assertion - SFSF Template Tag can be found below:

• X.509 Certificate: Public certificate corresponding to the key pair used for client configuration in SAP SuccessFactors.


• Private Key: Private key of the key pair that will be used to sign the SAML assertion.


• SAML Issuer: Name of the IdP issuing the SAML Assertion. The proposed value local.insomnia.com should be a good starting point.


• Lifetime in seconds: Lifetime of the SAML Assertion in seconds.


• Client Id: Registered Client Id in SAP SuccessFactors, also called as API key in the SAP SuccessFactors Documentation.


• User Identifier (changed on April/2023): User identifier to be used to access the SAP SuccessFactors API's.


• User Identifier Format (added on April/2023): Type of User Identifier informed for SAML assertion. It can be one of the three following types: User ID, Username or E-Mail - check the blog SAML assertions for SAP SuccessFactors OAuth 2.0 API’s: Handling of User Identifiers
  
  
  

  to better understand which of these options best suits your test needs.

  
  


• OAuth Token Endpoint: The URL of the API server from which you request the OAuth token.


• Audience: Value used to tag the SAML assertion. The proposed value www.successfactors.com should be a good starting point.

For more information on the parameters above, please refer to the SAP SuccessFactors documentation Generating a SAML Assertion | SAP Help Portal. Please do also check the blog SAML assertions for SAP SuccessFactors OAuth 2.0 API’s: Handling of User Identifiers to understand the user identifier types that can be used when creating the SAML assertion.

I hope this Insomnia plugin can be a valid alternative for SAP SuccessFactors API testers out there willing to automate their test scenarios. Feel free to check the GitHub repository https://github.com/edersouza38/insomnia-plugin-sfsf-samlassertion of the plugin - whenever possible I'll check issues and suggestions to be incorporated! As a last remark, thanks to my CoE colleagues rodriguesh01 (SAP SuccessFactors) and sarah.homer (Integration) for working together in this topic that gave birth to this plugin! ❤️