How-To install&configure the SAP Web Dispatcher

Last modification: 18. January 2007

Oliver Luik / Christian Goldbach

1 2 3

INTRODUCTION ................................................................................................................................. 4 SAP WEB DISPATCHER INSTALLATION WITH SAPINST.......................................................... 4 SSL INSTALLATION AND CONFIGURATION................................................................................ 4 3.1 THE SAP CRYPTOGRAPHIC LIBRARY INSTALLATION PACKAGE .......................................................... 5 3.1.1 Definition .................................................................................................................................. 5 3.1.2 Structure.................................................................................................................................... 5 3.2 3.2.1 3.2.2 3.3 3.4 3.4.1 3.4.2 3.4.3 3.5 3.5.1 3.5.2 3.5.3 3.5.4 3.6 3.6.1 3.6.2 3.6.3 3.6.4 3.7 3.7.1 3.7.2 3.7.3 3.7.4 3.8 3.8.1 3.8.2 3.8.3 3.8.4 3.9 3.10 INSTALLING THE SAP CRYPTOGRAPHIC LIBRARY .................................................................... 5 Procedure .................................................................................................................................. 5 Result ........................................................................................................................................ 6 SETTING THE SSL PROFILE PARAMETERS FOR THE SAP WEB DISPATCHER ............................... 6 CREATING THE PSES AND CERTIFICATE REQUESTS.................................................................. 8 Use ............................................................................................................................................ 8 Prerequisites.............................................................................................................................. 8 Procedure .................................................................................................................................. 9 SENDING THE CERTIFICATE REQUESTS TO A CA .................................................................... 10 Use .......................................................................................................................................... 10 Prerequisites............................................................................................................................ 11 Procedure ................................................................................................................................ 11 Result ...................................................................................................................................... 12 IMPORTING THE CERTIFICATE REQUEST RESPONSES .............................................................. 13 Use .......................................................................................................................................... 13 Prerequisites............................................................................................................................ 13 Procedure ................................................................................................................................ 13 Result ...................................................................................................................................... 14 CREATING CREDENTIALS FOR THE SAP WEB DISPATCHER..................................................... 14 Use .......................................................................................................................................... 14 Prerequisites............................................................................................................................ 14 Procedure ................................................................................................................................ 14 Result ...................................................................................................................................... 15 TESTING THE SSL CONNECTION TO THE SAP WEB DISPATCHER ............................................ 16 Use .......................................................................................................................................... 16 Prerequisites............................................................................................................................ 16 Procedure ................................................................................................................................ 16 Result ...................................................................................................................................... 16

SAMPLE PROFILE FOR THE SAP WEB DISPATCHER WHEN TERMINATING SSL ......................... 17 SAMPLE PROFILE FOR THE SAP WEB DISPATCHER WHEN REENCRYPTING SSL AND RETRIEVING META DATA USING SSL......................................................................................................................................... 18 4 SAP WEB DISPATCHER CONFIGURATION................................................................................. 20 4.1
NOT DEFINED.

CONFIGURING THE WEB DISPATCHER WEB ADMINISTRATION INTERFACE . ERROR! BOOKMARK

4.2

HOW TO CONFIGURE THE URL FILTER ................................................................................... 20

SAP AG

1.18.07

4.3 4.3.1 4.3.2 4.3.3

4.3.3.1 4.3.3.2

SETTING UP YOUR OWN ERROR PAGES................................................................................. 20 Use .......................................................................................................................................... 20 Prerequisites............................................................................................................................ 21 Procedure ................................................................................................................................ 21
Static Error Pages ........................................................................................................................ 21 Dynamic Error Pages.................................................................................................................... 21

4.3.4 4.4 4.4.1 4.4.2

4.4.2.1 4.4.2.2 4.4.2.3

Example................................................................................................................................... 22 HOW TO DISPLAY A WELCOME PAGE ...................................................................................... 23 Use .......................................................................................................................................... 23 Properties................................................................................................................................ 23

Value Range and Syntax............................................................................................................... 23 Example ....................................................................................................................................... 24 Caching ........................................................................................................................................ 24

4.5 4.5.1 4.5.2 4.5.3

4.5.3.1 4.5.3.2

HOW TO CONFIGURE AUTOMATIC REDIRECTS TO HTTPS........................................................ 25 Use .......................................................................................................................................... 25 Integration............................................................................................................................... 25 Properties................................................................................................................................ 25

Value Range and Syntax............................................................................................................... 25 Examples ..................................................................................................................................... 26

4.5.4 5

More Information .................................................................................................................... 27

REFERENCES .................................................................................................................................... 27 5.1 5.2 5.3 SAP NOTES................................................................................................................................... 27 HOW-TO GUIDES ........................................................................................................................... 28 EXTERNAL REFERENCES ................................................................................................................ 28

HISTORY ............................................................................................................................................ 28

SAP AG

1.18.07

1 Introduction
This document is a Step-By-Step installation manual for the SAP Web Dispatcher for the Service Desk usage.

2 SAP Web Dispatcher Installation with SAPinst

This section describes the installation of the SAP Web Dispatcher with SAPinst. It can technically be done on the same server as the Web AS. The setup on the same server is for security reasons only recommended for demo/internal systems. In a productive setup the SAP Web Dispatcher and the Web AS should be separated by a firewall.

