Integrating with SAP Datasphere Consumption APIs using SAML Bearer Assertion

gustavokath

SAP Datasphere facilitates smooth and scalable access to business data, thereby supporting the business data fabric architecture. SAP Datasphere's is committed to data openness and freedom of choice for analytical frontend solutions and allow development of customized applications connected to it.

The Consumption OData API serves as a prime example of this, providing access to all model types from Facts via relational data access to Analytic Models in analytical mode. Some of this was covered by Mirko Link here.

When integrating SAP Datasphere to other applications the authentication methods are vital to deliver a good customer experience. With the use of SAML Bearer Assertion propagation is possible to forward the IdP authentication from a browser based third-party application to SAP Datasphere without any extra user interaction. Leveraging federated data and Data Access Controls applied to any SAP Datasphere model, the only requirement is that the user must be registered in both applications.

This blog post aims to guide you through the setup of integrating a NodeJS application from SAP Business Technology Platform (BTP) with SAP Datasphere using SAML Bearer Assertion destinations. It will cover the following steps:

Configure Identity Provider Custom User Attribute
Establish Trust between BTP Destinations and SAP Datasphere
Create SAP Datasphere OAuth Client
Setup Destination to SAP Datasphere Consumption APIs
Create XSUAA and Destination Service Instances
Develop BTP Application connected to SAP Datasphere

The initial 3 steps detail the necessary requirements for integrating any system with SAP Datasphere using SAML Bearer Assertion principal propagation. Steps 4,5, and 6 specifically address how BTP Apps can be correctly configured for successful integration with SAP Datasphere.

1. Configure Identity Provider & User Attribute Setup

To allow the SAML Bearer propagation attributes to be recognized its is important that the IdP used in your application to configure the user attributes with "Groups" value equal to "sac".

In this blog, we will be using the SAP Identity Authentication Service (IAS). However, the procedure should be similar with any other Identity Provider.

Open the SAP BTP Cockpit on the subaccount level
Go to Trust Configurations
Click on "New SAML Trust Configuration" to trust your IdP on BTP Platform.
More details can be found on this tutorial. After doing this it should look like bellow:
Open Your IAS Administrator panel
Go to Applications & Resources
Select the Application of your subaccount
Open the "Attributes" menu
Add the "Groups" attribute with static value "sac"

2. Establish Trust between BTP Destinations and SAP Datasphere

Another important requirement is establishing trust between SAP Datasphere and SAP BTP Destinations. This specifies which sources SAP Datasphere can rely on and accept the SAML propagated tokens. This requires providing specific sub-account information for the SAML Bearer Assertion principal propagation flow. Follow the steps below to setup:

Open SAP BTP subaccount
Go to "Destinations" tab
Click on "Download IDP Metadata"
This will download a XML file containing the Trust Identity Provider name and signing certificate, copy those 2 fields
Open SAP Datasphere Administration Page
Go to "App Integration" tab
On "Trusted Identity Providers" click on "Add a Trusted Identity Provider"
Give a name to the new trusted IdP and add Provider Name and Signing certificate copied from the XML file

3. Create SAP Datasphere OAuth Client

To setup the connection to SAP Datasphere Consumption APIs it is needed to generate an OAuth Client which contains the information required to authenticate via OAuth2.0 protocol.

Go to your SAP Datasphere Administration page
Open "App Integration" tab
On the OAuth Client section, you will find important URLs for generating the OAuth credentials, save it for later. Later on this blog when there is a reference to the bellow tags replace it by its correspondent:
- <oauth2_saml_token_url>: OAuth2SAMLTokenURL
- <oauth2_saml_audience>: OAuth2SAMLAudience
Create a New OAuth Client to be used later
1. Set the name of your OAuth Client
2. In Purpose field set "Interactive Usage"
3. Redirect URI field can be left blank
4. Click Save
Copy the Client ID (oauth_clientId) and Client Secret (oauth_secret) which appear in the pop and save them somewhere safe. They will be used later.

