What is Principal Propagation?

With Principal Propagation you have the possibility to propagate the logged in user from SAP BTP to an App, that you have created with Simplifier.

The following steps are needed to use Principal Propagation in your App:

If you want to use a Corporate Identity Provider (e.g. Microsoft EntraID) you have to establish trust between IAS and the Corporate Identity Provider
IAS (SAP Cloud Identity Services) needs to trust BTP and vice versa
You need to setup IAS as an oAuth Authentication Provider in Simplifier
Your App needs to use the LoginAction for oAuth2.0 with the new parameter UsePrincipalPropagation set to true
You need to deploy your App to BTP using the built-in deployment in the App Editor

Do I need the SAP Cloud Connector?

Depending on how Simplifier is deployed, you will need to use SAP Cloud Connector in order to utilize the Apps, which you have created with Simplifier, on SAP BTP.

If Simplifier is not publicly reachable, then you will need to use SAP Cloud Connect
If Simplifier can be accessed from anywhere on the Internet, then you will not need to use SAP Cloud Connect

See the diagram below for two examples.

This documentation handles both cases – with and without the use of SAP Cloud Connector.

If you are already using SAP BTP with IAS and a Corporate Identity Provider, you might have already established trust between SAP Cloud Identity Services and your Corporate Identity Provider (e.g. Microsoft EntraID) – please read through this chapter anyway, to be sure that everything is setup properly.

Setup Corporate Identity Provider

This documentation establishes trust between a Microsoft EntraID and SAP Cloud Identity Services. For other Corporate Identity Providers than EntraID, please consult their documentation.

In EntraID you have to add SAP Cloud Identity Services as an Enterprise Application. In SAP Cloud Identity Services you have to add EntraID as a Corporate Identity Provider. Please follow these instructions to set this up: https://learn.microsoft.com/en-us/entra/identity/saas-apps/sap-hana-cloud-platform-identity-authentication-tutorial

In order that email, name and groups of the user are transferred correctly from EntraID to BTP, we need to adapt the Claims & Attributes with these steps:

In EntraID go to your newly created Enterprise Application (e.g. named SAP Cloud Identity Services for BTP)
Choose “Manage”
Choose “Single sign-on”
Choose “SAML”
Choose “Attributes & Claims”
In the end we need the Attributes and Claims like shown in the lower screenshot
It is important that the claim names are correct (groups, email, given_name, family_name) and without a namespace (this applies for any Corporate Identity Provider – not only for EntraID)

If you are already using SAP BTP, you might have already established trust between SAP Cloud Identity Service and SAP BTP – please read through this chapter anyway, to be sure that everything is set up properly.

Setup IAS and BTP

Follow this tutorial, how trust can be established between SAP Cloud Identity Services and your SAP BTP Subaccount:
https://developers.sap.com/tutorials/abap-custom-ui-trust-cf..html

Now in SAP Cloud Identity Services you have a new application e.g. called “SAP BTP subaccout”. For this Application you have to go to “Conditional Authentication” and in the section “Default Authenticating Identity Provider” choose the formerly established Corporate Identity Provider (in our case EntraID) as Default Identity Provider.

Setup SAP Cloud Identity Service as oAuth in Simplifier

Please follow this documentation: https://community.simplifier.io/doc/installation-instructions/setup-external-identity-provider/configure-btp-identity-services-via-openid-connect/

Probably you already have a SAP Cloud Identity Services subscription, so you can skip the first step.

The next steps are:

Stay in the Simplifier Settings for Authentication and in “Mechanism settings” of “sapbtp” enable the switch for Principal Propagation
Next, we need to look up the domain name, that is used for principal propagation.
- In SAP Cloud Identity Services go to
  - Applications & Resources
  - Select the application, that has been created for the SAP BTP subaccount (something with “XSUAA_…”)
  - Select it’s “OpenID Connect Configuration”
  - As “Redirect URI” there should be something like “https://<YOUR_INSTANCE>.authentication.eu10.hana.ondemand.com/login/callback/sap.custom” and “https://<YOUR_INSTANCE>.authentication.eu10.hana.ondemand.com” is the URL we are looking for.
Now switch back to the Simplifier Settings for Authentication and in “Mechanism settings” of “sapbtp”
As “Propagation JKU” fill in: “https://<YOUR_INSTANCE>.authentication.eu10.hana.ondemand.com/token_keys”
As “Propagation Profile URL” fill in: “https://<YOUR_INSTANCE>.authentication.eu10.hana.ondemand.com/userinfo”
“Propagation Profile Path” and “Propagation Profile Verb” should stay with the defaults “/” and “GET”

Mapping User Details and Groups

Go to the subtab “User Details”
Fill in:
- First Name: “given_name”
- Last Name: “family_name”
- E-Mail Address: “email”
Go to the subtab “User Groups”
- Depending on whether the user logs into the Simplifier Admin UI via oAuth (case 1) or via a Simplifier App from BTP via Principal Propagation (case 2) the groups need to be mapped from different paths from the extracted user profile. So for each group, that we want to use in a mapping, we need to create two entries – here is one example:
- We want to map the group with the ID “123-ABC” to the “Sales” group defined in Simplifier
- Fill in the two rules for “Sales” like in the screenshot
  - for (case 1) we have the rule, that the path “groups” in the extracted profile should “contain” the group ID “123-ABC”
  - for (case 2) we have the rule, that the path “idTokenPayload/xs.system.attributes/xs.saml.groups” in the extracted profile should “contain” the group ID “123-ABC”

Create App

An App, that makes use of Principle Propagation needs to use the Login Action with the prepared oAuth Authentication Provider. Here is an example, how to do that:

You are editing your App in the Simplifier Admin UI
In the Process Designer create a story and name it “Login”
From the left icon bar pull in the shape to subscribe an event
choose e.g. “Screen Events” -> “onBeforeFirstShow” of the first screen, that appears in your app
From the left icon bar pull in the shape to “Server Action”
connect both shapes
Select again the “Login Action” shape and choose “oAuth 2.0” in the right details view
Double click the “Login Action” shape and pull in all parameters from the right
- set the “Service” to the name of the created oAuth Authentication Provider for which we have enabled Principal Propagation – in our case it’s “sapbtp”
- set “UsePrinciplePropagation” to true
- click “Apply”
You should also connect the output points of the shape “Success”, “Already logged in” and “Error” like for any other “Login Action”

Prerequisites: SAP Cloud Connector and BTP Setup

This guide assumes that you have already completed the BTP setup (Cloud Connector, destinations, Content Provider) as described in the Deploy to SAP BTP documentation. No additional Cloud Connector configuration is needed for Principal Propagation.

Deploy App to BTP

Once your app is configured with the Principal Propagation Login Action, deploy it to SAP BTP using the built-in deployment:

Open your app in the App Editor
In the toolbar, click the Deploy dropdown and select Deploy to SAP BTP
Fill out the deployment dialog (app name, subtitle, icon, group/section, roles) and click Deploy
In SAP Build Work Zone, refresh the Simplifier Content Provider in the Channel Manager to pick up the new app

For the full BTP setup (Cloud Connector, destinations, Content Provider) and deployment instructions, see: Deploy to SAP BTP