It is recommended to install the ASCII Version of the WebDispatcher. Please refer to the "Installation Guide Web Dispatcher for detailed installation descriptions. At the end of this installation the Web Dispatcher is up and running, you are able to use the Web Admin interface and you are able to send requests to the Web Dispatcher ports which are forwarded to the application server (with the HTTP protocol).

3 SSL Installation and Configuration

This section describes the installation of the SAP Cryptographic Library for SSL and the required configuration to use it in the Web Dispatcher. The configuration of SSL described in this chapter is required in case the Web Dispatcher should terminate the SSL traffic. If End-to-End SSL should be used, then the configuration described in this chapter is not necessary. However, when End-toEnd SSL is used, the Web Dispatcher is not able to look inside the HTTP data, thus features like URL filtering and redirect are not available.
If the SAP Web Dispatcher is to pass the SSL connection to the server in the backend (End-to-End SSL), then set the parameter icm/server_port_<xx> to PROT=ROUTER, PORT=<port>, TIMEOUT=<timeout_in_seconds>.

SAP AG

1.18.07

3.1 The SAP Cryptographic Library Installation Package

3.1.1 Definition
The installation package available for using the SAP Cryptographic Library. The installation package is available for authorized customers on the SAP Service Marketplace at http://service.sap.com/swdc. For unpacking the installation package use the SAPCAR utility. SAPCAR is available on the SAP Service Marketplace -> Support Packages and Patches -> Additional Components -> SAPCAR -> SAPCAR 7.00.

3.1.2 Structure
The SAP Cryptographic Library installation package sapcrypto.car contains the following files: 1. 2. 3. The SAP Cryptographic Library ( sapcrypto.dll for Windows NT or libsapcrypto.<ext> for UNIX) A corresponding license ticket ( ticket) The configuration tool sapgenpse.exe

3.2

Installing the SAP Cryptographic Library

Use the following procedure to install the SAP Cryptographic Library on your host.

3.2.1 Procedure
As user <sid>adm: 1. Extract the contents of the SAP Cryptographic Library installation package. 2. Copy the library file and the configuration tool sapgenpse.exe to the directory specified by the application server's profile parameter DIR_EXECUTABLE. In the following, we represent this directory with the notation $(DIR_EXECUTABLE).
Examples UNIX:

1. 2.

DIR_EXECUTABLE: /usr/sap/<SID>/SYS/exe/run/ Location of SAP Cryptographic Library: /usr/sap/<SID>/SYS/exe/run/libsapcrypto.so

Windows NT:

SAP AG

1.18.07

3. 4.

DIR_EXECUTABLE: <DRIVE>:\usr\sap\<SID>\SYS\exe\run\ Location of SAP Cryptographic Library: <DRIVE>:\usr\sap\<SID>\SYS\exe\run\sapcrypto.dll

3. Check the file permissions for the SAP Cryptographic Library. If, for example, you copied the library to its location using ftp on UNIX, then the file permissions may not be set correctly. Make sure that <sid>adm (or SAPService<SID>under Windows NT) is able to execute the library's functions. 4. Copy the ticket file to the sub-directory sec in the instance directory $(DIR_INSTANCE).
Examples UNIX: h

5. 6.

DIR_INSTANCE: /usr/sap/<SID>/<instance> Location of the ticket: /usr/sap/<SID>/<instance>/sec/ticket DIR_INSTANCE: <DRIVE>:\usr\sap\<SID>\<instance> Location of the ticket: <DRIVE>:\usr\sap\<SID>\<instance>\sec\ticket

Windows NT:

7. 8.

5. Set the environment variable SECUDIR to the sec sub-directory. The application server uses this variable to locate the ticket and its credentials at run-time.
If you set the environment variable using the command line, then the value may not be applied to the server's processes. Therefore, we recommend setting SECUDIR in the startup profile for the server's user or in the registry (Windows NT).

3.2.2 Result
The SAP Cryptographic Library is installed on the application server and the environment is set up correctly so that the Web Dispatcher can locate the library at run-time.

3.3

Setting the SSL Profile Parameters for the SAP Web Dispatcher

In addition to the standard parameters used by the SAP Web Dispatcher, set the following SSLrelevant parameters.

SAP AG

1.18.07

Setting profile parameters for Web Dispatcher is performed using a text editor on the Web Dispatcher profile file. The profile file created by the Web Dispatcher Installation is contained in directory /usr/sap/<SID>/SYS/profile (<DRIVE>:\usr\sap\<SID>\SYS\profile on Windows), the name of the profile file is <SID>_<instance>_<hostname>.

1. Location of the SAP Cryptographic Library and Personal Security Environments to use: ssl/ssl_lib=<Location_of_SAP_Cryptographic_Library> ssl/server_pse=<Location_of_SSL_server_PSE> ssl/client_pse=<Location_of_SSL_client_PSE> The client PSE is only required when SSL is used between the SAP Web Dispatcher and the SAP Web Application Server or between the Web Dispatcher and the SAP Message Server. 4. SAP Web Dispatcher SSL information to use for incoming connections: icm/server_port_<xx>=PROT=HTTPS, PORT=<HTTPS_Port>, TIMEOUT=900 icm/HTTPS/verify_client=<0,1> Documentation for parameter icm/HTTPS/verify_client 5. Connection Parameters to the SAP Web AS Message Server in the backend rdisp/mshost=<message_server_host> ms/https_port=<message_server_HTTPS_Port> if you want to use Metadata Exchange Using SSL. Otherwise, use ms/http_port=<message_server_HTTP_Port> if the connection should not use SSL. Only one of the two parameters ms/https_port and ms/http_port needs to be set, depending on the protocol used for retrieving meta data from the SAP Message Server. The SAP Message Server HTTP and HTTPS ports are defined by profile parameters ms/server_port_0, ms/server_port_1, and can be viewed in transaction SMMS => Goto => Parameters => Display. 6. Parameter for Client Protocol wdisp/add_client_protocol_header=<true,false> Set this parameter to true if there is a change in the protocol at the SAP Web Dispatcher (HTTPS to HTTP or vice versa). If this parameter is set to true, then the SAP Web Dispatcher sets the header variable clientprotocol to the protocol used between the client and the SAP Web Dispatcher (either HTTP or HTTPS). The application server then uses this value as the protocol to use for generated absolute URIs. 7. SSL information to use for outgoing SSL connection

