Introduction

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

This blog post covers the use case of an external system communicating with SAP S/4HANA Cloud using Principal Propagation via Integration Suite, so forwarding the identity of a user across several systems including mediation. This is done using OAuth 2.0 SAML Bearer Assertion flows.

Depending on the authentication method between the external system and Integration Suite, the complexity of the scenario can increase.

If basic authentication is used, then there is an identity in the Cloud Foundry subaccount, that can be propagated just using Cloud Integration. In that case, the below configuration steps 1, 5 & 6 are not needed. See how to set up basic authentication with user instead of service keys in Cloud Foundry in the blogposts Basic Authentication for Cloud Integration in Cloud Foundry Environment and Enable SAP IAS as Custom IdP for Basic Inbound Authentication in Cloud Foundry Environment.

If OAuth 2.0 is used as authentication method, then you can use the grant type Password while retrieving the token in the client to have an identity or user in Cloud Integration subaccount, which can be propagated using just the Cloud Integration adapters.

If client certificate is used as authentication method, then you can use SAP API Management to extract the identity from the client certificate and to initiate an OAuth2SAMLBearer grant flow. SAP API Management as a trusted issuer, will generate a SAML artefact and exchange it with BTP’s SAP Authorization & Trust Management Service for a Json Web Token that is presented to Cloud Integration.

Once you have an identity in Cloud Foundry, independently of the authentication method (basic auth./OAuth 2.0/client certificate), then you can use Cloud Integration to generate a SAML assertion against SAP S/4HANA Cloud. Prerequisite is that a user exists in both systems – Cloud Foundry subaccount and SAP S/4HANA Cloud – with the same e-mail account.

The following picture depicts the scenario using client certificate (with other authentication methods steps 1-5 are not needed as API Management is not involved and the call is done directly to Cloud Integration):

Scenario Overview

Scenario overview:

1. Client calls SAP API Management endpoint with client certificate authentication
2. SAP API Management validates client certificate and extracts subject (CN & email)
3. SAP API Management as trusted custom IdP generates and signs a SAML assertion
4. SAP API Management fetches client credentials and roles from Cloud Integration Service
5. SAP API Management exchanges SAML token, client credentials, roles and email (those two as OAuth scopes) for an OAuth Bearer token from SAP Authorization & Trust Management service (XSUAA)
6. SAP API Management initiates Inbound Authentication for Cloud Integration
7. The receiver adapter in Cloud Integration is configured to use OAuth2 SAML Bearer Assertion, which fetches a bearer token from S/4HANA Cloud
8. The S/4HANA Cloud service is called matching the user with email

Prerequisites

• A user must exist in S/4HANA Cloud with the same email as the propagated user in Cloud Foundry subaccount for basic authentication or OAuth 2.0 or with the same email as in the subject of the private certificate for client certificate authentication.
• You need an instance and a service key for the service Process Integration Runtime with integration-flow plan

Configuration

The configuration steps for this scenario are:

1. Setup API Management as a trusted Identity Provider
2. Download Signing Certificate of Destination Service in subaccount
3. Create communication arrangement in S/4HANA Cloud
4. Create your integration flow in Cloud Integration
5. Enable two-way SSL in API Management
6. Create the API Proxy in API Management
7. Test your scenario

1) Setup API Management as a trusted Identity Provider

In this step you will need to trust a new custom Identity Provider in your BTP subaccount, so that API Management can have a trusted relationship with XSUAA to enable SAML2Bearer grant flow.

In this blog post you can see how to generate the certificates for signing the SAML Assertions (see the chapters “Generate Certificate for Signing SAML Assertion” and “Generate JAR containing Certificate”) and how to obtain the SAML Metadata for the new Identity Provider (see the chapter “Generate SAML IdP Metadata”). After generating the certificate, you should have the following files (certificate, key and keystore):

Identity Provider Signing Certificates

As explained in the same blog post, you can use a tool like https://www.samltool.com/idp_metadata.php to generate the metadata for your new custom Identity Provider. Give an EntityId (apim.proxy.idp in the example), an Http redirect url (not relevant) and as SP X.509 cert paste the content of the cert.pem generated in the previous step.

Identity Provider Metadata

Next step is trusting the new Identity Provider in your subaccount. Go to Security–>Trust Configuration and upload a New Trust Configuration.

Trusting Identity Provider

Select the Metadata XML file generated in the previous step and provide a name for the Identity Provider (apim.proxy.idp in the example). You probably would like to disable the flag Available for User Logon, so that you keep on using the default Identity Provider to access the Cloud Integration WebUI. The flag Create Shadow Users on User Logon allows you to automatically create a user in this Identity Provider when a request arrives, otherwise the user must exist in this Identity Provider before doing the call or you’ll receive a 401 Unauthorized error.

Identity Provider Trust Configuration

Next step is to create or reuse an existing role collection with the MessagingSend role assigned to it to allow the generated JWT to execute the integration flows. If you have configured your integration flows to use a different role, then this different role must be assigned to the role collection.

Role Collection

In the new custom Identity Provider map the attribute group given when generating the SAML artefact to the above-mentioned role collection. In this example, the attribute group is called “it-rt-….ESBMessaging.send” and will be configured in the API policy in step 6 – Create the API Proxy in API ManagementàsamlHelper.jsàAttributeValue.

Attribute Mapping in Identity Provider

As said before, if you do not allow shadowing users, then the needed user must be created manually for the new Identity Provider in the BTP cockpit. The user does not need any role as it will be given while generating the SAML assertion. In this example I will use the common name of the client certificate as username.

