Skip to Content
Technical Articles
Author's profile photo Piotr Tesny

OAuth2SAMLBearerAssertion Flow with SAP BTP Destination Service.

This instalment opens a mini series of sibling blogs on the OAuth2SAMLBearerAssertion Flow with SAP BTP Destination Service.

Each blogs can be read independently from one another and each sibling blog has a focus on a specific SAP Product or Solution in the dedicated Putting it all together section.


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

A common assumption is that a business user’s remote resource access scope will be determined by that user’s identity as it is known, at a source, on the client application side.

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


User propagation (user SSO) with the OAuth2SAMLBearerAssertion Flow.


At the heart of the OAuth2SAMLBearerAssertion flow is the users Single Sign-On.

A user should be required to authenticate only once in this process. Following that a user’s identity should be seamlessly propagated to backend systems.

However, I have come across situations where people have been trying to re-use the SAML2 Assertion message generated with the WebSSO Profile as a OAuth2SAML Bearer Assertion message.

Using SAML Assertions as Authorization Grants.

This is described in the following Internet Engineering Task Force (IETF) specification [RFC7522], namely:

The OAuth 2.0 Authorization Framework [RFC6749] provides a method for making authenticated HTTP requests to a resource using an access token. Access tokens are issued to third-party clients by an authorization server (AS) with the (sometimes implicit) approval of the resource owner.

In OAuth, an authorization grant is an abstract term used to describe intermediate credentials that represent the resource owner authorization. An authorization grant is used by the client to obtain an access token. Several authorization grant types are defined to support a wide range of client types and user experiences. OAuth also allows for the definition of new extension grant types to support additional clients or to provide a bridge between OAuth and other trust frameworks.

Finally, OAuth allows the definition of additional authentication mechanisms to be used by clients when interacting with the authorization server.

When carefully reading through the above specification it does say the following:

"Assertion Framework for OAuth 2.0 Client Authentication and
Authorization Grants" [RFC7521] is an abstract extension to OAuth 2.0
that provides a general framework for the use of assertions as client
credentials and/or authorization grants with OAuth 2.0. This
specification profiles the OAuth Assertion Framework [RFC7521] to
define an extension grant type that uses a SAML 2.0 Bearer Assertion
to request an OAuth 2.0 access token as well as for use as client

And most importantly:

The format and processing rules for the SAML Assertion
defined in this specification are intentionally similar, though not
identical, to those in the Web Browser SSO profile defined in the
SAML Profiles [OASIS.saml-profiles-2.0-os] specification.  This
specification is reusing, to the extent reasonable, concepts and
patterns from that well-established profile.

I hope that clarifies that matter.

And this is where the SAP BTP Destination service comes to the rescue.


Putting it all together.

The following sibling blogs discuss the OAuth2SAMLBearerAssertion flow use cases with selected SAP Products and Solutions.


SAP Analytics Cloud


and in lieu of conclusion…

What is the rationale behind using the Destination Service ?

The Destination Service takes care of the SSO user propagation.

The Destination Service can accept several sources of the external user identity to be propagated to the remote asset management system for granting the resource access. The most common source of the user identity being a user JWT Token.

The Destination Service is acting as an IDP (identity provider) for the xsuaa service. The xsuaa will additionally validate the saml bearer assertion against this IDP.

The Destination Service provides the signing certificate (the public key) [for the xsuaa service to validate the assertion] out of the box. You will need the public key to create the IDP provider for the xsuaa service on the destination side.

It generates an internally a signed SAML Assertion and calls into the xsuaa service token exchange endpoint.

The Destination Service offers a RESTFUL API service with several well-behaved endpoints. In all likelihood you will need only one single API which is the find destination API. As this is a HTTP RESTFUL API it can be called from any type of client application deployed anywhere.




Additional resources.

SAP Destination Service as a user propagation broker for the OAuth2SAMLBearerAssertion flow.

Using the SAP Business API Hub as your client application.

We shall be using the SAP BTP Connectivity services, and more precisely the destination service to help implement the user propagation logic from a bespoke client application to the assets in the SuccessFactors tenant.

Let’s have a look how the Destination Service can help address this conundrum especially if your client application is wired with a custom Identity Provider and not using the SAP BTP Platform trust configuration.

Good to know:

  • You can leverage Destination services APIs using the SAP_CP_CF_Connectivity_Destination  API package from the SAP Business API hub.
  • And you can also configure your sandbox environment there and try out the Destination Service APIs without writing a single line of code!
  • You can use your SAP BTP trial account to get access to Destination service.

Sandbox environment configuration with Destination service on SAP Business API Hub.