SAP AG

1.18.07

The following parameters are required only when SSL is used between SAP Web Dispatcher and SAP Web Application server or between SAP Web Dispatcher and SAP Message Server. wdisp/ssl_encrypt=<0,1,2> Documentation for wdisp/ssl_encrypt wdisp/ssl_auth=<0,1,2> Documentation for wdisp/ssl_auth wdisp/ssl_cred=<File_name_of_client_PSE> This parameter is only necessary if wdisp/ssl_auth = 2. Documentation for wdisp/ssl_cred wdisp/ssl_certhost=<Common_host_name> Use this parameter if multiple servers in the backend use the same host name in their SSL server certificates (for example, www.mycompany.com). Documentation for wdisp/ssl_certhost

3.4

Creating the PSEs and Certificate Requests

3.4.1 Use
If the SAP Web Dispatcher is to terminate the SSL connection, then it needs to possess a key pair and public-key certificate to use for the incoming SSL connection. This information is stored in the SAP Web Dispatchers SSL server PSE. If it also uses SSL for the connection to the backend server, then it also needs to possess a key pair to use for this connection. This information is stored in its SSL client PSE. Although you can use the same file for both of these PSEs, we refer to them separately in the documentation. You can either use the trust manager to create the PSEs or you can use the configuration tool sapgenpse. See the procedures below.
If the SAP Web Dispatcher is to pass the SSL connection to the SAP Web Application Server, then you do not need to perform these steps.

3.4.2 Prerequisites
8. You know the naming convention to use for the SAP Web Dispatchers Distinguished Name. The syntax of the Distinguished Name depends on the CA that you use.

SAP AG

1.18.07

For example, if you use the SAP CA, the naming convention is CN=<host_name>, OU=I<installation_number>-<company_name>, OU=SAP Web AS, O=SAP Trust Community, C=DE.

3.4.3 Procedure
You can use the configuration tool sapgenpse to create the SAP Web Dispatchers PSEs.
Before you can use sapgenpse to create the SSL server PSE, the environment variable SECUDIR must be set to the directory where the license ticket is located. If the environment variable is not yet set, then set it using the command line as shown below.

Setting the environment variable SECUDIR on Windows: set SECUDIR=<SECUDIR_directory> On Unix systems the syntax for setting environment variables is dependent on the Unix shell.

Use the tools command get_pse as shown below to create the SAP Web Dispatchers PSE.
sapgenpse get_pse <additional_options> -p <PSE_Name> -r <cert_req_file_name> -x <PIN> <Distinguished_Name>

The sapgenpse commands (create the PSE and the certification request, create the credential file, import the own certificate, import trusted certificates) must be performed once for every PSE (for example SAPSSLS.pse and SAPSSLC.pse).

Where: Standard Options

Option -p Parameter <PSE_Name> Description Path and file name for the PSE. If the complete path is not included, then the PSE file is created in the SECUDIR directory. Allowed Values The file name must correspond to the file name specified in the profile parameter ssl/server_pse and wdisp/ssl_cred for the SSL server PSE and the SSL client PSE respectively (for example, SAPSSLS.pse or SAPSSLC.pse). Path description (in quotation marks, if Default None

-r

<file_name>

File name for the certificate request

Stdout

SAP AG

1.18.07

spaces exist) -x None <PIN> <Distinguished_Name> PIN that protects the PSE The Distinguished Name for the SAP Web Dispatcher Character string Character string (in quotation marks, if spaces exist) None None

Additional Options
Option -s -a -noreq Parameter <key_len> <algorithm> None Description Key length Algorithm used Only generate a key pair and PSE. Do not create a certificate request. Generate a certificate request for the public key stored in the PSE specified by the p parameter. Allowed Values 512, 1024, 2048 RSA, DAS Not applicable Default 1024 RSA Not set

-only req

None

Not applicable

Not set

The command line below creates the SAP Web Dispatchers SSL server PSE and certificate request using the following information:

9. 10. 11. 12. 13. 14. 15.

The environment variable SECUDIR is set to C:\Program Files\SAP\SAPWebDisp\sec. The PSE is to be located at C:\Program Files\SAP\SAPWebDisp\sec\SAPSSLS.pse. The PIN used to protect the PSE is abcpin.. The name of the certificate request file is abc.req. The SAP Web Dispatcher is accessed using the fullyqualified host name host123.mycompany.com. The CA used is the SAP CA. Therefore, the servers Distinguished Name is CN=host123.mycompany.com, OU=I1234567890MyCompany, OU=SAP Web AS, O=SAP Trust Community, C=DE.

