Principal propagation in a multi-cloud solution between Microsoft Azure and SAP Business Technology Platform (BTP), Part II: Connecting the system on-premise

Extending the scenario

My initial blog post on this topic described the concepts and setup for principal propagation in a pure Cloud-based scenario for a Web application and its components (a frontend and backend unit) deployed on Microsoft Azure and SAP Business Technology Platform (BTP). With BTP being a powerful platform to extending existing mission critical SAP applications running on premises, a common requirement is to extend the reach for propagating the authenticated user (principal) beyond the Cloud boundaries. In those hybrid deployment models, the user’s data is still managed by corporate systems and exposed to the Cloud by specific protocol gateways and security components to ensure the highest level of control for this access.
In this part II of the blog series, you will learn how to extend the scenario of part I and implement end-to-end principal propagation from the initial login of the user in Azure Active Directory (Azure AD) all the way to BTP and the data access in an SAP system running on premise. The following requirements will be met:

• The user is not required to authenticate twice (neither in BTP nor the SAP system on premise)
• The Azure AD user is correctly mapped to the user’s on-premise account in SAP
• Secure communication between all components to ensure the highest level of integrity, confidentiality, and accountability.

Prerequisites

Take some time to read through the first part of this blog series. It explains important concepts to understand principal propagation in a multi-cloud environment between Microsoft Azure and BTP. If you’ve already done so, the good news is: The configuration made so far in part I for Azure and BTP won’t change – everything applies in this extended scenario as well. However, you will have to install new components for this scenario – essentially everything needed to simulate the on-premise environment:

• SAP Cloud Connector (SCC): SCC will establish a secure tunnel connection between your simulated local on-premise environment (e.g. your dev machine) and the Cloud. You can download the software archive from SAP Development Tools page. I chose the Portable version for my local test environment, since it is recommended for non-productive scenarios. You will also need Java version 8 to run SCC.
• SAP NetWeaver Application Server ABAP (AS ABAP) with SAP Gateway: I chose the free developer edition for AS ABAP 7.52, SP04, which can be downloaded from here. Running my test environment on Windows 10, I installed the server on Hyper-V. Follow this blog to get very good detailed instructions for this setup. Another alternative for a local AS ABAP instance is to get the free trail from the SAP Cloud Appliance Library, which may save you some time for the setup, but comes at the costs for the Virtual Machine (VM) at your preferred and supported Cloud provider.
• OpenSSL Toolkit: You will need a corporate certificate authority (CA) in the scenario to enable SCC for principal propagation to the SAP system. OpenSSL is a great toolkit to setup a CA in a dev or test environment.

Detailed scenario walk-through

Similar to part I, a step-by-step walk-through of the scenario will help to understand all details in the process of securely propagating the authenticated user from Azure AD all the way to the RFC/BAPI call in SAP. Before we begin, let us again define our exact requirements:

• The user authenticates only once in Azure AD. Even though there are multiple hops in different environments which are traversed when accessing the data in SAP, the user must not be asked again to enter their credentials to provide the best experience.
• We ultimately rely on this initial authentication in Azure AD throughout the whole request chain to enforce the user’s authorizations in the SAP system. This requires a consistent mapping of the user’s identity in Azure AD to a user account in SAP. You will use the user’s e-mail address to associate the two accounts. It is out of scope for this tutorial to synchronize the user’s accounts in Azure AD and SAP. Identity provisioning and management software may be used for this purpose to keep user accounts up-to-date in such a distributed system setup across on-premise and different Cloud platforms.

The following solution diagram shows the extended scenario based on part I of this blog series:

