Human Capital Management Blogs by SAP
Get insider info on SAP SuccessFactors HCM suite for core HR and payroll, time and attendance, talent management, employee experience management, and more in this SAP blog.
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 

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

EderSouza
Advisor
Advisor
‎04-18-2023 9:43 AM
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:

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

 
Popular Blog Posts