sapgenpse get_pse -p SAPSSLS.pse -x abcpin -r abc.req "CN=host123.mycompany.com, OU=I1234567890-MyCompany, OU=SAP Web AS, O=SAP Trust Community, C=DE"

SAP AG

1.18.07

3.5

Sending the Certificate Requests to a CA

3.5.1 Use
After you have generated a key pair and certificate request for each PSE, send the certificate requests to a CA to be signed. The response from the CA is a signed public-key certificate for the server when it is using the designated PSE.

3.5.2 Prerequisites
You can send the certificate requests to the CA of your choice, for example, the SAP CA. Note however, the corresponding certificate request response from the CA must be available in one of the following formats: 9. PKCS#7 certificate chain format In this case, the issuing CA provides the certificate request response in the necessary format. For example, the SAP CA provides the response in this format, or you can request this format from your CA. 10. PEM format

In this case, the certificate request response from your CA contains only the signed public-key certificate. Therefore, you must also have access to the CAs root certificate. When using sapgenpse, then it must exist as a file in the file system.

3.5.3 Procedure
For each certificate request that you created, send the contents of the certificate request to your CA. The exact procedure to use depends on the CA that you use. For the SAP CA, follow the instructions provided by the SAP Trust Center Service at http://service.sap.com/tcs.

The link http://service.sap.com/tcs => SSL Test Server Certificates allows you to create signed test certificates. You can sign certificates for testing which will be valid for two months. In order to create a CA response in format PKCS#7, select Choose server type => PKCS#7 certificate chain.

To view the contents of the certificate, open the certificate request with a text editor. Because many editors use hidden characters for formatting, use a text editor that does not support formatting features, for example, Notepad. If carriage returns or line feeds have been corrupted, for example, during download, then correct these errors.

The example below shows a correct certificate request.

SAP AG

1.18.07

-----BEGIN CERTIFICATE REQUEST----MIIBkzCCAVICAQAwWjELMAkGA1UEBhMCREUxHDAaBgNVBAoTE215U0FQLmNvbS BXb3JrcGxhY2UxDzANBgNVBAsTBlNBUCBBRzEOMAwGA1UECxMFQmFzaXMxDDAK BgNVBAMTA0JJTzCB7jCBpgYFKw4DAhswgZwCQQCSnauC/cAfQVrmOtWznQ9I+i 4twoPq8wCE0Fk5EAVjQnX2oMqBnyoi+ee/ZH2cLwyhp5mOOw70+exS7PHEWKiF AhUAw9FSY1AsFV4U9fC9w+Bg5H4ISYcCQARcC+7q3UkM0TF0A5zRaq7viO3Wj2 MwYUNwFkc0hxzhloUQd21megZADoFiisdzkn/nF4eIxV9vq9XxcV63xTsDQwAC QFher18UA8YkY4/zHe4mbupBXvDSucm2nbJuQ5PgDBvVaMmtpXIisyzuAFL+qC zQ92mkNqUR9JLWpz09ghQdISCgADAJBgcqhkjOOAQDAzAAMC0CFA7qEluP/Kfi +6HF/8I7j4NfF44xAhUAqkDgAeR3tzmNegKUTQ+JzeCXawE= -----END CERTIFICATE REQUEST-----

3.5.4 Result
The CA will validate the information contained in the certificate request (according to its own policy) and return a response that contains the signed public-key certificate.

SAP AG

1.18.07

3.6

Importing the Certificate Request Responses

3.6.1 Use
The CA will send you a certificate request response that contains the signed publickey certificate for the SAP Web Dispatcher. Once you have received this response, import it into the SAP Web Dispatchers corresponding PSE. You can either use the trust manager or you can use the configuration tool sapgenpse. See the procedures below.

3.6.2 Prerequisites
11. If you are using sapgenpse, then each certificate request response exists as a file in the file system. Otherwise, if you are using the trust manager, then the responses can either exist as a file or you can use Copy&Paste to insert it into the PSE. 12. If the certificate request responses do not contain the CAs root certificate, then you also have access to this certificate. If you are using the trust manager, then it must exist in the trust managers database. If you are using sapgenpse, then it exists as a file in the file system.

3.6.3 Procedure
You can use the configuration tool sapgenpse to import the certificate request response into the PSEs. Use the tools command import_own_cert as shown below.
sapgenpse import_own_cert <Additional_options> -p <PSE_file> -c <Cert_file> [-r <RootCA_cert_file>] -x <PIN>

Where: Standard Options

Option -p Parameter <PSE_Name> Description Path and file name of the PSE. Allowed Values Path description (in quotation marks, if spaces exist) Default None

The path is the SECUDIR directory and the file name is SAPSSLS.pse. for the SSL server PSE or SAPSSLC.pse for the SSL client PSE (if it exists).
-c <Cert_file> Path and file name of the

Path description (in

None

SAP AG

1.18.07

certificate request response -r <RootCA_cert_ file> File containing the CAs root certificate (and any intermediate CA certificates). This parameter is necessary if the CA root and any intermediate CA certificates are not included in the certificate request response. PIN that protects the PSE

quotation marks, if spaces exist) Path description (in quotation marks, if spaces exist) Not set

-x

<PIN>

Character string

None