Steps 1 to 6 are described in detail in part I. However, lets briefly recap what happens up to this point: The user authenticates interactively when accessing the protected Web Application frontend on Azure. This results in an OAuth access token issued by Azure AD (steps 1, 2 and 3). In step 4, Azure AD exchanges this OAuth token with a SAML assertion containing the user’s attributes and unique identifier, using the On-Behalf-Of (OBO) flow in Azure AD. This SAML assertion is used as an interoperable user credential in step 5 to initiate another token exchange, now across different Cloud platforms, following the international standard RFC 7522. Step 5 reverses the previous exchange by sending the SAML assertion to the OAuth authorization server in BTP, and getting back a new OAuth access token, now issued by BTP. This is used in step 6 to call the Web Service in BTP with the original user. So far, we achieved principal propagation across Azure and BTP. But what if we want to propagate the user even further down to the SAP system in the corporate network, because we have to display data for the user from this system in the Web Application frontend in Azure? Here is how this can be achieved:

7. The BTP Web Service uses the SAP Cloud SDK which simplifies the OData call to the SAP system. It basically reduces the effort for the developer to a single API call as outlined by the following code excerpt from the code repository:

   ODataQueryResult result = ODataQueryBuilder                        
     .withEntity("/sap/opu/odata/SAP/ZAZURESAP_PP_SRV", "SalesOrderSet")                        
     .withoutMetadata()
     .build()
     .execute(DESTINATION_NAME);

   The string constant DESTINATION_NAME refers to the name of a destination defined in the BTP account. This HTTP destination is configured for a URL exposed by the SAP Cloud Connector and uses the authentication type Principal Propagation. You will configure the destination following the steps in this tutorial.

8. With this destination, the Cloud Connector receives a JSON Web Token (JWT) generated for the authenticated (propagated) user in BTP, extracts the attributes, and uses its Security Token Service (STS) component to issue a new token. With this third (!) token exchange in the end-to-end process, the user’s identity is converted into a short-lived X.509 certificate, containing the unique user’s identifier in the certificate’s common name (CN) to assert the identity to the SAP Gateway system. Using X.509 as the preferred token format for the “last mile” ensures maximum interoperability for propagating the principal even to older SAP releases. By setting up a mapping rule in the SAP system, the asserted identity in the X.509 client certificate is used to logon an existing user in the SAP system and finally execute the OData service implementation in the context of the mapped user.

In total, we now count three token conversions in the extended scenario to securely propagate the authenticated user (principal) across both Clouds and the on-premise system.

X.509 certificate management

The final token exchange from JWT to an X.509 certificate for the user requires the STS in SCC to generate new client certificates based on the information found in the JWT tokens of incoming requests from BTP using destinations with authentication type Principal Propagation. Generating new certificates and managing their lifecycle is typically delegated to a Certificate Authority (CA), either internally or externally. In your test setup, you will install your own, internal corporate root CA using the OpenSSL toolset. The root CA serves as the trust anchor in the chain of trust and issues a so-called intermediate CA certificate (signed by the root CA private key) to SCC for the purpose of issuing short-lived client certificates for propagated users. This follows best practices in certificate management.

User mapping

One last word on this important and non-trivial topic: User mapping! In many federation scenarios like this, where user accounts are managed in the different user stores, the unique identifiers of the user accounts may be different and have to be mapped to each other. Let’s take the example from this scenario:

• The user authenticates with Azure AD. Here, the user’s principal name is set the user’s login name, followed by the Azure AD tenant’s primary domain, for example jdoe@contoso.onmicrosoft.com. Most likely, this user name is not known to an SAP system. Therefore, a mapping to the user’s email address (e.g. jdoe@contoso.com) registered in Azure AD has been configured in step 31 of part I, when you set the SAML configuration for the enterprise app registration. You could have also set the subject name identifier (NameID) in the Azure AD-generated SAML assertion to any other value found in the directory. If there were something like an “SAP ID” (e.g. “JDOE“, which many customers maintain in their AD), you could have mapped it to the NameID, and carry this identfier all the way to the SAP system for login.
• Now, with the user’s email address chosen as the unique identifier for this scenario (which is also a good practice), the next user mapping in the scenario happens in the SAP system using the certificate mapping rules (you will see the details below when configuring the scenario). BTP just passes the propagated user through the SAP Cloud Connector to SAP, where the incoming email address is used to uniquely identify and logon an existing user in SAP. For example, if the SAP user with login name JDOE has an email address set to jdoe@contoso.com, JDOE will be logged on.