User in Custom Identity Provider

2) Download Signing Certificate of Destination Service in subaccount

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

Destination Service Certificate

You need this certificate in next step.

3) Create communication arrangement in S/4HANA Cloud

You need to configure communication arrangements for your required scenarios. 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 want just 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 click on OAuth 2.0 Details and note down this information as it will be needed to create a OAuth2 SAML Bearer Assertion security artifact in Cloud Integration.

OAuth 2.0 Details

4) Create your integration flow in Cloud Integration

In Cloud Integration add a new security artifact.

OAuth2 SAML Bearer Assertion Artifact

Enter the following values in the artifact:

Parameter	Value
Name	Enter an arbitrary name
Grant Type	OAuth2SAMLBearerAssertion
Audience	SAML2 Audience found on OAuth 2.0 Details in Inbound Communication of the communication arrangement
Client Key	Client ID found on OAuth 2.0 Details in Inbound Communication of the communication arrangement (communication user)
Token Service URL	Token Service URL found on OAuth 2.0 Details in Inbound Communication of the communication arrangement
Target System Type	SAP BTP (Neo)
Token Service User	User Name found on OAuth 2.0 Details in Inbound Communication of the communication arrangement (communication user)
Token Service Password	Password of the communication user
Include Scope	True
Scope	Scopes found on OAuth 2.0 Details in Inbound Communication of the communication arrangement (Scope assignment)
Additional Property – userIdSource	email
Additional Property – nameIdFormat	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
AuthnContextClassRef	urn:oasis:names:tc:SAML:2.0:ac:classes:X509

Here is an example of a simple integration flow. Important is to select OAuth2 SAML Bearer Assertion as authentication method and give the credential name of the security artifact just created.

Integration Flow

5) Enable two-way SSL in API Management

As we do not call the integration flow directly, but through API Management, we need to configure it.

To enable inbound client certificate authentication and extract properties from the certificate in API Management you must request Two-Way SSL certificate. See Enable Client Certificate Authentication on API Proxies to know how the process works.

Per default, the virtual host of your API Management is secured with a one-way SSL certificate. That means, that the sender does not use client certificates. If two-way SSL certificate is used, then all the API proxies called through this virtual host will need a client certificate, otherwise they will not work anymore. A best practice for this is to request an additional virtual host and use this virtual host just for those API Proxies requesting client certificates. Doing this, all the remaining API proxies will still work the old way.

6) Create the API Proxy in API Management

Create a key store in API Management with the jar file created in step 1 (Setup API Management as a trusted Identity Provider–>Generate certificate for signing SAML assertions) to sign the SAML assertion to be exchanged with the BTP’s XSUAA.

Key Store for Signing SAML Assertions

Create the API proxy pointing to your integration flow. It is important not to use an API Provider with credentials defined, otherwise it uses those credentials to access the Cloud Integration instead of the generated token. Use a URL instead as provider.

API Proxy

Search for the policy template “Connect to SAP Cloud Foundry services”–>“SAP Cloud Foundry SAML2OAuth Flow” on SAP API Business Hub and apply it to your API proxy.

In the samlHelper.js in the policies enter the following info:

• Variable sapapim.issuer: origin key of the custom identity provider created in step 1 (Setup API Management as a trusted Identity Provider–>New Trust Configuration)
• Variable sapapim.audience: download SAML Metadata of your subaccount from BTP Cockpit–>Trust Configuration and take entityId
• Variable sapapim.recipient: also from SAML Metadata, take the AssertionConsumerService Location (…/oauth/token/alias…)
• Variable sapapim.username: context.getVariable(“client.cn”) to get the common name of the client certificate making the request
• Variable sapapim.storename: store name used to sign the SAML assertions to be exchanged with XSUAA
• Variable sapapim.keyname: name of the key used to sign the SAML assertions
• Variable sapapim.clientId: client id of the Process Integration Runtime (integration-flow plan) service key with the ESBMessaging.send role assigned
• Variable sapapim.secret: client secret of the Process Integration Runtime (integration-flow plan) service key with the ESBMessaging.send role assigned
• AttributeValue: attribute Name=”Groups” mapped to the role collection used in step 1 for sending messages to Cloud Integration (ApplicationIdentifier.RoleName)
• AttributeValue: attribute Name=”mail” mapped to getVariable(“client.email.address”) to get the e-mail of the client certificate making the request

API Policies

The Process Integration Runtime instance for the service key used above must have following configuration:

Process Integration Runtime Instance

In the policy getOAuthToken enter as HTTPTargetConnection the value of AssertionConsumerService Location found on the file downloaded from the BTP Cockpit–>Trust Configuration–>SAML Metadata.

API Policies

Once you save and deploy the API proxy you can debug it and obtain the generated JWT token.

SAP API Management Debugging

7) Test the scenario

Configure your sending system or client for using client certificate authentication. In postman it is done going to File–>Settings–>Certificates and assign your certificate to the API Proxy endpoint.

Configure Client Certificate in Postman

Then simply make a call to the API Proxy. You should obtain the result of the S/4HANA Cloud service.

Client Call

Summary

In this blog post you have seen how to consume a S/4HANA Cloud service using Principal Propagation via SAP Integration Suite (SAP API Management & Cloud Integration). The blog post describes all the steps needed in case of using client certificate authentication in client application using both SAP API Management and Cloud Integration. In case of using basic authentication or OAuth 2.0, SAP API Management is not needed, thus steps 1 to 5 can be skipped.