3.6.4 Result
The certificate request response is imported into the PSE.
The following command line imports the certificate request response (ABC.cer) into the SAP Web Dispatchers SSL server PSE that is stored at C:\Program Files\SAP\SAPWebDisp\sec\SAPSSLS.pse. (SECUDIR is set to C:\Program Files\SAP\SAPWebDisp\sec). The PIN that protects the PSE is abcpin. sapgenpse import_own_cert -c ABC.cer -p SAPSSLS.pse -x abcpin

3.7

Creating Credentials for the SAP Web Dispatcher

3.7.1 Use
The SAP Web Dispatcher must have active credentials at run-time to be able to access its PSEs. Therefore, to produce active credentials, use the configuration tools command seclogin to open each PSE.
The credentials are located in the file cred_v2 in the directory specified by the environment variable SECUDIR. Make sure that only the user under which the SAP Web Dispatcher runs has access to this file (including read access).

3.7.2 Prerequisites
13. The SAP Cryptographic Library is installed and the environment variable SECUDIR is set to the directory where the license ticket and PSEs are located. 14. You know the user that runs the SAP Web Dispatcher.

SAP AG

1.18.07

3.7.3 Procedure
Use the following command line to open each PSE and create credentials.
sapgenpse seclogin <additional options> -p <PSE_Name> -x <PIN> -O [<Windows_Domain>\]<user_ID>

Where: Standard Options

Option -p Parameter <PSE_Name> Description Allowed Values Default None

Path and file name for the PSE.

PIN that protects the PSE User for which the credentials are created. (The user that runs the SAP Web Dispatcher process.)

Path description (in quotation marks, if spaces exist)

Character string Valid operating system user

-x -O

<PIN> [<Windows_ Domain>\] <user_ID>

None The current user

If the user that runs the SAP Web Dispatcher is the current user, then this parameter is optional. Use the parameter v (verbose) to see the results.

Additional Options
Option -l Parameter None Description List all available credentials for the current user. Delete credentials Specifies that you want to change the PIN Allowed Values Not applicable Default Not set

-d -chpin

None None

Not applicable Not applicable

Not set Not set

After creating the credentials, restart the SAP Web Dispatcher.

3.7.4 Result
The credentials file (cred_v2) for the user provided with the O option is created in the SECUDIR directory.
The following command line opens the SAP Web Dispatchers SSL server PSE that is located at C:\Program Files\SAP\SAPWebDisp\sec\SAPSSLS.pse and creates

SAP AG

1.18.07

credentials for the user ABCadm. (SECUDIR is set to C:\Program Files\SAP\SAPWebDisp\sec). The PIN that protects the PSE is abcpin. sapgenpse seclogin -p SAPSSLS.pse -x abcpin -O ABCadm

SAP AG

1.18.07

3.8

Testing the SSL Connection to the SAP Web Dispatcher

3.8.1 Use
Use the following test to test the SSL connection to the SAP Web Dispatcher. In this test, the SAP Web Dispatcher connects to the SAP Web Application Server using a Business Server Page (BSP).

3.8.2 Prerequisites
15. 16. The SAP Web Dispatchers PSEs and credentials exist. The SAP Web Dispatcher has been restarted.

17. You know the port number that the SAP Web Dispatcher is using for HTTPS connections. The port number is specified in the profile parameter icm/server_port_<xx> in the SAP Web Dispatchers profile.

3.8.3 Procedure
2. Start a BSP using an HTTPS connection to your SAP Web Dispatcher and the corresponding SSL port.
For example, start the standard BSP test application IT00 with the URL https://mywebdisp.mycompany.com:443/sap/bc/bsp/sap/it00/ default.htm.

If your Web browser cannot completely verify the SAP Web Dispatcher's publickey certificate, then you will receive a dialog that states the reason why. For example, if your Web browser does not possess the issuing CA's root certificate as a trusted root certificate, then you are informed and can choose to trust the server at this time. 3. If you trust the server's certificate (either automatically or manually), then the next step is to authenticate yourself. If your authentication was successful, the page appears.

3.8.4 Result
You are connected to the SAP Web AS via the SAP Web Dispatcher. SSL is used for the connection between your Web browser and the SAP Web Dispatcher, which is indicated in your Web browser.

SAP AG

1.18.07

SAP R/3 und HTTP

-18-

3.9

Sample Profile for the SAP Web Dispatcher When Terminating SSL

# SAPSYSTEMNAME must be set so that the default profile is # read. If not, a warning is displayed on the console. SAPSYSTEMNAME = ABC

# SAPSYSTEM must be set so that the shared memory areas # can be created. # The number must be different from the other SAP instances # on the host. SAPSYSTEM = 26 # Set DIR_INSTANCE so that the SAP Cryptographic Library can # find the sec sub-directory. DIR_INSTANCE = C:\Program Files\SAP\SAPWebDisp # Message Server Description rdisp/mshost = abcmain ms/http_port = 8081 # Description of the Access Points icm/server_port_0 = PROT=HTTP, PORT=1081, TIMEOUT=900 icm/server_port_1 = PROT=HTTPS, PORT=1443, TIMEOUT=900 icm/HTTPS/verify_client = 0 # Parameters for the SAP Cryptographic Library ssl/ssl_lib = C:\Program Files\SAP\SAPWebDisp\sapcrypto.dll ssl/server_pse = C:\Program Files\SAP\SAPWebDisp\sec\SAPSSLS.pse

SAP AG

1.18.07

SAP R/3 und HTTP

-19-

3.10 Importing the application servers certificate to the Web Dispatcher