Besides those two places for configuring user mapping (i.e. Azure AD enterprise app SAML configuration & SAP certificate mapping rules), it is worth mentioning that SAP Cloud Connector is also able to set the Common Name (CN) in the generated certificate to other identity data than the users logon name (here again the email address since BTP won’t change it) found in the incoming (JSON Web) token from BTP. However, the before mentioned capabilities in Azure AD and SAP (Cert rule mappings) are much more flexible and therefore recommended for user mapping. Ideally, you have a central identity management system in place which takes care for keeping identity data in sync across two or more user directories.

Extended scenario setup

As already mentioned above, no changes to the initial setup are required in Azure AD and BTP. This applies to the following configurations already made in part I:

• The application registrations and trust setup to BTP in Azure AD
• The role collection configuration and trust setup to Azure AD in BTP

Due to the propagation of the Azure AD-authenticated user to the SAP system, the Web Service application running in BTP must be updated for making the OData call. In addition, the extended scenario requires the following configuration steps:

1. Setup of the corporate root CA with the OpenSSL toolkit to generate the root CA key pair and certificate, which is used to generate the intermediate CA key pair and certificate for SCC.
2. With the intermediate CA key and certificate, SCC can be configured for principal propagation to the SAP system. This also includes registration of the SAP system in SCC and definition of the access rules from the Cloud to it.
3. Configure trust to SCC in SAP Gateway and expose a simple OData service. To prove that the Azure AD-authenticated user is successfully propagated all the way to the OData service implementation, you will add a response header in the service implementation which sends back the currently logged on user in SAP.
4. Finally, you will update the Web Service implementation in BTP to add the OData service call via SCC. This also includes configuration of the HTTP destination in your BTP subaccount.

You should also checkout the part2 branch of the code repository from GitHub with the following commands:

git clone https://github.com/raepple/azure-scp-principal-propagation.git
cd azure-scp-principal-propagation
git checkout part2

Ready? So let’s get started!

Corporate Root CA setup

Step	Description	Screenshot
1	Open a command line and change to the directory of your OpenSSL installation. Create a new subdirectory with name trustedca.
2	Change to the new subdirectory and create the following subdirectories: certs, private, crl and csr
3	Copy the corporate root CA configuration file trustedca.cnf from the code repository to the trustedca directory. Next, generate the root CA signing key with the command openssl genrsa -aes256 -out trustedca.key 4096 You will be asked twice to provide and confirm a pass phrase for the generated private key.
4	Generate the self-signed CA root certificate with the command openssl req -key trustedca.key -new -x509 -days 7300 -sha256 -extensions v3_ca -out trustedca.crt Below are suggested values for the new certificate’s Distinguished Name (DN): Country Name:DE State or Province Name (full name):BW Locality Name (eg, city): <leave blank> Organization Name (eg, company):Contoso Ltd Organizational Unit Name (eg, section):Trusted CA Common Name:Trusted CA Email Address: <leave blank>
5	Create a few files needed by your new corporate root CA to manage the issuance of new certificates: copy NUL index echo 1000 > serial echo 1000 > crlnumber
6	You are now ready to generate the intermediate CA key pair and certificate for SCC with the command openssl genrsa -aes256 -out private\scc.key 2048
7	The intermediate CA certificate for SCC must be signed by your new root CA. Therefore you create a Certificate Signing Request (CSR) with the following command: openssl req -key private\scc.key -new -sha256 -out csr\scc.csr Below are suggested values for the new certificate’s Distinguished Name (DN): Country Name:DE State or Province Name (full name):BW Locality Name (eg, city): <leave blank> Organization Name (eg, company):Contoso Ltd Organizational Unit Name (eg, section):SCC Common Name:SCC Email Address: <leave blank> You can leave the ‘extra’ attributes for the certificate request blank: A challenge password: <leave blank> An optional company name: <leave blank>
8	Sign the SCC intermediate CA certificate request with your root CA key using the command openssl ca -batch -config trustedca.cnf -notext -in csr/scc.csr -out certs/scc.crt
9	For later upload to SCC, convert the intermediate CA key pair and certificate into a PKCS12-formatted file with the command openssl pkcs12 -export -clcerts -in certs/scc.crt -inkey private/scc.key -out certs/scc.p12 Remember the export password for the file. You will need it later when you import the key pair in SCC.

