OAuth2SAMLBearerAssertion Flow with the SAP BTP Destination Service. SAP Analytics Cloud CF edition.


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

Good to know:

User propagation (SSO) with the OAuth2SAMLBearerAssertion Flow

Long story short.

I have come across situations where people have been trying to re-use the SAML2 Assertion message generated with the WebSSO Profile as a SAML2 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.

Destination Service as a user propagation broker for the OAuth2SAMLBearerAssertion flow. Quo vadis?

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 Analytics Cloud 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!

Sandbox environment configuration

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 space level. You will also need to create a destination either programmatically or via SAP BTP cockpit GUI.
  • I suggest that for the sake of simplicity you do this on the sub-account level as anyway 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).

Putting it all together

Assuming you have the right level of access to your target SAC system you may need to create your own OAuth2.0 client application. Your SAC system maybe either Enterprise or Embedded Edition tenant on SAP BTP Cloud Foundry.

Let’s call the OAuth client Quovadis-SAC. (But this can be any name.)

The OAuth client should be for the interactive usage and there is no need to define any redirect uri. With the saml bearer assertion (as apposed to the authorization code flow) flow there will be no refresh token. We shall only be retrieving the short lived access token.

One piece of information you will need from the Destination service from the SAP BTP sub-account level is the public key (=the X.509 certificate) to that you will need to insert into SAP Analytics Cloud tenant’s Trusted Identity Provider as depicted below:

Good to know:

  • Each SAC CF tenant is tied up to its own SAP BTP Cloud Foundry sub-account. However, you can only get a partial access to the sub-account for the data acquisition, tunnelling or scheduling workflows via SAP Cloud Connector.
  • When you create an OAuth client application from SAC GUI this triggers a creation of an instance of the SAC-dedicated xsuaa service.
  • When you add a Trusted Identity Provider that triggers creation of an IDP for the sub-account. The provider name of the Trusted Identity Provider must not be random. It is equal to the CN name of the X.509 certificate.
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 with the APIs from the sandbox environment as follows:

Post (=create) a new destination:
Put (=update) an existing destination: { "Name": "Quovadis-SAC", "Type": "HTTP", "URL": "<SAC tenant URL>", "Authentication": "OAuth2SAMLBearerAssertion", "ProxyType": "Internet", "tokenServiceURLType": "Dedicated", "audience": "<OAuth2SAML Audience from SAC/System/Administration/App Integration>", "authnContextClassRef": "urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession", "clientKey": "<client_id from your SAC OAuth2 client>", "tokenServiceUser": "<client_id from your SAC OAuth2 client>", "SystemUser": "<technical user email address", "tokenServiceURL": "<OAuth2SAML Token URL from SAC/System/Administration/App Integration>", "tokenServicePassword": "<client_secret from your SAC OAuth2 client>"
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 let's use a technical user, a user that must exist in both the client application and the target backend system. In a productive scenario you would rather be using a user JWT token instead!
Find destination API call:

As a result of this call you will get the bearer access token that you can use to call into the any SAP Analytics Cloud APIs, your user may have access to, as depicted below:

  • Step 1. create a destination
  • Step2. get the destination
  • Step3. find the destination
  • Step4. use the bearer access token from previous step with any eligible SAC APIs

Good to know:

  • You can call the find API any time you need the bearer access token.
  • The Destination Service takes care of caching, rotating and renewing of the access token.
  • That hugely simplifies the access token housekeeping and also makes the code of the client application very simple.
  • All the sensitive information like the endpoints of the SAC OAuth2.0 server as well the SAC OAuth client application details are never disclosed and maintained securely in the Destination Service vault.
  • Same applies to the private key of the X.509 certificate. It is never disclosed.

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 internally a signed SAML2 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.

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.

best wishes

Piotr Tesny