This configuration is only used when SSL is used for the communication between SAP Web Dispatcher and SAP Web Application Server or between SAP Web Dispatcher and SAP Message Server. Export the SSL certificate of a PSE (e.g. the SSL certificate of the SAP Web Application Server or the SSL certificate of the SAP Message Server) and import it into the Web Dispatchers client PSE. Export the servers certificate
sapgenpse export_own_cert -p SAPSSLS.pse -x WASPIN

Save the output to a file WAS.cer and import it to the Web Dispatchers client PSE using the command
sapgenpse.exe maintain_pk -a WAS.cer -p SAPSSLC.pse -x ABCPIN

The opposite direction of importing the Web Dispatchers client certificate into the server PSE is not required, unless the server explicitely requests that a client certificate is provided using parameter icm/HTTPS/verify_client=2. Instead of importing a servers SSL certificate directly it would also be possible to import the root certificate of the CA which was used to sign the servers certificate. This is not described here. It is possible to use certificates which are not signed by a CA between SAP Web Dispatcher and SAP Web Application Server or SAP Web Dispatcher and SAP Message Server. However, in this case the certificates must be identical. This can be achieved by copying the servers server PSE file to the Web Dispatcher client PSE file.

3.11 Sample Profile for the SAP Web Dispatcher When Reencrypting SSL and retrieving meta data using SSL
When SSL reencryption is used, the SAP Web Application Server must be configured to support SSL. When meta data is retrieved using SSL, additionally the SAP Message Server must be configured to support SSL. # SAPSYSTEMNAME must be set so that the default profile is # read. If not, a warning is displayed on the console. SAPSYSTEMNAME = ABC

SAP AG

1.18.07

SAP R/3 und HTTP

-20-

# SAPSYSTEM must be set so that the shared memory areas # can be created. # The number must be different from the other SAP instances # on the host. SAPSYSTEM = 26 # Set DIR_INSTANCE so that the SAP Cryptographic Library can # find the sec sub-directory. DIR_INSTANCE = C:\Program Files\SAP\SAPWebDisp # Message Server Description rdisp/mshost = abcmain ms/https_port = 8443 # Description of the Access Points icm/server_port_0 = PROT=HTTP, PORT=1081, TIMEOUT=900 icm/server_port_1 = PROT=HTTPS, PORT=1443, TIMEOUT=900 icm/HTTPS/verify_client = 0 # Parameters for the SAP Cryptographic Library ssl/ssl_lib = C:\Program Files\SAP\SAPWebDisp\sapcrypto.dll ssl/server_pse = C:\Program Files\SAP\SAPWebDisp\sec\SAPSSLS.pse # Parameters for Using SSL to the backend server wdisp/ssl_encrypt = 2 wdisp/ssl_auth = 2 wdisp/ssl_cred = SAPSSLC.pse wdisp/ssl_certhost = www.mycompany.com # Parameters for retrieving meta data using SSL wdisp/server_info_protocol=https wdisp/group_info_protocol=https wdisp/url_map_protocol=https

SAP AG

1.18.07

SAP R/3 und HTTP

-21-

4 SAP Web Dispatcher Configuration

The following steps are also covered in the Web Dispatcher documentation on the SAP help portal: http://help.sap.com/saphelp_nw2004s/helpdata/en/f5/51c7d170bc4a98b1b5a03392 13af57/frameset.htm

4.1

How to configure the URL filter

To configure the URL filter you have to set the following profile parameter in the instance profile of the Web Dispatcher: wdisp/permission_table = $(DIR_DATA)/perm.txt and create a textfile named perm.txt in the instance data directory with the following content: # URL permission table P P D /sap/bc/* /sap/public/bsp/* *

Please check the new settings with the Web Admin Interface and the menu: Dispatching Module -> URL Filter.

4.2

Setting Up Your Own Error Pages

4.2.1 Use
For each Error Code, you can create an HTML page, which is sent to the client when this error occurs. You can define both static pages (ending .html) and dynamic pages (ending .shtml). Moreover, you can create a file ICMERR-EDEFAULT.{html,shtml} in directory icm/HTTP/error_templ_path, whose contents are returned if there is no other template for the error. If external resources (such as images) should be referenced in the error templates, these can be delivered with the ICMs file access handler. See also icm/HTTP/file_access_<xx>.

SAP AG

1.18.07

SAP R/3 und HTTP

-22-

4.2.2 Prerequisites
To use dynamic error handling in the ICM or Web dispatcher, you must set the profile parameter icm/HTTP/error_templ_path to the directory with the error template files. For example: icm/HTTP/error_templ_path = /usr/sap/WEB/D13/data/icmerror
If you use the Internet Explorer Web browser, the option Show friendly HTTP messages must be deactivated. You can set this from the menu: Tools Internet Options Advanced under Browsing.

4.2.3 Procedure
Create files ICMERR-<error code>.(s)html in the relevant directory for the error codes you want. You can create static or dynamic error pages. 4.2.3.1 Static Error Pages If a static error page is defined for an error (ending .html), this is returned to the client. 4.2.3.2 Dynamic Error Pages The dynamic pages support the following SSI commands (server-die includes, see http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html).
For the dynamic substitutions, the whole file must be searched for the SSI tags "<!--". The effort required to do this is related to the size of the file. The dynamic pages cannot be stored in the cache either.

The following section explains the SSI commands that are supported.
4.2.3.2.1 ECHO

