OAuth2SAMLBearerAssertion Flow with the SAP BTP Destination Service. SuccessFactors.
This instalment belongs to a mini series of blogs on the OAuth2SAMLBearerAssertion Flow with the SAP BTP Destination Service. The focus being on how to leverage the destination service’s default x.509 trust with your destination. Good to know:
|
Abstract.
|
And this is where SAP BTP Destination service comes to the rescue. |
Putting it all together.
|
Before you can configure the API hub sandbox environment you will need to have created an instance of the destination service on your SAP BTP sub-account. Please refer to the following article on the details for the sandbox environment configuration with SAP API Business Hub. Assuming you have the right level of access to your target SFSF system you may now create there your own OAuth2.0 client application. Let’s call it Quovadis-SFSF. One piece of information you will need from the Destination service created on SAP BTP sub-account level is the trust’s public key that you will need to insert into the Quovadis-SFSF OAuth2.0 client application as depicted below:
|
Assuming you will be rehearsing the access to the destination
service APIs with the SAP Business API Hub sandbox environment
you do not need to write a single line of code.
All you need to do is create a definition of your destination
Your destination will be called by the destination
service find api any time you need to procure a bearer access token
to authorize access to remote resource.
You can create a destination definition using the GUI of the SAP BTP sub-account or programmatically calling the destination service APIs.
Let’s rather do it programmatically as follows:
Post (=create) a new destination:
Put (=update) an existing destination:
https://destination-configuration.cfapps.<region>.hana.ondemand.com/destination-configuration/v1/subaccountDestinations
{
"Name": "Quovadis-SFSF",
"Type": "HTTP",
"URL": "https://apisalesdemo2.successfactors.eu/odata/v2/User/$metadata",
"Authentication": "OAuth2SAMLBearerAssertion",
"ProxyType": "Internet",
"tokenServiceURLType": "Dedicated",
"audience": "www.successfactors.com",
"authnContextClassRef": "urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession",
"companyId": "<SFSF company code>,
"clientKey": "<apiKey from Quovadis-SFSF application>",
"apiKey": "<apiKey from Quovadis-SFSF application>"
"SystemUser": "<technical user>",
"nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
"tokenServiceURL": "https://salesdemo.successfactors.eu/oauth/token"
}
Reference the URL value please refer to the following SAP note
2215682 - Successfactors API URLs for different Data Centers
Most of the values will need to come from the OAUTH2.0 service
which is used to protect the remote resource you are trying
to have your user get access to.
For the sake of simplicity and for sandboxing purposes only
we may use a technical user, a user that must exist in
both the client application and the target backed end system.
In a productive scenario you would rather be using
a user's JWT token instead! This user's JWT token would need
to be passed in the X-user-token header of the destination
service find destination API call.
Then, the destination service will internally generate a saml assertion
for user's authentication with the:
- destination server x509 trust as the assertion issuer,
- audience as the assertion audience (service provider),
- tokenServiceURL as the assertion's recipient (ACS=Assertion Consumer Service)
- and both the apiKey and companyId properties.
This assertion will be used on the IDP-initiated flow with the
recipient acting as ACS (Assertion Consumer Service).
Find destination API call:
https://destination-configuration.cfapps.<region>.hana.ondemand.com/
destination-configuration/v1/destinations/Quovadis-SFSF
where the region would be any of the BTP regions where
the destination service is available.
|
As a result of this call you will get the bearer access token that you can use to call into the any SFSF OData APIs, your user may have been granted access to, as depicted below:
|
__________
Troubleshooting
| This is how to troubleshoot a saml assertion that is being generated by destination service:
How to troubleshoot SAP BTP OAuth2SAMLBearerAssertion destination with SuccessFactors?
|
Additional reading
Last but not least. Let’s see the rationale behind using the Destination Service.SAP SuccessFactors HXM Suite OData API: Developer Guide (V2) |
Hello Pieter,
Please refer to the Putting it all together section of this blog post.
In a nutshell the access to destination service REST APIs is protected by a destination service own OAuth client.
Assuming you are rehearsing your destination on API Business Hub, first you will need to set up a destination service sandbox there.
Before you can configure the API hub sandbox environment you will need to have created an instance of the destination service on your SAP BTP sub-account.
Please refer to the following article on the details for the sandbox environment configuration with SAP API Business Hub.
I hope this helps. Regards; Piotr
Hi Piotr,
My goal is to find out what issue I have in my destination to SF where the API is returning:
I have an endpoint created in a CAP application to return the JWT of my authenticated user and then I want to use that JWT as the Bearer token to the destinations call in order for it to return the bearer token (destintation 'authTokens' response) that would be used to authenticate with the SF API.
When I use the client id/secret of the destination service instance key and query my 'successfactors' destination via https://destination-configuration.cfapps.eu10.hana.ondemand.com/destination-configuration/v1/destinations/successfactors it returns the following error message for the 'authTokens' property in the response:
Update
uaa.userUpdate 2
Hello Pieter,
a. My 1st recommendation would be that you make it work using the API Hub Sandbox to call your destination via find destination API. In other words without your CAP application.
You may refer to this comment for the detailed steps.
This must work before going any further!
b. you might want to share the destination definition by redacting the sensible information...
c. regarding the user JWT token...if you decode it using jwt.io you must be able to see there the SFSF user' identity your are trying to propagate.
And if the user's identity claim in the jwt token is different from user_name then you will need to additionally tell the destination service what claim it is: for instance sub, email, etc...
I hope that helps; Piotr;
Hello Piotr,
Thanks to the API Hub Sandbox I noticed that I need to send the end-user's JWT as X-user-token header value and not as the bearer token. I am now getting the authToken returned that would be send to the SF API (this works both in the API Hub Sandbox or in Postman).
The result of a direct call to the SF API is the same as through the approuter: 403 [LGN0022]Person-only not supported when gace flag is off
This is the base64 decoded (redacted) content of the authToken for the SF API resturned by the destination service:
FYI the user_name of the JWT is correct and matches the SF userId as is required by OAuth in SF.
Hello Pieter,
OK. So it looks like you can retrieve the access bearer token via find destination API call. That's great!
Re the error message: which SFSF ODATA API endpoints you have tried ? is it a GET or POST/PUT API call ? can you tell more about it ?
Otherwise there is a SAP note, namely 2872019 - [LGN0022]The access token is either rejected or expired - SuccessFactors HXM Suite - Can you cross check if this is relevant to your problem?
Hi Piotr,
It's a GET call. I found that note as well, but it doesn't seem to be related.
The the bearer access token for SF contains this 'personOnly:true' and the personGUID instead of the user ID. When I create an access token via postman like it's explained in 2800150 - How to test OAuth authentication via Postman - SuccessFactors Integrations, the access token that is provided does not contain the properties 'personOnly' or 'personGuid' and the 'sfPrinciple' property contains the SF user ID and not the SF person GUID (as shown in my previous comment).
Pieter
Hi Pieter,
OK. The method described in 2800150 relies on the SFSF OAuth2 client idp endpoint to generate the saml assertion with the SFSF user id. This method has two big caveats: it needs the private key of your x509 certificate to be passed in the idp endpoint call and it requires a hard-coded user id.
On a side note: you will likely obtain the same result with the destination service if you add the "SystemUser" property with the user id. (You do not need to remove the other jwt related properties as SystemUser property will override them. Please note SystemUser property is deprecated and may be removed from service any time soon.)
Still my understanding is that regardless of the method you use to obtain the bearer access token you get the same error when calling the ODATA API ? Correct ?
403 error means Forbidden. So this is likely related to your SFSF user permissions.
Even if the aforementioned note SAP note is not that relevant it points to page 30 of the SAP SuccessFactors HXM Suite OData API: Developer Guide (V2). Please have a look if your problem is or is not related to SFSF user permissions.
Have you tried to call the API with sfadmin as user?
Hi Piotr,
My intention is to use the destination and not the idp endpoint. I only mentioned this to indicate the difference in the decoded content of the bearer access token. The one generated by the destination service contains a 'personOnly' and the error returned by the API seems related "[LGN0022]Person-only not supported when gace flag is off".
This error is only received when using the access token provided by the destination service. I really think the issue lies with the destination service (or the successfactors extension service, in case it's still used somehow after the destination is generated by it).
I don't understand where the person GUID even comes from (it's the correct SF person GUID for the provided SF userId (JWT user_name). The SF person GUID is NOT part of the JWT and thus is retrieved somehow by the destination service from SF?!
Pieter
Hello Pieter,
Indeed the destination service will call the SFSF OAuth client token endpoint via tokenServiceURL passing it the saml assertion that it has generated internally [based on the destination definition properties].
What it means that whatever you can see in the decoded bearer access token eventually comes back from SFSF OAuth client.
What you could do is the following:
1.Could you please test with find destination using SystemUser property in the destination definition to pass the same SFSF user id or name as with the SFSF idp endpoint?
(I bet the bearer access token would be like for like as via the internal SFSF idp endpoint.)
2.Could you please explain how you generate the X-user-token ?
3.Could you please provide the destination definition ? not the screenshot from the UI but rather the json output from the get destination API call ?
Thanks;Piotr
PS, not sure about your relationship with SAP; are you a partner/customer?
Hello Pieter,
Long story short: when using find destination with the dynamic business user identity (passed via user JWT token) and if the user JWT token contains the user_uuid attribute, this user_uuid attribute will be added to the internally generated saml assertion. Please note this is by design.
You may refer to this other blog post for more details.
I hope that helps; Piotr;
Hello Piotr and fellow blog readers,
I can confirm that the cause of my issue is related to the presence of the user_uuid in the SAML assertion. The solution was to remove the user_uuid as a (default) SAML assertion attribute in IAS for the BTP application.
IAS would pass the (internal) user_uuid to BTP during SSO, XSUAA would then include the user_uuid in the JWT which is passed to the destination service. The destination service then includes that user_uuid in the SAML assertion it generates. Upon receiving the user_uuid as assertion attribute, SuccessFactors assumes (IMO wrongfully) that we want to receive a person GUID based access token. The access token is then refused when used to authenticate to the OAuth protected OData API.
Thank you Piotr for helping out and finding the solution!