Human Capital Management Blogs by SAP
Get insider info on HCM solutions for core HR and payroll, time and attendance, talent management, employee experience management, and more in this SAP blog.
cancel
Showing results for 
Search instead for 
Did you mean: 
quovadis
Product and Topic Expert
Product and Topic Expert

























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:

  • Please consider there are other types of authorization flows that might be a better fit for your application.

  • Using SAML Assertions as Authorization Grants covered in here








Last but not least, please consider reading a sibling blog to see how to leverage the Destination Service with your own key pair (with your own x.509 trust), namely:



Abstract.









The SAML 2.0 Bearer Assertion Flow typically comes into play when we want to give a client application's users an automated access to remote resources or assets which are protected with the OAuth2.0 protocol.


A common assumption is that the user's remote resource access scope will be determined by the user's identity as it is known on the client application side.


Thus the most important aspect of this flow is the propagation of the user's identity to the backend system commonly referred to as Principal (=user identity) Propagation.


 

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/sub...

{
"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 service 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:


 

Appendix








As of June 2021, SAP BTP destination service features a newly added /saml2Metadata. REST API endpoint allowing you to download the generic SAML IdP metadata (that precisely contains the x.509 certificate) 

https://destination-configuration.cfapps.<region>.hana.ondemand.com/destination-configuration/v1/sam...

{
"idpMetadata": "PG5zMzpFbnRpdHlEZXNjcmlwdG9yCiAgICAgICAgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvMDkveG1sZHNpZyMiCiAgICAgICAgeG1sbnM6bnMyPSJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L3htbGVuYyMiCiAgICAgICAgeG1sbnM6bnM0PEZXNjcmlwdG9yPgogICAgPC9uczM6SURQU1NPRGVzY3JpcHRvcj4KPC9uczM6RW50aXR5RGVzY3JpcHRvcj4="
}









The  resulting idpMetadata string is a base64-encoded  generic IDP XML metadata. It does contain the x509 certificate but is not configured for any specific scenario (i.e. CF to CF, CF to Neo etc.) which might require additional properties.

For convenience, it the can be decoded into plain XML with any saml assertion decoder  and then  formatted with pretty print as follows:

<?xml version="1.0"?>
<ns3:EntityDescriptor xmlns="http://www.w3.org/2000/09/xmldsig#" xmlns:ns2="http://www.w3.org/2001/04/xmlenc#" xmlns:ns4="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ns3="urn:oasis:names:tc:SAML:2.0:metadata">
<script/>
<ns3:SPSSODescriptor AuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<ns3:KeyDescriptor use="signing">
<KeyInfo>
<X509Data>
<X509Certificate> MIIFiDCCA3CgAwIBAgIKl4jx5h0R3MSTdzANBgkqhkiG9w0BAQ0FADCBgjFLMEkG A1UEAwxCY2ZhcHBzLmFwMjEuaGFuYS5vbmRlbWFuZC5jb20vYWZiYWM0ZGUtOWQx D85Qu75kaZW44MwyUDaiWBfvV2MH3dT7MxaLaQ== </X509Certificate>
</X509Data>
</KeyInfo>
</ns3:KeyDescriptor>
</ns3:SPSSODescriptor>
<ns3:IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<ns3:KeyDescriptor use="signing">
<KeyInfo>
<X509Data>
<X509Certificate> MIIFiDCCA3CgAwIBAgIKl4jx5h0R3MSTdzANBgkqhkiG9w0BAQ0FADCBgjFLMEkG A1UEAwxCY2ZhcHBzLmFwMjEuaGFuYS5vbmRlbWFuZC5jb20vYWZiYWM0ZGUtOWQx D85Qu75kaZW44MwyUDaiWBfvV2MH3dT7MxaLaQ== </X509Certificate>
</X509Data>
</KeyInfo>
</ns3:KeyDescriptor>
</ns3:IDPSSODescriptor>
</ns3:EntityDescriptor>

 

 

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)



 
29 Comments