<!--#echo var="variable" --> You can set the following variables: Variable Name DATE_LOCAL DATE_GMT Meaning Current time/date: Tue Mar 26 17:15:32 2002 Current GMT time/date: Tue Mar 26 17:15:32 2002

LAST_MODIFIED FILE_SIZE SERVER_SOFTWARE SERVER_NAME SERVER_PORT

The time when the current file was last modified Size of the current file in Bytes SAP Web Application Server 6.30 The name of the server The server port

SAP AG

1.18.07

SAP R/3 und HTTP

-23-

PATH_TRANSLATED ICM_SERVER

URL path (without parameters) Host name and port through which this server can be reached. For example: Is3022.wdf.sapag.de:1080 Instance name: ls3022_BIN_12 Error that occurred (numeric) ICM version

ICM_INSTANCE ICM_ERR_CODE ICM_ERR_VERSION

ICM_ERR_COMPONENT Component ICM_ERR_MODULE ICM_ERR_LINE ICM_ERR_DETAIL Module Name Line Detail on the error that occurred

Not all fields are available for all errors. With error ICMEOVERLOAD, for example, the request has not yet been read, which is why field PATH_TRANSLATED has not been set.

In your page you can write, for example: <tr><td>Server:</td><td><!--#echo var="ICM_SERVER" --></td></tr> </tr><tr><td background="http://<!--#echo var="ICM_SERVER" -->/images/graybar_tile.jpg" height="31">

4.2.3.2.2 INCLUDE

You can use this command to include a different file at this point. <!--#include file="file name" -->
Your error page can be framed, for example, by the two INCLUDE statements: <!--#include file="header.html" --> ... <!--#include file="footer.html" -->

The file must not include itself! Recursive inclusion causes the ICM to terminate.

4.2.4 Example
You can find an example of a dynamic error page and the .shtml file in Examples of a Dynamic Error Page.

SAP AG

1.18.07

SAP R/3 und HTTP

-24-

4.3

How to display a welcome page

4.3.1 Use
The parameter icm/HTTP/file_access_<xx> determines for which URL prefixes static file access should be set, and in which directory the static files are stored. If an attempt is made to access a page or file under virtual_root defined by the URL prefix, virtual_root is replaced by document_root. The handler then attempts to read the file from the file system and to send it back to the client.

4.3.2 Properties
Work area Unit Standard value Dynamically changeable Internet Communication Manager, SAP Web Dispatcher Character string No

4.3.2.1 Value Range and Syntax The parameter has the following syntax: icm/HTTP/file_access_<xx> = PREFIX=<URL-prefix>, DOCROOT=<root directory of files>, CACHECTRL=<sec> <xx> must be specified in ascending order from 0. For example,icm/HTTP/file_access_0 = PREFIX=/docs/, DOCROOT=/tmp/documents Then when the ICM enters the URL prefix /docs/xxx in the browser, the content of file xxx in directory /tmp/documents is returned.
4.3.2.1.1 Displaying Directory Contents

You can also define a directory index with this parameter. Use the following options for this.
Option Meaning / Possible Values

BROWSEDIR

Determines the level of detail in the list. The following values are permitted: 0: Function is inactive directory contents are not displayed. 1: Only the file names are displayed. 2: File names are displayed together with their size and date last changed.

SAP AG

1.18.07

SAP R/3 und HTTP

-25-

DIRINDEX IGNORE
Caching

Name of file that is to be displayed instead of the directory contents. The display of the directory contents can be restricted. Files to which the template applies are not listed.

4.3.2.1.2

With the option CACHECTRL you can specify the cache time in seconds. This is the length of time the ICM temporarily stores data for after it has sent the data to the client. If the same request arrives within this time interval, it is dealt with in the cache. You can specify the following values for this option: (default is +3600 that is, one hour) 18. 19. 0 or -1: Files are not passed to the cache. +7200: Files are kept in the cache for two hours.
Note that you have to enter a + sign.

4.3.2.2 Example You have configured the port 8080 for HTTP and set: icm/HTTP/file_access_0 = PREFIX=/doc/, DOCROOT=/tmp/documents,DIRINDEX=index.htm,BROWSEDIR=2,IGNORE=c ore *.dll *.info *.bak Documents is a directory containing various files. In the browser open URL http://host:8080/doc/ (do not forget the slash at the end). A detailed display of all the files in the directory will be displayed. Files with names core, endings info or bak, are not displayed in the list.If the file index.htm is in the directory, its contents are displayed. To display a file double-click it. If it is a directory again, the contents will be displayed or the file specified with DIRINDEX (in this example, index.htm). 4.3.2.3 Caching With the option CACHECTRL you can specify the cache time in seconds. This is the length of time the ICM temporarily stores data for after it has sent the data to the client. If the same request arrives within this time interval, it is dealt with in the cache. You can specify the following values for this option: (default is +3600 that is, one hour) 20. 21. 0 or -1: Files are not passed to the cache. +7200: Files are kept in the cache for two hours.

SAP AG

1.18.07

SAP R/3 und HTTP

-26-

Note that you have to enter a + sign.

4.4

How to configure automatic redirects to HTTPS

To configure the automatic redirect in the Web Dispatcher you have to set the profile parameter icm/HTTP/redirect_<xx> in the instance profile of the Web Dispatcher:
icm/HTTP/redirect_0 = PREFIX=/, FROM=*, FROMPROT=http, PROT=https, PORT=8866, HOST=ldp007.wdf.sap.corp

