Introduction

Note: This post is part of a series. For a complete overview visit the Principal Propagation in SAP Integration Suite.

This blog post explains how to propagate the identity of a principal from an app on BTP Cloud Foundry environment to SAP S/4HANA Cloud using SAP Integration Suite. This is done using OAuth 2.0 SAML Bearer Assertion flow. This OAuth 2.0 SAML Bearer Assertion flow allows to request an OAuth access token using a SAML assertion when the client needs to use a trust relationship. The SAML assertion is signed to provide authentication to the app.

The following picture depicts the scenario:

Scenario Overview

Scenario Overview:

1) Client calls the application

2) & 3) The application fetches a Json Web Token from XSUAA (SAP Authorization and Trust Management Service) for the required user

4) The application calls a proxy in SAP API Management giving the JWT as authorization header

5) & 6) The API Proxy fetches a JWT from SAP Destination Service

7) & 10) The API Proxy calls the Destination Service giving the JWT from previous step as authorization header and the JWT from step 3 as x-user-token header

8) & 9) An OAuth2SAMLBearerAssertion destination fetches a bearer token from S/4HANA Cloud using a technical user

11) The API Proxy calls the S/4HANA Cloud service

Configuration Steps:

1. Create Service Keys for XSUAA and Destination Service in Cloud Foundry
2. Download Signing Certificate of Destination Service in Cloud Foundry
3. Create communication arrangement in S/4HANA Cloud
4. Create destination for OAuth2SAMLBearerAssertion in Cloud Foundry
5. Create API Proxy in SAP API Management
6. Test scenario

Prerequisites

• You have a user JWT (JSON Web Token) in your BTP application where the call to the SAP API Management happens.
• A user exists in Cloud Foundry subaccount and in SAP S/4HANA Cloud with the same email account.

1) Create Service Keys for XSUAA and Destination Service in Cloud Foundry

In your Cloud Foundry subaccount, you need to create two instances and the respective service keys.

One is an instance and a service key for the Authorization & Trust Management service with plan Application.

Authorization and Trust Management Service Key

To avoid scope errors while fetching a token for the service key or calling the application, you need to update the service key as explained in Note 2876853.

The other needed instance and service key is for Destination Service with plan Lite.

Destination Service Key

2) Download Signing Certificate of Destination Service in Cloud Foundry

You need the certificate that will sign the saml assertions. You need this certificate while creating the communication arrangements in S/4HANA Cloud in next step. You get the certificate with the button Download Trust in the Destination section of your Cloud Foundry subaccount.

Destination Service Signing Certificate

3) Create communication arrangement in S/4HANA Cloud

You need to configure communication arrangements for your required scenarios in SAP S/4HANA Cloud. In this example we will use the Business Partner scenario.

First step needed is to create a communication user. In your S/4HANA Cloud system, under Communication Management menu point, select Maintain Communication Users and create a new user giving User Name, Description and Password.

Communication User

Next step is to create a Communication System for your Cloud Foundry subaccount. Go to Communication Management–>Communication System and click on New. As General Data give System ID and System Name. As Technical Data enter Logical System and Business System. Mark also the flag Inbound Only, as in our scenario we just want to call from Cloud Foundry to S/4HANA, not the other way around. Activate OAuth 2.0 Identity Provider and add the certificate downloaded in the previous step. As OAuth 2.0 SAML Issuer enter the CN of the uploaded certificate. As Users for Inbound Communication enter Authentication Method = User ID and Password and the communication user you created before.

Communication System

Last step is the communication arrangement. Go to Communication Management–>Communication Arrangements and create a new one. Select a scenario (for the example we select SAP_COM_0008 – Business Partner, Customer and Supplier Integration) and give an Arrangement Name. As communication data select the communication system created before. It automatically updates the Inbound Communication section. Also deactivate all the outbound services, as for our scenario we are just interested in inbound services.

Communication Arrangement

On Inbound Communication section of the arrangement click on OAuth 2.0 Details and note down this information as it will be needed to create a destination in Cloud Foundry subaccount.

OAuth 2.0 Arrangement Details

4) Create destination for OAuth2SAMLBearerAssertion in Cloud Foundry

You need to create a destination in Cloud Foundry. This destination will be called from your API proxy and will be responsible to create a SAML Bearer Assertion against S/4HANA Cloud.

OAuth2SAMLBearerAssertion Destination

You need the following information in the destination:

Parameter	Value
Name	Enter an arbitrary name
Type	HTTP
URL	Service URL of your OData service found in the communication arrangement under Inbound Services. In our example we use the Business Partner (A2X) service url
Proxy Type	Internet
Authentication	OAuth2SAMLBearerAssertion
Audience	SAML2 Audience found on OAuth 2.0 in Inbound Communication of the communication arrangement
AuthnContextClassRef	urn:oasis:names:tc:SAML:2.0:ac:classes:X509
Client Key	Client ID found on OAuth 2.0 in Inbound Communication of the communication arrangement (communication user)
Token Service URL Type	Dedicated
Token Service URL	Token Service URL found on OAuth 2.0 in Inbound Communication of the communication arrangement
Token Service User	User Name found on OAuth 2.0 in Inbound Communication of the communication arrangement (communication user)
Token Service Password	Password of the communication user
Additional Property – nameIdFormat	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Additional Property – userIdSource	email
Additional Property – x_user_token.jwks_uri	Access the following url https://<identityzone>.authentication.<xx99>.hana.ondemand.com/.well-known/openid-configuration and copy the value of jwks_uri. You find <identityzone> and <xx99> in the service key of your XSUAA instance

5) Create API Proxy in SAP API Management

Next you will need an API Proxy in SAP API Management to handle all the needed Json Web Tokens and SAML Assertions. For our example, you can search the artifact Business Partner (A2X) in package SAP S/4HANA Cloud in Discover section and copy it to your workspace. When copying it enter your S/4HANA Cloud host and port.

API Proxy

You can download the policy template PrincipalPropagationOnCF.zip from the GitHub repository Principal Propagation with SAP API Management in apibusinesshup-api-recipes and apply it to your API Proxy.

API Policies

Then go to the policies and modify as follows the script setConfigJson.js:

Parameter	Value
issuer	url of the Destination service key of your Cloud Foundry subaccount (see step 1) followed by “/oauth/token”
publicKey	verification key of the Destination service key
destinationName	Name of the destination created in the previous chapter (step 4)
destinationUri	uri of the Destination service key without “https://”
destinationAuthEndpoint	url of the Destination service key without “https://”
destinationClientId	clientid of the Destination service key
destinationClientSecret	clientsecret of the Destination service key

setConfigJson.js

6) Test the scenario

For testing the scenario use Postman or other http client. Do a Get call to the API Proxy URL. As Authorization Type use OAuth 2.0 with following values for the retrieval of the user JSON Web Token:

Parameter	Value
Grant Type	Password Credentials
Access Token URL	url of XSUAA service key (see step 1) followed by /oauth/token
Client ID	Clientid of XSUAA service key
Client Secret	Clientsecret of XSUAA service key
Username	Username of your user in Cloud Foundry
Password	Password of your user in Cloud Foundry

Http Client

Summary

In this blog post you have seen how to consume an SAP S/4HANA Cloud service using Principal Propagation via SAP Integration Suite.