4. Setup Destination to SAP Datasphere Consumption APIs

Next, we must establish a SAML Bearer Assertion destination. This will manage the authentication propagation and facilitate communication with the SAP Datasphere Consumption APIs.

Open SAP BTP subaccount cockpit on Destinations page
Click "Create Destination" and fill the required information as follows:
- Name: <name> - Provide a name to the destination
- Type: HTTP
- URL: <sap_datasphere_url> - Consumption API URL to be consumed
```
 http://<datasphere-host>/api/v1/dwc/consumption/analytical/<space>/<asset>/<asset>
```
- Proxy Type: Internet
- Authentication: OAuth2SAMLBearerAssertion
- Audience: <oauth2_saml_audience> - OAuth2SAMLAudience copied on step 3
- AuthnContextClassRef: urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession
- Client Key: <oauth_clientId> - OAuth Client ID from step 3
- Token Service URL: <oauth2_saml_token_url> - OAuth2SAMLTokenURL from step 3
- Token Service User: <oauth_clientId> - OAuth Client ID from step 3
- Token Service Password: <oauth_secret> - OAuth Secret from step 3
Save

5. Create XSUAA and Destination Service Instances

In order to ensure the application we develop in the next section properly validates authenticated users, checks permissions, and consumes the destinations, we need to create service instances for XSUAA and Destination Service. These will be bound to our backend and Approuter applications

5.1. Create XSUAA Service Instance

Open BTP Cockpit on sub-account level
Go to "Instances and Subscriptions"
Click "Create" button
Fill the creation form with the following
- Service: Authorization and Trust Management Service
- Plan: application
- Runtime Environment: Cloud Foundry
- Space: <space_name> - The space name where your application will be deployed
- Instance Name: <uaa_instance_name> - The name of the XSUAA instances created to be bound to the future app
Click "Next" and provide the bellow entry in the JSON configuration
```
{
  "tenant-mode": "dedicated"
}
```
Finish clicking "Create" on the dialog

5.2. Create Destination Service Instance

As the previous step, open BTP Cockpit and go to "Instances and Subscriptions"
Click "Create" button
Fill the creation form with the following
- Service: Destination Service
- Plan: lite
- Runtime Environment: Cloud Foundry
- Space: <space_name> - The space name where your application will be deployed
- Instance Name: <destination_instance_name> - The name of the XSUAA instances created to be bound to the future app
Finish clicking "Create" on the dialog

6. Develop BTP Application connected to SAP Datasphere

To finish this blog post we will develop a simple suite of BTP Applications. These will simulate any custom-developed, browser-based app on BTP that can call one or multiple SAP Datasphere Consumption APIs. The applications in development are based on the tutorial "Secure a Basic Node.js App with the Authorization and Trust Management Service (XSUAA)". Some details may be omitted to simplify this blog post's content and focus more on the SAP Datasphere integration rather than the XSUAA setup. For any queries, please refer to the complete tutorial.

The architecture of the sample app comprehends a NodeJS-express based application, which serves as a proxy to consume SAP Datasphere models exposed via the Consumption APIs. A SAP approuter-based application will sit above this, taking responsibility for routing, authorization, and handling frontend UI5 assets.

saml-blog-post.drawio.png

6.1 Exposing an route to SAP Datasphere in your application