Configure SAP Cloud Connector (SCC)

Step	Description	Screenshot
10	Start your SCC instance by launching go.bat (on Windows) from the installation directory. Login to your SCC instance (https://localhost:8443 if you run it on your local machine). If you have a new installation, the userAdministrator has the initial password manage, and you have to change it upon first login. You may also see a warning in your browser saying the the connection is not trustworthy (due to a mismatch of the CN name in the SSL certificate), but can safely ignore it.
11	Enter the connection parameters for your BTP subaccount. In my case, I’ve connected SCC to my BTP trial subaccount on the us10 landscape. Make sure you select the correct region and ID for your subaccount. The ID can be obtained from SAP Cloud Platform Cockpit when you enter your subaccount and click on the Information symbol of the subaccount tile.
12	Import the intermediate CA certificate as you new system certficate by selecting Configuration from the left-side navigation menu. Select the tab On Premise and click on the Import button to install the new System Certificate. Choose P12 Certificate for the Certificate Type, select the file scc.p12 from the certs subfolder of your OpenSSL root CA directory, and enter the export password. Click Import.
13	Scroll down on the Configuration screen to the CA Certificate section. Again, click on the Import button, select the scc.p12 file, and import it.
14	Next, select the Cloud To On-Premise settings of your subaccount from the navigation menu, stay on the Access Control tab, and click on Add (“+”).
15	Click through the wizard with the following selections: Backend Type: SAP Gateway Protocol: HTTPS Internal Host: <Hostname of your SAP Gateway system> Internal Port: <SSL Port of your SAP Gateway system, e.g. 44300> Virtual Host: Choose the proposed value Virtual Port: Choose the proposed value Principal Type: X.509 Certificate (General Usage) Host in Request Header: Use Virtual Host Description: Can be left empty Check Internal Host: Activate the checkbox Click Finish. You should see a new entry in the table for your SAP Gateway system. Verify that the Check Result shows Reachable. In the Resources table, click on Add (“+”).
16	For the sake of simplicity you will allow the root path (“/“) with subpaths to be accessed from the Cloud. In a production environment you would restrict the access to resources to only a subset, e.g. /sap/opu/odata). Click Save.
17	Select the tab Principal Propagation and click on the Synchronize button to import the trust configuration for the JWT signing key from your BTP subaccount.
18	For a quick test of the principal propagation settings in the next section, go back to the Configuration settings in the main navigation menu. Select the On Premise tab and scroll down to the Principal Propagation settings. Click on the Create a sample certificate button. For the CN name, enter the e-mail address of your test user. Click Generate. Remember the folder where the generated file scc_sample_cert.der is downloaded. You will need this file to create the user mapping rule in the next section.

Configure trust and user mapping in SAP Gateway

