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

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
credentials...."

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.

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.

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.