Once you complete the tutorial, which should take approximately 25 minutes, we can start making modifications to facilitate calling SAP Datasphere. For flexibility, we will expose one API designed to forward any requests to the SAP Datasphere Consumption APIs (/datapshere/*). The same logic can be applied for integrating any required business logic.

First we need to install the axios library which will be used to make request to Destination Service and SAP Datasphere

npm add --save axios

On myapp/index.js include de following code expose the SAP Datasphere route and consume Destination Service properly (For the blog, all functions have been placed in the index.js - in a productive code it could be organized properly)

...
app.get('/datasphere/*', checkReadScope, async (req, res) => {
	// Get the user token from the request
	const userToken = (req.headers["authorization"]).split(" ")[1];

	// Get the destination for calling the Datasphere API
    const datasphereToken = await findDestinationSAML(
      "Datasphere_Strakiller_2TAPI",
      userToken
    );

		const path = Object.values(req.params).join("/");
		const response = await axios({
			method: "get",
			url: `${process.env.DATASPHERE_HOST}/${path}`,
			headers: {
				Authorization: `Bearer datasphereToken.value`,
				"Content-Type": "application/json",
			},
		});

    res.status(response.status).json(response.data);
});

async function findDestinationSAML(destinationName, userToken) {
	const credentials = xsenv.cfServiceCredentials({ tag: "destination" });
  const token = await getDestinationServiceToken();

  const response = await axios({
    method: "get",
    url: `${credentials.uri}/destination-configuration/v1/destinations/${destinationName}`,
    headers: {
      Authorization: `Bearer ${token}`,
			"X-user-token": userToken,
    },
  });

  if (!response.data.authTokens || response.data.authTokens.length === 0) {
    throw new Error(`Failed to fetch destination, ${response.data}`);
  }

  return response.data.authTokens[0];
};

async function getDestinationServiceToken() {
  const credentials = xsenv.cfServiceCredentials({ tag: "destination" });

  const response = await axios({
    method: "post",
    url: `${credentials.url}/oauth/token`,
    headers: {
      Authorization: `Basic ${Buffer.from(
        `${credentials.clientid}:${credentials.clientsecret}`
      ).toString("base64")}`,
      "Content-Type": "application/x-www-form-urlencoded",
    },
    data: {
      client_id: credentials.clientid,
      grant_type: "client_credentials",
    },
  });
  if (response.status !== 200) {
    throw new Error(
      `Failed to fetch destination service access token, ${response.data}`
    );
  }
  return response.data.access_token;
};

...

On the manifest.yml file under the backend app include the destination service binding

- name: saml-blog-app
  ...
  services:
    - saml-blog-app-uaa
    - destination

Then deploy the changes running:

cf push

Through these modifications, we have established the /products/datasphere/* route in our backend application, which will forward any content provided in the "*" to the SAP Datasphere Consumption APIs. For this to function correctly, the route pattern should align exactly with the Consumption API routes as detailed in the SAP Help and SAP Business Accelerator Hub. For instance, when the route below is activated, it will list all the SAP Datasphere assets that my user account can access.

https://saml-blog-approuter.cfapps.sap.hana.ondemand.com/products/datasphere/api/v1/dwc/catalog/assets

6.2 SAP Datasphere Model for Products

The tutorial currently pulls product data from a static JSON file stored in the repository. This could be enhanced by consuming an SAP Datasphere model to deliver this information via OData APIs. As such, a View or Analytic Model containing product details could be displayed. We'll use the static JSON data to construct a comparable view within SAP Datasphere.

The Product View can be accessed by invoking the URL mentioned below. To display data from SAP Datasphere, update this URL in the UI5 code and make minor adjustments to the JSONModel.

https://saml-blog-approuter.cfapps.sap.hana.ondemand.com/products/datasphere/api/v1/dwc/consumption/...

Conclusion

In conclusion, SAP Datasphere facilitates streamlined and scalable access to business data, supporting the business data fabric architecture and promoting data openness and a freedom of choice for analytical frontend solutions. Through its use, businesses can develop customized applications tailored to fit their unique needs. This blog post provided an in-depth guide on how to set up an integration of an SAP Business Technology Platform (BTP) NodeJS application to SAP Datasphere using SAML Bearer Assertion destinations. Among the crucial steps involved in this process include configuring the identity provider, establishing trust, creating an OAuth client, setting up a destination to SAP Datasphere consumption APIs, and ultimately developing a BTP application connected to SAP Datasphere. With this setup, businesses can enhance their customer experience by uplifting their authentication methods through integrations to other applications.