Step	Description	Screenshot
19	Login to the SAP Gateway system with SAP GUI and start transaction STRUST. Select SSL Server Standard from the PSE list. Click on the button Import certificate. In the file dialog window, select the trustedca.crt root CA certificate from the trustedca subdirectory of your OpenSSL installation. Click Enter, and then Add to Certificate List. Repeat this step to import the SCC intermediate CA certificate by clicking on the Import certificate button again. Now select the scc.crt file from the trustedca\certs subdirectoy of your OpenSSL installation. Click Enter and then Add to Certificate List.
20	The certificate list of the SSL Server Standard PSE now contains the two certificates (root and intermediate) of the corporate CA. Click Save.
21	Verify and maintain the required SSL profile parameters for principal propagation by starting transaction RZ11. Enter the Parameter Name icm/HTTPS/verify_client an click Display. This parameter specifies whether or not a client (here SCC) must send a certificate.
22	Check that the Current Value is set to 1. Otherwise, click on the Change Value button and set it to 1. With the value set to 1, the server asks the client to transfer a certificate. If the client does not send a certificate, authentication is carried out by another method, for example, basic authentication. Next, go to the profile parameter management with transaction code RZ10
23	Select the instance profile with name <SID>_<Instance-Name>_<Hostname>, e.g. NPL_D00_VHCALNPLCI in my case, from the Profile list, choose Extended maintenance, and click on the Change button.
24	Add the following new parameter to the instance profile by clicking on the Create Parameter (F5) button. Parameter name: icm/HTTPS/trust_client_with_issuer Parameter value: CN=Trusted CA, OU=Trusted CA, O=Contoso Ltd, SP=BW, C=DE This parameter controls the trust relationship between SCC and the Internet Communication Manager (ICM) to accept X.509 client certificates issued by the corporate Root CA. Note: The parameter value depends on the input for the DN in step 4. It may be different in your case if you chose other values. I’d recommend to copy & paste the value from the Configuration screen in SCC. Important: Before saving the new parameter, change the “ST” element of the DN into “SP”. Click on Copy, then Back (F3).
25	Add another new parameter to the instance profile by clicking on the Create Parameter (F5) button. This parameter controls the trust relationship between SCC and the Internet Communication Manager (ICM) to accept X.509 client certificates issued to SCC. Parameter name: icm/HTTPS/trust_client_with_subject Parameter value: OU=SCC, O=Contoso Ltd, C=DE, SP=BW, CN=SCC Note: The parameter value depends on the input for the DN in step 7. It may be different in your case if you chose other values. I’d recommend to copy & paste the value from the Configuration screen in SCC. Important: Before saving the new parameter, change the “ST” element of the DN into “SP”. Click on Copy, then Back (F3).
26	Add another new parameter to the instance profile by clicking on the Create Parameter (F5) button. This parameter controls how the CN name in the incoming client certificates generated by SCC are mapped to users in your SAP system. Parameter name: login/certificate_mapping_rulebased Parameter value: 1 Click on Copy, then Back (F3).
27	Finally, check that the new parameters were added to your instance profile. Click the Change/Display button and confirm to save the changes to the profile. Click Back (F3).
28	Click Save to activate the profile changes. Note: You can ignore any warnings or consistency checks when saving and activating the new profile changes. At this time, you may want to restart your SAP instance to make the changes effective.
29	Login to your SAP instance again and configure the rule based certificate mapping with transaction code CERTRULE. Switch to the edit mode by clicking on the Display/Change button. Then click on the Import certificate button to upload the generated client certificate from step 18 (scc_sample_cert.der) . Add a new mapping rule for this certificate by clicking on the Rule button.
30	In the dialog window, select the proposed value for the Certificate Attr. field. To successfully map the user’s ID from the Common Name (CN) in the certificate, which is the user’s email address, select for Login As the value E-Mail. Click Continue (Enter).
31	Click Save (Ctrl + S). You should see on the right side that the certificate could be successfully mapped based on the new rule, and that a user with the email exists. If this is not the case, check with transaction SU01 that a user with the E-Mail address from the certificate exists.

SAP Gateway OData Service deployment

