Implementing SAP Marketing Forms using the SAP Web Dispatcher

[steffens]

Warning

Modern web browsers introduced new security measures to improve the secure handling of cookies, e.g. SameSite cookies or cross-site tracking prevention.

These measures may deny cookies for cross-domain requests. However, the following setup makes use of cross-domain requests and cookies to keep a session alive. This doesn't work anymore with these modern web browsers.

Please see the following blog post for more details regarding the SameSite cookies and options to configure your SAP Web Dispatcher accordingly: https://blogs.sap.com/2020/02/14/handling-google-chrome-samesite-cookie-change-in-sap-on-prem-applic...

Alternatively, you can implement the same setup using a reverse proxy on your own web server instead of the SAP Web Dispatcher so that the communication is not cross-domain. This reverse proxy configuration could either just point to the web dispatcher which is configured as below or replace its configuration by applying the same settings as part of the proxy so that you don't have to configure the web dispatcher at all.

Introduction

SAP Marketing offers an easy to use editor to design and configure web forms. These forms are hosted on the customer web server to allow custom integrations into existing web sites and technologies.

The forms provide built-in functionality to send and receive the required data to and from the SAP Marketing system. To make this scenario work, you have to integrate the form on the web server with the SAP system.

While the SAP Marketing Installation Guide covers an example implementation using a PHP snippet, it’s also possible to configure the SAP Web Dispatcher in a way that allows easy integration without additional implementation effort. This guide describes the required steps.

You need to have basic knowledge about the SAP Web Dispatcher and its configuration to follow this guide. Furthermore you need to have access to the SAP Web Dispatcher directory and the profile file in order to perform the necessary changes.

Intended System Setup

The form itself has to be hosted using a customer web server and runs inside the user’s web browser client. The SAP Web Dispatcher acts as an interface (proxy) to access the SAP Marketing server.

The intended setup consists of a direct communication between the form and the SAP Web Dispatcher without any additional implementation to connect the two components. To make this communication possible, the Web Dispatcher needs to be configured to allow the anonymous HTTPS requests from the customer web server domain on which the form (HTML, CSS and JS files) is hosted.

The cookies sent by the SAP Marketing system are marked as secure which means that the web browser will only handle them if the form is using HTTPS. This means that the web server needs to use HTTPS to use this approach.



The described configuration can be performed once without additional effort for forms created afterwards.

Adding a Modification Handler for the Form Result Service

The SAP Web Dispatcher allows the modification of HTTP requests based on user-defined conditions.

To separate these modifications from the standard configuration you can define a dedicated modification handler file in your SAP Web Dispatcher profile as follows:

# Form Result Service Modification Handler

icm/HTTP/mod_1 = PREFIX=/sap/opu/odata/sap/CUAN_CONTENT_PAGE_RESULT_SRV, FILE=$(DIR_INSTALL)/profile/CUAN_CONTENT_PAGE_RESULT_SRV.txt

The above statement uses the profile parameter “icm/HTTP/mod_<xx>” for requests matching the given prefix “/sap/opu/odata/sap/CUAN_CONTENT_PAGE_RESULT_SRV” to define a modification handler file “CUAN_CONTENT_PAGE_RESULT_SRV.txt” inside the profile folder. The name and the location of the handler file can be chosen as desired. If there is already a modification handler in place, you have to increase the profile parameter index (“mod_<xx>”) accordingly.

Following this, you have to create the modification handler file as defined in the profile parameter. Simply create an empty text file that contains the configuration statements described in the following sections.

After setting up the profile parameter and the handler file, you have to restart the SAP Web Dispatcher instance. Afterwards you can check and reload the Modification Handler in the Web Administration Interface.

Preparing the Authentication with a Technical User

The form result OData service requires a backend user with the relevant role. The Installation Guide covers the creation of the user in the section “System User Authentication”.

In order to allow forms to call the service as an anonymous web user, the SAP Web Dispatcher needs to forward the HTTP requests with the proper user authorization. This guide uses Basic HTTP Authentication for this purpose.

Provide the necessary “Authorization” HTTP request header as follows:

# Authorization

SetHeader Authorization "Basic <Base64Encoded-Username:Password>"

You have to maintain the value of the header with a Base64 encoded string of “Username:Password” where “Username” is replaced by the name of the according technical user and “Password” is replaced by the user’s password while keeping the as the separator. You can find several online services by searching for “base 64 encode”.

Assuming the user name “TECHUSER” and the password “Secret123” you would have to encode the text “TECHUSER:Secret123” in Base64. The complete header value would then be “Basic VEVDSFVTRVI6U2VjcmV0MTIz”. The SAP system then uses this “Authorization” header to process the HTTP requests as the given user.

Please note that the Base64 encoding is not an encryption. Anyone with access to the SAP Web Dispatcher is able to read the encoded value and decode it to receive the user name and password combination. Thus it makes sense to create a “System” user that only has the landing page result role assigned in order to prevent abuse of it.

Enabling Cross-Origin-Resource-Sharing