4.4.1 Use
This parameter is used to define an HTTP redirect (301). If the client attempts to access the URL in question, the server sends a redirect. This forces the client to access the new destination instead.

4.4.2 Integration
If this parameter is set, it calls the redirect subhandler of the HTTP plug-in. The HTTP request is therefore not sent to the backend (ABAP or J2EE server). Processing HTTP Requests describes the subhandler call sequence.

4.4.3 Properties
Work area Unit Standard value Dynamically changeable Internet Communication Manager, SAP Web Dispatcher Character string Local and on all servers

4.4.3.1 Value Range and Syntax The parameter has the following syntax: icm/HTTP/redirect_<xx> = PREFIX=<URL prefix>[, FROM=<pattern for URL>, FROMPROT=<incoming protocol>, FOR=<pattern for host name:port>,TO=<new URL prefix>, PROT=<protocol>, HOST=<host>, PORT=<port number/name>] <xx> must be specified in ascending order from 0.
4.4.3.1.1 Optional Parameters

With the optional parameters FROM and FROMPROT special requests can be selected for which a redirect is to be created:

SAP AG

1.18.07

SAP R/3 und HTTP

-27-

22.

FROM:

Pattern with wildcards *(character string) and ? (a character) For example, the pattern /sap/* matches all requests beginning with /sap. If FROM is not specified the redirect for URLs which match the PREFIX exactly is created. 23. FROMPROT:

Value range: http or https. This argument is used to restrict requests to one receive protocol. If FROMPROT is not specified, a redirect is created for all protocols. With the optional parameter FOR you can check whether a redirect is to be created at all. 24. FOR:

The pattern for host name:port can contain the wildcards * (character string) and ? (one character), and must match the value of the HTTP header field HOST. Only if it does, is a redirect executed. If it does not match the value or if the HOST header field is not set, a redirect is likewise not sent.
The pattern *.sap.com:* matches the HOST header field wassrv.sap.com:80 or wassrv2.sap.com:1080.

If the option FOR is not set, a redirect is executed for any value of the header field HOST. You can use optional parameters PROT, HOST, PORT and TO to set the destination to a different protocol, a different host, a different port, or to a different URL. You can only specify the port and protocol once you have specified a host name. If you specify the PROT or PORT you also have to specify the HOST. If the parameter TO is defined it describes the exact URL to which a request is forwarded. With TO no variable from the URL derived from the incoming URL can be created. The default values for PROT, HOST, PORT and TO are values that are set when an incoming request is received. If the options are not set, these values are not changed for the redirect that is created.

4.4.3.2 Examples
Parameter Value Description

icm/HTTP/redirect_0 = PREFIX=/, TO=/bc/bsp/demo/default.html

Access attempts on "/" are redirected to "/bc/bsp/demo/default.html".

SAP AG

1.18.07

SAP R/3 und HTTP

-28-

icm/HTTP/redirect_0 = PREFIX=/, FROM=/mime/*,HOST=mimeserver, PORT=8080 icm/HTTP/redirect_0 = PREFIX=/sap/bc/bex, FROMPROT=http, PROT=https, HOST=px155.sap.com icm/HTTP/redirect_0 = PREFIX=/, FROM=/sap*, FROMPROT=http, PROT=https, HOST=px155.sap.com icm/HTTP/redirect_0 = PREFIX=/, FROM=*, FROMPROT=http, PROT=https, HOST=px155.sap.com icm/HTTP/redirect_0 = PREFIX=/, FROM=/mime/*,FOR=crm.sap.com* ,HOST=crmserver, PORT=80

Only requests with specific URL patterns are redirected to HTTPS

Only requests with a specific URL are redirected to HTTPS

Only specific HTTP requests are redirected to HTTPS

All HTTP requests are redirected to HTTPS

Requests with the URL prefix /mime/ and the HTTP header field HOST that matches the pattern crm.sap.com:* are redirected to the server crmserver:80.

4.4.4 More Information

Note the following documentation associated with this parameter: Generic Profile Parameters with the Ending _<xx>

5 References

5.1 SAP Notes

538405 974284 908097 552286 634262 Composite SAP Note on the SAP Web Dispatcher Patch History 7.00 Install Patches for SAP Web Dispatcher 7.00 Troubleshooting for the SAP Web Dispatcher Preclarification of SAP Web dispatcher problems

SAP AG

1.18.07

SAP R/3 und HTTP

-29-

870127 833960 750292 597059 397175

Security recommendations Requirements for reverse proxies (Application Gateways) URL Generation in SAP Web AS License conditions SAP-Cryptographic Library SAP Cryptographic Software - Export control

5.2 How-To Guides

http://service.sap.com/nw-howtoguides -> SAP Web Application Server. configure SAP Web Dispatcher for SSL www.sdn.sap.com -> Guidelines for Successful Implementation of SAP Web Dispatcher in Customer Landscapes

5.3 External References

HTTP1.0 RFC 1945 (http://www.faqs.org/rfcs/rfc1945.html) HTTP1.1 RFC 2068 (http://www.faqs.org/rfcs/rfc2068.html) MIME Extensions RFC 1521 (http://www.faqs.org/rfcs/rfc1521.html)

6 History
Date 28.11.2006 OL 12.12.2006 OL 17.12.2006 OL 8.1.2007 CG Change 1st version Added several chapters Review & New design Corrections and Additions (sample profile for reencryption)

SAP AG

1.18.07