Step	Description	Screenshot
32	Start the Gateway Service Builder by running transaction SEGW and create a new project (Ctrl + F5). Enter the following Project: ZAZURE_SAP_PP Description: Principal Propagation Test Service Service Package: $TMP Click Continue (Enter).
33	On the new project, right-click on Data Model and select Import -> DDIC Structure.
34	In the first step of the import wizard, enter SalesOrder for the new Entity Type Name, and import the ABAP Structure SEPM_ISOE. Click Next.
35	Select the all parameters from the DDIC structure except MANDT. Click Next.
36	Select SALESORDER as the key element for your new data model by activating the Is Key checkbox. Click Finish.
37	The new Entity Types and Entity Sets have been created. Click Save. Next, select Project -> Generate or press Crtl+F3. In the new dialog window, leave all proposed default values unchanged for the runtime objects and click Continue (Enter).
38	Select Local Object in the Create Object Directory Entry dialog. You should see a message saying Runtime objects generated.
39	Expand the subfolder Service Maintenance on your new project, select the item GW_HUB, right-click on it, and choose Register from the context menu.
40	In the Add Service dialog, leave all default values. Click on Local Object to set the Package Assignment to $TMP. Activate the checkbox Enable OAuth for Service. Click Continue (Enter).
41	Double-click on the GW_HUB item again to check that the Registration Status turned to green.
42	Now you need to implement the service method(s) fot the generated stubs. Open the subfolder Service Implementation, select the SalesOrderSet item, and right-click on the GetEntitySet (Query) method. From the context menu, select Go to ABAP Workbench. Confirm with Yes to save the changes, and click on Continue (Enter) on the Information popup.
43	In ABAP Workbench, press Ctrl + F1 or the Display/Change button.
44	Select the method SALESORDERSET_GET_ENTITYSET from the subfolder Methods -> Inherited Methods. Right-click on it and choose Redefine from the context menu.
45	Replace the code of the SALESORDERSET_GET_ENTITYSET method with the code from the GitHub repository. You can find it here. The code adds an HTTP response header with name “current_user” which contains the currently logged in users name when the method is executed. You will inspect this header later during the scenario test to verify that the user from Azure AD has been propagated correctly. Click Save (Ctrl + S), then Activate (Ctrl + F3). Confirm the object activation popup dialog with Continue (Enter).

BTP Web Service update and HTTP destination configuration

This step assumes that you’ve alread deployed the service as described in part I of this blog series. In this step you will only update the existing deployment of the service, i.e. you won’t create the XSUAA service binding again or define the role collection. If you haven’t done so yet, go to the first part of this blog and execute the steps in the sections Deployment of the backend service and Configure authorizations for the backend service in BTP.

Step	Description	Screenshot
46	Open a command line and change to the directory where you cloned the GitHub repository. Make sure that your are on the part2 branch by entering the command git status.
47	Change to the SCP\service subfolder. Edit the file manifest.yml and replace the string <your-trial-org-name> with the value of your BTP trial subaccount’s org name, e.g. 98abcd76trial Replace the string <your-trial-org-landscape> with the value of your BTP trial subaccount’s landscape, e.g. eu10or us10 This ensures a unique route to the service in the (trial) landscape.
48	Create the service binding for the destination service with the command cf create-service destination lite service-destination
49	Create the service binding for the connectivity service with the command cf create-service connectivity lite service-connectivity
50	Build the BTP Web Service with the command mvn clean package. You should see a message saying the build succeeded.
51	Login to your BTP subaccount. In the following steps we’ll use a trial account on the EU10 landscape with the command cf login -a https://api.cf.eu10.hana.ondemand.com
52	Deploy the BTP Web Service with the command cf push You should see a message that the state of your service is running.
53	Open the BTP Cockpit in your browser and login with your account admin. Navigate to your trial account and select Connectivity –  Destinations from the left side navigation menu. Click New Destination.
54	Enter the following configuration values: Name: npl_http Type: HTTP URL: The virtual host and port from step 15, e.g. http://vhcalnplci:44300 Proxy Type: OnPremise Authentication: Principal Propagation Click Save. Note: The destination name is hardcoded in the Web Service implementation. If you change the name here you also have to change in the code.

Testing the scenario

...
SAP Gateway OData Service Response Code: 200
OData Service executed for SAP user: [JDOE]