SAML assertions for SAP SuccessFactors OAuth 2.0 API's: Handling of User Identifiers

[EderSouza]

Hello SAP Community,

In the blog Testing SAP SuccessFactors’ API’s: How to use Insomnia to automate the generation of SAML Assertions I've followed the instructions provided on SAP documentation Generating a SAML Assertion to generate SAML assertions that could be used in the OAuth 2.0 authentication of SAP SuccessFactors' API's. However, during the authentication tests of this method it was possible to see (with the help of my dear colleagues rodriguesh01 and sarah.homer from CoE EMEA ❤️) that the user identifier entered in the NameID tag of the resulting SAML assertion is always mapped to an User ID in SAP SuccessFactors.

However, if you have already used the soon-to-be deprecated /oauth/idp endpoint, you might have stumbled across the parameters use_email and use_username mentioned in the KBA 2668018 - Error message: "Unable to authenticate the client (Login failed - invalid user)" for Oauth... , which allows SAML Assertions to be created using the Username and the E-mail as user identifiers. This might be useful depending on the information that you have available at the moment the SAML Assertion is created; yet the new documentation does not mention how to do that when creating the SAML assertion from scratch. An analysis of the SAML Username / E-Mail assertions generated by the SAP SuccessFactors /oauth/idp endpoint has allowed us to identify which attributes were added for each case and enhance the manually generated SAML Assertion according to the informed user identifier.

If you are unsure which of the three user identifiers (User ID, Username or E-Mail) you are going to use for SAP SuccessFactors authentication, the documents below can help you understand the difference between User ID and Username:

• 2495643 - SuccessFactors User IDs - Clarifying the Different IDs (sap.com)


• Differentiating Between Person ID, User ID, and User Name in Employee Central | SAP Help Portal


• 2493579 - Employee Central: Person/User IDs Used Within Employee Central - SuccessFactors Employee P...

The screenshot below of the Manage Login Accounts tool from SAP SuccessFactors can help you to find the Username and E-Mail information for a specific user:

Manage Login Accounts tool

Below is an extended version of the SAP Documentation on how to generate SAML Assertions according to the informed user identifer. It is important to highlight that this might be subject to SAP changes and it is not SAP official:

 

Element	Description	User Identifier	Example
<saml2:Issuer>	Issuer information of the SAML assertion	All	<saml2:Issuer>www.myidp.com</saml2:Issuer>
<saml2:Subject>, <saml2:NameID>, Format and Recipient	Enter the SAP SuccessFactors user identifier that you use to access the APIs in the NameID element. The Format attribute has to be adjusted according to the user identifier type: E-mail: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress User ID and Username: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified The Recipient attribute must be set as the URL of the API server from which you request the OAuth token.	User ID, Username	<saml2:Subject> <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">admin</saml2:NameID> <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <saml2:SubjectConfirmationData NotOnOrAfter="2020-08-21T09:23:24.511Z" Recipient="http://<api-server>/oauth/token"/> </saml2:SubjectConfirmation> </saml2:Subject>
		E-Mail	<saml2:Subject> <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">admin@test.com</saml2:NameID> <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <saml2:SubjectConfirmationData NotOnOrAfter="2020-08-21T09:23:24.511Z" Recipient="http://<api-server>/oauth/token"/> </saml2:SubjectConfirmation> </saml2:Subject>​
<saml2:AttributeStatement> and <saml2:Attribute>	The AttributeStatement element must contain the API key (clientId) that you obtained after you register the client application in Registering Your OAuth2 Client Application. If the Username is used as user identifier, then an additional AttributeStatement tag is required setting the use_username Attribute as true.	User ID, E-Mail	<saml2:AttributeStatement> <saml2:Attribute Name="api_key"> <saml2:AttributeValue xsi:type="xs:string">NDU0MDE0MDkwYj***5YTE5MWIxMTNkNjc1Zg</saml2:AttributeValue> </saml2:Attribute> </saml2:AttributeStatement>​
		Username	<saml2:AttributeStatement> <saml2:Attribute Name="api_key"> <saml2:AttributeValue xsi:type="xs:string">NDU0MDE0MDkwYj***5YTE5MWIxMTNkNjc1Zg</saml2:AttributeValue> </saml2:Attribute> </saml2:AttributeStatement> <saml2:AttributeStatement> <saml2:Attribute Name="use_username"> <saml2:AttributeValue xsi:type="xs:string">true</saml2:AttributeValue> </saml2:Attribute> </saml2:AttributeStatement>​
<saml2:Conditions>, NotBefore, NotOnOrAfter and <saml2:Audience>	The NotBefore and NotOnOrAfter attributes in the  element defines the validity period of the SAML assertion. The element is used to tag the SAML assertion. Any value is accepted except empty value. For example, www.successfactors.com.	All	<saml2:Conditions NotBefore="2020-08-21T09:03:24.511Z" NotOnOrAfter="2020-08-21T09:23:24.511Z"> <saml2:AudienceRestriction> <saml2:Audience>www.successfactors.com</saml2:Audience> </saml2:AudienceRestriction> </saml2:Conditions>​

I hope this information can be useful for the developers/system administrators that are going to create or enhance SAML assertions for OAuth 2.0 authentication informing the Username and E-mail information from the SAP SuccessFactors' user. These user identifier options are available in the Insomnia Plugin I've developed to automate the generation of SAML assertions for testing of SAP SuccessFactors' API's - the name of the corresponding parameter is User Identifier Format . Feel free to check it using the links below:

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

insomnia-plugin-sfsf-samlassertion - Insomnia