Before you can configure the API hub sandbox environment you will need to have created an instance of the destination service.

  • Goto the BTP trial cockpit to either sign up or login to your trial BTP account.
  • Enter your trial account. You will be let in to your SAP BTP trial global account with the view on the trial sub-account.
  • There you will need to create an instance of the destination service on either the sub-account or subscription (space) level. You will also need to create a destination definition either programmatically or in the SAP BTP Destination service GUI.
  • I suggest that for the sake of simplicity you do this on the sub-account level as anyway the working assumption is our client application is not deployed to SAP BTP platform.

Next step is to create a service key for the instance of the destination service you created in the previous step.

Why this is at all required?

  • As our client application is not deployed to Cloud Foundry we need to be able to get access to the destination service resources remotely.
  • And by design, every CF service can be consumed either directly through the binding mechanism or indirectly (remotely) via the service key exposure mechanism.

The access to the destination service APIs is protected with the OAuth2.0 protocol.

  • That means before you can call into the destination service APIs endpoints you will need first to secure access to the destination service resources (its APIs).

In a nutshell you will need to obtain a bearer access token to be passed in the destination service Authorization header every time you want to invoke any of the destination service APIs.

(Please note this is being taken care of by SAP API Hub once you have defined your sandbox environment).

Good to know:

The Destination service is included with the SAP BTP trial account. Your consent may be required to accept the SAP BTP trial terms and conditions.



Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Riho Riho
      Riho Riho

      Hi Piotr,

      Thanks you for your interesting blog.

      We have configured an OAuth2SAMLBearerAssertion Destination in the Destinations Service in SAP BTP Cockpit to SAP S/4Hana Cloud, which is used by Mendix on BTP. De configuration is looking fine, but the Check Connection test for the OAuth2SAMLBearerAssertion destination keeps giving a response 'Connection to "xxx" established. Response returned: "401: Unauthorized"' and the connection is not working in Mendix.

      We followed the configuration steps in the guide, but it doesn't work.

      Single Sign-on in Mendix on BTP using the IAS from S/4Hana Cloud is working fine.

      ​An Basic Authentication Destination in SAP BTP Cockpit to S/4Hana Cloud is working fine.

      Should the "Check Connection" test in the OAuth2SAMLBearerAssertion Destination give a successful 200 reponse?

      What could be wrong in our situation?

      Kind regards,


      Author's profile photo Piotr Tesny
      Piotr Tesny
      Blog Post Author

      Hi Mark, Thanks for the heads up.

      I have never set this up with S4HC. But the SFSF experience is kind of similar to S4HC configuration.

      1. From my SuccessFactors testbed I I have had the same situation. My URL in the destination definition is an SFSF ODATA endpoint and the Check Connection test returns 401. However, this is perfectly normal as precisely this URL cannot be called without a bearer access token.
      2. From my experience so far the value of the URL field in the destination definition is not that important. You can put or any other valid URL there. Why this is so? The DestinationService is not going to call the URL of your service on your behalf at all. It will rather  provide you with the bearer access token so you can do it yourself.
      3. Looking at the SAP documentation I would check the points 2f and 2g and make sure that looks good.
      4. You could also try calling into the token service URL of your S4HC OAuth client application with the OAuth credentials: token service user/token service password. That should work.
      5. Last but not least, Try to propagate the user identity with a SystemUser first. This must be a user that exists in either your client application and S4HC. You may need to choose the user source like email for instance and have it as a property in your destination definition.
      6. You would configure the Destination Service APIs sandbox on the SAP API Hub to facilitate testing and troubleshooting. This way you could try out changes to your configuration way faster.

      best wishes


      Author's profile photo M. van Dooren
      M. van Dooren

      HI Piotr,

      Thanks for your response. The OAuth2SAMLBearerAssertion connection is working now. Below some comments which helped us to find the solution.

      1. HTTP 401 is indeed the correct result for the Check Connection test for this destination.
      2. The destination service indeed doesn’t do the API call itself. Mendix on BTP is reusing the URL of the destination to do the specific API call via a microflow step, so in our case it is important that the URL is configured correctly.
      3. The parameters were checked and were correct.
      4. This is working indeed.
      5. This is a good approach. Starting with a destination with a fixed SystemUser property confirms whether most of the configuration is correct.
      6. The Destination service API on SAP API Business Hub is indeed very helpful. A destination with a fixed SystemUser property can be tested really easy here. Testing a destination with a x-user-token is more difficult because an x-user-token needs to be generated and provided. An small node.js application is needed. It would be user friendly to provide this as out of the box functionality on API Business Hub. Note: to be able to test a destination via the Destination service API on SAP API Business Hub (externally), the Destination Service on BTP needs to be activated as well.

      Mendix on BTP is using it's own xsuaa service. In the end we had to add the following additional parameters to the destination to get it working:

      • nameIdFormat = urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
      • userIdSource = email
      • x_user_token.jwks_uri = https://<Mendix BTP host>/token_keys

      Kind Regards,

      Mark van Dooren