Using the SAP Web Dispatcher directly for the form integration usually implies that the HTTP requests are being sent to a different domain. While the landing page HTML is hosted on the website’s domain, the Web Dispatcher runs on an own domain. This setup requires some additional preparation because modern web browsers implement security mechanism to prevent illegal requests.

The server providing the web service (here: form result OData service) has to set specific HTTP response headers that define from which domains the service can be called. The web browser then checks these header values before sending HTTP requests. This system is called Cross-Origin-Resource-Sharing (CORS). If your setup doesn’t require CORS you can skip this section.

Form requests require the following CORS HTTP headers:

• “Access-Control-Allow-Origin”
  
  
  
  • Defines the allowed domain from which the service can be called
  
  
  
  


• “Access-Control-Allow-Methods”
  
  
  
  • Defines the allowed HTTP methods
  
  
  
  


• “Access-Control-Allow-Credentials”
  
  
  
  • Enables the use of cookies which is necessary to satisfy the SAP Gateway OData protocol
  
  
  
  


• “Access-Control-Allow-Headers”
  
  
  
  • Defines the list of allowed HTTP headers that can be send via requests
  
  
  
  


• “Access-Control-Expose-Headers”
  
  
  
  • Defines the list of allowed HTTP headers that can be read from responses
  
  
  
  

You can set these HTTP response headers in the modification handler file as follows:

# CORS Enablement

SetResponseHeader Access-Control-Allow-Origin "https://<Form-Domain>/"

SetResponseHeader Access-Control-Allow-Methods "OPTIONS, HEAD, GET, POST"

SetResponseHeader Access-Control-Allow-Credentials "true"

SetResponseHeader Access-Control-Allow-Headers "Content-Type, X-CSRF-Token"

SetResponseHeader Access-Control-Expose-Headers "X-CSRF-Token"

Replace the value of the “Access-Control-Allow-Origin” header with the domain used for your web site hosting the landing page (e.g. “https://www.mymarketingform.com/”).

Preparing CORS Preflight Requests

Modern web browsers send additional preflight HTTP OPTIONS requests for CORS requests to check for the required HTTP headers.

At present, the SAP NetWeaver OData Gateway doesn’t support  requests which use the “OPTIONS” method. Because of this it’s necessary to work around the missing functionality of the OData service by re-writing the OPTIONS requests to another path that supports the HTTP method. This approach does not lead to functionality or security limitations.

You can re-write the OPTIONS requests onto the “/sap/public/ping” service by adding the following to your modification handler file:

# OPTIONS Workaround

If %{REQUEST_METHOD} stricmp "OPTIONS" 

	RegIRewriteUrl ^(.*)$ /sap/public/ping

Adjusting the JavaScript File

The last step is to maintain the service URL in the form JavaScript file. By default, the file already contains the relative service path as follows: “/sap/opu/odata/sap/CUAN_CONTENT_PAGE_RESULT_SRV”. You must enhance this path to contain the domain of your SAP Web Dispatcher.

Example: “https://dispatcher.sap.com/sap/opu/odata/sap/CUAN_CONTENT_PAGE_RESULT_SRV”.

Complete Modification Handler File

Having completed the configuration steps the complete modification handler file should look similar to the following:

#------------------

# Modification Handler for /sap/opa/odata/sap/CUAN_CONTENT_PAGE_RESULT_SRV/

#------------------



# Authorization

SetHeader Authorization "Basic VEVDSFVTRVI6U2VjcmV0MTIz"



# CORS Enablement

SetResponseHeader Access-Control-Allow-Origin "https://www.mymarketingform.com/"

SetResponseHeader Access-Control-Allow-Methods "OPTIONS, HEAD, GET, POST"

SetResponseHeader Access-Control-Allow-Credentials "true"

SetResponseHeader Access-Control-Allow-Headers "Content-Type, X-CSRF-Token"

SetResponseHeader Access-Control-Expose-Headers "X-CSRF-Token"



# OPTIONS Workaround

If %{REQUEST_METHOD} stricmp "OPTIONS" 

	RegIRewriteUrl ^(.*)$ /sap/public/ping

Alternatives to the SAP Web Dispatcher

The described configuration of the SAP Web Dispatcher acting as a reverse proxy can also be implemented using other common web server technologies like Apache HTTP Server, Nginx or Microsoft IIS. This can be helpful in case it’s not possible or not wanted to change the SAP Web Dispatcher configuration.

---

Helpful Links

Cross-Origin-Resource-Sharing: https://developer.mozilla.org/en-US/docs/Glossary/CORS

Preflight Request: https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request

Modification of HTTP Requests: https://help.sap.com/saphelp_nw75/helpdata/en/86/960bf3f8544e0d91c70c9359e2f127/content.htm

Deleting, Adding, and Enhancing HTTP Header Fields: https://help.sap.com/saphelp_nw75/helpdata/en/09/80227250984225ab99eb35f1097166/content.htm

Using the SAP Web Dispatcher for SAP Marketing: https://blogs.sap.com/2016/02/25/using-the-sap-web-dispatcher-for-hybris-marketing-part-1/