Web Disp Step by Step Docu

How-To install&configurethe SAP Web Dispatcher

Last modification: 18. January 2007

Oliver Luik / Christian Goldbach

SAP AG 1.18.07

1 INTRODUCTION ................................................................................................................................. 4

2 SAP WEB DISPATCHER INSTALLATION WITH SAPINST.......................................................... 4

3 SSL INSTALLATION AND CONFIGURATION................................................................................ 4

3.1 THE SAP CRYPTOGRAPHIC LIBRARY INSTALLATION PACKAGE .......................................................... 53.1.1 Definition .................................................................................................................................. 53.1.2 Structure.................................................................................................................................... 5

3.2 INSTALLING THE SAP CRYPTOGRAPHIC LIBRARY .................................................................... 53.2.1 Procedure.................................................................................................................................. 53.2.2 Result ........................................................................................................................................ 6

3.3 SETTING THE SSL PROFILE PARAMETERS FOR THE SAP WEB DISPATCHER ............................... 6

3.4 CREATING THE PSES AND CERTIFICATE REQUESTS.................................................................. 83.4.1 Use ............................................................................................................................................ 83.4.2 Prerequisites.............................................................................................................................. 83.4.3 Procedure.................................................................................................................................. 9

3.5 SENDING THE CERTIFICATE REQUESTS TO A CA.................................................................... 103.5.1 Use .......................................................................................................................................... 103.5.2 Prerequisites............................................................................................................................ 113.5.3 Procedure................................................................................................................................ 113.5.4 Result ...................................................................................................................................... 12

3.6 IMPORTING THE CERTIFICATE REQUEST RESPONSES .............................................................. 133.6.1 Use .......................................................................................................................................... 133.6.2 Prerequisites............................................................................................................................ 133.6.3 Procedure................................................................................................................................ 133.6.4 Result ...................................................................................................................................... 14

3.7 CREATING CREDENTIALS FOR THE SAP WEB DISPATCHER..................................................... 143.7.1 Use .......................................................................................................................................... 143.7.2 Prerequisites............................................................................................................................ 143.7.3 Procedure................................................................................................................................ 143.7.4 Result ...................................................................................................................................... 15

3.8 TESTING THE SSL CONNECTION TO THE SAP WEB DISPATCHER ............................................ 163.8.1 Use .......................................................................................................................................... 163.8.2 Prerequisites............................................................................................................................ 163.8.3 Procedure................................................................................................................................ 163.8.4 Result ...................................................................................................................................... 16

3.9 SAMPLE PROFILE FOR THE SAP WEB DISPATCHER WHEN TERMINATING SSL......................... 173.10 SAMPLE PROFILE FOR THE SAP WEB DISPATCHER WHEN REENCRYPTING SSL AND RETRIEVING METADATA USING SSL......................................................................................................................................... 18

4 SAP WEB DISPATCHER CONFIGURATION................................................................................. 20

4.1 CONFIGURING THE WEB DISPATCHER WEB ADMINISTRATION INTERFACE . ERROR! BOOKMARKNOT DEFINED.

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

SAP AG 1.18.07

4.3 SETTING UP YOUR OWN ERROR PAGES................................................................................. 204.3.1 Use .......................................................................................................................................... 204.3.2 Prerequisites............................................................................................................................ 214.3.3 Procedure................................................................................................................................ 21

4.3.3.1 Static Error Pages ........................................................................................................................ 214.3.3.2 Dynamic Error Pages.................................................................................................................... 21

4.3.4 Example................................................................................................................................... 22

4.4 HOW TO DISPLAY A WELCOME PAGE ...................................................................................... 234.4.1 Use .......................................................................................................................................... 234.4.2 Properties................................................................................................................................ 23

4.4.2.1 Value Range and Syntax............................................................................................................... 234.4.2.2 Example ....................................................................................................................................... 244.4.2.3 Caching........................................................................................................................................ 24

4.5 HOW TO CONFIGURE AUTOMATIC REDIRECTS TO HTTPS........................................................ 254.5.1 Use .......................................................................................................................................... 254.5.2 Integration............................................................................................................................... 254.5.3 Properties................................................................................................................................ 25

4.5.3.1 Value Range and Syntax............................................................................................................... 254.5.3.2 Examples ..................................................................................................................................... 26

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

5 REFERENCES .................................................................................................................................... 27

5.1 SAP NOTES................................................................................................................................... 275.2 HOW-TO GUIDES ........................................................................................................................... 285.3 EXTERNAL REFERENCES ................................................................................................................ 28

6 HISTORY ............................................................................................................................................ 28

SAP AG 1.18.07

1 Introduction

This document is a Step-By-Step installation manual for the SAP Web Dispatcher forthe 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 thesame server as the Web AS. The setup on the same server is for security reasons only recommended fordemo/internal systems. In a productive setup the SAP Web Dispatcher and the Web AS should be separated by afirewall.

It is recommended to install the ASCII Version of the WebDispatcher.

Please refer to the "Installation Guide Web Dispatcher” for detailed installationdescriptions.

At the end of this installation the Web Dispatcher is up and running, you are able touse the Web Admin interface and you are able to send requests to the WebDispatcher ports which are forwarded to the application server (with the HTTPprotocol).

3 SSL Installation and Configuration

This section describes the installation of the SAP Cryptographic Library for SSL andthe required configuration to use it in the Web Dispatcher.

The configuration of SSL described in this chapter is required in case the WebDispatcher should terminate the SSL traffic. If End-to-End SSL should be used, thenthe configuration described in this chapter is not necessary. However, when End-to-End SSL is used, the Web Dispatcher is not able to look inside the HTTP data, thusfeatures 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> toPROT=ROUTER, PORT=<port>, TIMEOUT=<timeout_in_seconds>.

SAP AG 1.18.07

3.1 The SAP Cryptographic Library Installation Package

3.1.1 DefinitionThe installation package available for using the SAP Cryptographic Library. Theinstallation package is available for authorized customers on the SAP ServiceMarketplace at http://service.sap.com/swdc.

For unpacking the installation package use the SAPCAR utility. SAPCAR is availableon the SAP Service Marketplace -> Support Packages and Patches -> AdditionalComponents -> SAPCAR -> SAPCAR 7.00.

3.1.2 StructureThe SAP Cryptographic Library installation package sapcrypto.car contains thefollowing files:

1. The SAP Cryptographic Library ( sapcrypto.dll for Windows NT orlibsapcrypto.<ext> for UNIX)

2. A corresponding license ticket ( ticket)

3. The configuration tool sapgenpse.exe

3.2 Installing the SAP Cryptographic LibraryUse the following procedure to install the SAP Cryptographic Library on your host.

3.2.1 ProcedureAs 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 thedirectory specified by the application server's profile parameterDIR_EXECUTABLE. In the following, we represent this directory with thenotation $(DIR_EXECUTABLE).

Examples

UNIX:

1. DIR_EXECUTABLE: /usr/sap/<SID>/SYS/exe/run/

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

Windows NT:

http://service.sap.com/swdc.

SAP AG 1.18.07

3. DIR_EXECUTABLE:<DRIVE>:\usr\sap\<SID>\SYS\exe\run\

4. 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, forexample, you copied the library to its location using ftp on UNIX, then the filepermissions may not be set correctly. Make sure that <sid>adm (orSAPService<SID>under Windows NT) is able to execute the library'sfunctions.

4. Copy the ticket file to the sub-directory sec in the instance directory$(DIR_INSTANCE).

Examples

UNIX: h

5. DIR_INSTANCE: /usr/sap/<SID>/<instance>

6. Location of the ticket:/usr/sap/<SID>/<instance>/sec/ticket

Windows NT:

7. DIR_INSTANCE:<DRIVE>:\usr\sap\<SID>\<instance>

8. Location of the ticket:<DRIVE>:\usr\sap\<SID>\<instance>\sec\ticket

5. Set the environment variable SECUDIR to the sec sub-directory. Theapplication server uses this variable to locate the ticket and its credentials atrun-time.

If you set the environment variable using the command line, then the value may not beapplied to the server's processes. Therefore, we recommend setting SECUDIR in thestartup profile for the server's user or in the registry (Windows NT).

3.2.2 ResultThe SAP Cryptographic Library is installed on the application server and theenvironment is set up correctly so that the Web Dispatcher can locate the library atrun-time.

3.3 Setting the SSL Profile Parameters for the SAP WebDispatcher

In addition to the standard parameters used by the SAP Web Dispatcher, set the following SSL-relevant parameters.

SAP AG 1.18.07

Setting profile parameters for Web Dispatcher is performed using a text editor on theWeb Dispatcher profile file. The profile file created by the Web Dispatcher Installation iscontained 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 Environmentsto 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 betweenthe SAP Web Dispatcher and the SAP Web Application Serveror 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 backendrdisp/mshost=<message_server_host>

ms/https_port=<message_server_HTTPS_Port> if you want to useMetadata Exchange Using SSL. Otherwise, usems/http_port=<message_server_HTTP_Port> if the connection shouldnot use SSL.

Only one of the two parameters ms/https_port and ms/http_port needs to beset, depending on the protocol used for retrieving meta data from the SAPMessage Server.

The SAP Message Server HTTP and HTTPS ports are defined by profileparameters ms/server_port_0, ms/server_port_1, … and can be viewed intransaction SMMS => Goto => Parameters => Display.

6. Parameter for Client Protocolwdisp/add_client_protocol_header=<true,false>

Set this parameter to true if there is a change in the protocol at the SAP WebDispatcher (HTTPS to HTTP or vice versa). If this parameter is set to true, thenthe SAP Web Dispatcher sets the header variable clientprotocol to theprotocol used between the client and the SAP Web Dispatcher (either HTTP orHTTPS). The application server then uses this value as the protocol to use forgenerated 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 SAPWeb Dispatcher and SAP Web Application server or between SAP WebDispatcher and SAP Message Server.

wdisp/ssl_encrypt=<0,1,2>

Documentation for wdisp/ssl_encryptwdisp/ssl_auth=<0,1,2>

Documentation for wdisp/ssl_authwdisp/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 namein 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 UseIf the SAP Web Dispatcher is to terminate the SSL connection, then it needs topossess a key pair and public-key certificate to use for the incoming SSLconnection. This information is stored in the SAP Web Dispatcher’s SSL serverPSE.

If it also uses SSL for the connection to the backend server, then it also needs topossess a key pair to use for this connection. This information is stored in its SSLclient PSE. Although you can use the same file for both of these PSEs, we refer tothem separately in the documentation.

You can either use the trust manager to create the PSEs or you can use theconfiguration tool sapgenpse. See the procedures below.

If the SAP Web Dispatcher is to pass the SSL connection to the SAP Web ApplicationServer, then you do not need to perform these steps.

3.4.2 Prerequisites8. You know the naming convention to use for the SAP Web Dispatcher’s

Distinguished Name. The syntax of the Distinguished Name depends on the CAthat you use.

http://www.mycompany.com

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=SAPTrust Community, C=DE.

3.4.3 ProcedureYou can use the configuration tool sapgenpse to create the SAP Web Dispatcher’sPSEs.

Before you can use sapgenpse to create the SSL server PSE, the environmentvariable SECUDIR must be set to the directory where the license ticket is located. If theenvironment 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 Unixshell.

Use the tool’s command get_pse as shown below to create the SAP WebDispatcher’s 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 thecredential file, import the own certificate, import trusted certificates) must be performedonce for every PSE (for example SAPSSLS.pse and SAPSSLC.pse).

Where:

Standard Options

Option Parameter Description Allowed Values Default-p <PSE_Name> Path and file name for

the PSE.

If the complete path isnot included, then thePSE file is created inthe SECUDIR directory.

The file name mustcorrespond to the filename specified in theprofile parameterssl/server_pse andwdisp/ssl_cred forthe SSL server PSEand the SSL clientPSE respectively (forexample,SAPSSLS.pse orSAPSSLC.pse).

None

-r <file_name> File name for thecertificate request

Path description (inquotation marks, if

Stdout

SAP AG 1.18.07

spaces exist)

-x <PIN> PIN that protects thePSE

Character string None

None <Distinguished_Name> The DistinguishedName for the SAP WebDispatcher

Character string (inquotation marks, ifspaces exist)

None

Additional Options

Option Parameter Description Allowed Values Default-s <key_len> Key length 512, 1024, 2048 1024

-a <algorithm> Algorithm used RSA, DAS RSA

-noreq None Only generate a key pairand PSE. Do not create acertificate request.

Not applicable Not set

-onlyreq

None Generate a certificaterequest for the public keystored in the PSEspecified by the –pparameter.


The command line below creates the SAP Web Dispatcher’s SSL server PSE andcertificate request using the following information:

9. The environment variable SECUDIR is set to C:\ProgramFiles\SAP\SAPWebDisp\sec.

10. The PSE is to be located at C:\ProgramFiles\SAP\SAPWebDisp\sec\SAPSSLS.pse.

11. The PIN used to protect the PSE is abcpin..

12. The name of the certificate request file is abc.req.

13. The SAP Web Dispatcher is accessed using the fully-qualified host name host123.mycompany.com.

14. The CA used is the SAP CA.

15. Therefore, the server’s Distinguished Name isCN=host123.mycompany.com, OU=I1234567890-MyCompany, 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 WebAS, O=SAP Trust Community, C=DE"

SAP AG 1.18.07

3.5 Sending the Certificate Requests to a CA

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

3.5.2 PrerequisitesYou can send the certificate requests to the CA of your choice, for example, the SAPCA. Note however, the corresponding certificate request response from the CA mustbe 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 thenecessary 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 thesigned public-key certificate. Therefore, you must also have access to the CA’sroot certificate. When using sapgenpse, then it must exist as a file in the filesystem.

3.5.3 ProcedureFor each certificate request that you created, send the contents of the certificaterequest to your CA.

The exact procedure to use depends on the CA that you use. For the SAP CA, followthe instructions provided by the SAP Trust Center Service athttp://service.sap.com/tcs.

The link http://service.sap.com/tcs => SSL Test Server Certificates allows you to createsigned test certificates. You can sign certificates for testing which will be valid for twomonths. In order to create a CA response in format PKCS#7, select “Choose servertype” => 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 doesnot support formatting features, for example, Notepad. If carriage returns or line feedshave been corrupted, for example, during download, then correct these errors.

The example below shows a correct certificate request.

http://service.sap.com/tcs.

http://service.sap.com/tcs

SAP AG 1.18.07

-----BEGIN CERTIFICATE REQUEST-----MIIBkzCCAVICAQAwWjELMAkGA1UEBhMCREUxHDAaBgNVBAoTE215U0FQLmNvbSBXb3JrcGxhY2UxDzANBgNVBAsTBlNBUCBBRzEOMAwGA1UECxMFQmFzaXMxDDAKBgNVBAMTA0JJTzCB7jCBpgYFKw4DAhswgZwCQQCSnauC/cAfQVrmOtWznQ9I+i4twoPq8wCE0Fk5EAVjQnX2oMqBnyoi+ee/ZH2cLwyhp5mOOw70+exS7PHEWKiFAhUAw9FSY1AsFV4U9fC9w+Bg5H4ISYcCQARcC+7q3UkM0TF0A5zRaq7viO3Wj2MwYUNwFkc0hxzhloUQd21megZADoFiisdzkn/nF4eIxV9vq9XxcV63xTsDQwACQFher18UA8YkY4/zHe4mbupBXvDSucm2nbJuQ5PgDBvVaMmtpXIisyzuAFL+qCzQ92mkNqUR9JLWpz09ghQdISCgADAJBgcqhkjOOAQDAzAAMC0CFA7qEluP/Kfi+6HF/8I7j4NfF44xAhUAqkDgAeR3tzmNegKUTQ+JzeCXawE=-----END CERTIFICATE REQUEST-----

3.5.4 ResultThe CA will validate the information contained in the certificate request (according toits 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 UseThe CA will send you a certificate request response that contains the signed public-key certificate for the SAP Web Dispatcher. Once you have received this response,import it into the SAP Web Dispatcher’s corresponding PSE. You can either use thetrust manager or you can use the configuration tool sapgenpse. See the proceduresbelow.

3.6.2 Prerequisites11. 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 theresponses can either exist as a file or you can use Copy&Paste to insert it intothe PSE.

12. If the certificate request responses do not contain the CA’s root certificate,then you also have access to this certificate. If you are using the trust manager,then it must exist in the trust manager’s database. If you are using sapgenpse,then it exists as a file in the file system.

3.6.3 ProcedureYou can use the configuration tool sapgenpse to import the certificate requestresponse into the PSEs. Use the tool’s command import_own_cert as shownbelow.

sapgenpse import_own_cert <Additional_options> -p <PSE_file> -c <Cert_file> [-r<RootCA_cert_file>] -x <PIN>

Where:

Standard Options

Option Parameter Description Allowed Values Default-p <PSE_Name> Path and file name of the

PSE.

The path is theSECUDIR directoryand the file name isSAPSSLS.pse. forthe SSL server PSEor SAPSSLC.pse forthe SSL client PSE(if it exists).

Path description (inquotation marks, ifspaces exist)

None

-c <Cert_file> Path and file name of the Path description (in None

SAP AG 1.18.07

certificate requestresponse

quotation marks, ifspaces exist)

-r <RootCA_cert_file>

File containing the CA’sroot certificate (and anyintermediate CAcertificates). Thisparameter is necessary ifthe CA root and anyintermediate CAcertificates are notincluded in the certificaterequest response.

Path description (inquotation marks, ifspaces exist)

Not set

-x <PIN> PIN that protects the PSE Character string None

3.6.4 ResultThe certificate request response is imported into the PSE.

The following command line imports the certificate request response (ABC.cer) into theSAP Web Dispatcher’s SSL server PSE that is stored at C:\ProgramFiles\SAP\SAPWebDisp\sec\SAPSSLS.pse. (SECUDIR is set to C:\ProgramFiles\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 UseThe SAP Web Dispatcher must have active credentials at run-time to be able toaccess its PSEs. Therefore, to produce active credentials, use the configurationtool’s command seclogin to “open” each PSE.

The credentials are located in the file cred_v2 in the directory specified by theenvironment variable SECUDIR. Make sure that only the user under which the SAPWeb Dispatcher runs has access to this file (including read access).

3.7.2 Prerequisites13. 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 ProcedureUse 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 Parameter Description Allowed Values Default-p <PSE_Name> Path and file name

for the PSE.Path description (inquotation marks, ifspaces exist)

None

-x <PIN> PIN that protects the PSE Character string None

-O [<Windows_Domain>\]<user_ID>

User for which thecredentials are created.(The user that runs theSAP Web Dispatcherprocess.)

If the user that runs theSAP Web Dispatcher isthe current user, then thisparameter is optional.

Use the parameter –v(verbose) to see theresults.

Valid operating systemuser

Thecurrentuser

Additional Options

Option Parameter Description Allowed Values Default-l None List all available

credentials for the currentuser.


-d None Delete credentials Not applicable Not set

-chpin None Specifies that you want tochange the PIN


After creating the credentials, restart the SAP Web Dispatcher.

3.7.4 ResultThe credentials file (cred_v2) for the user provided with the –O option is created inthe SECUDIR directory.

The following command line opens the SAP Web Dispatcher’s SSL server PSE that islocated 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:\ProgramFiles\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 WebDispatcher

3.8.1 UseUse the following test to test the SSL connection to the SAP Web Dispatcher. In thistest, the SAP Web Dispatcher connects to the SAP Web Application Server using aBusiness Server Page (BSP).

3.8.2 Prerequisites15. The SAP Web Dispatcher’s PSEs and credentials exist.

16. The SAP Web Dispatcher has been restarted.

17. You know the port number that the SAP Web Dispatcher is using for HTTPSconnections.

The port number is specified in the profile parameter icm/server_port_<xx>in the SAP Web Dispatcher’s profile.

3.8.3 Procedure2. 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 URLhttps://mywebdisp.mycompany.com:443/sap/bc/bsp/sap/it00/default.htm.

If your Web browser cannot completely verify the SAP Web Dispatcher's public-key certificate, then you will receive a dialog that states the reason why. Forexample, if your Web browser does not possess the issuing CA's root certificateas a trusted root certificate, then you are informed and can choose to trust theserver at this time.

3. If you trust the server's certificate (either automatically or manually), then thenext step is to authenticate yourself.

If your authentication was successful, the page appears.

3.8.4 ResultYou are connected to the SAP Web AS via the SAP Web Dispatcher. SSL is usedfor the connection between your Web browser and the SAP Web Dispatcher, whichis indicated in your Web browser.

https://mywebdisp.mycompany.com:443/sap/bc/bsp/sap/it00/

SAP R/3 und HTTP -18-

SAP AG 1.18.07

3.9 Sample Profile for the SAP Web Dispatcher WhenTerminating 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:\ProgramFiles\SAP\SAPWebDisp\sec\SAPSSLS.pse


SAP AG 1.18.07

3.10 Importing the application server’s certificate to theWeb Dispatcher

This configuration is only used when SSL is used for the communication betweenSAP Web Dispatcher and SAP Web Application Server or between SAP WebDispatcher and SAP Message Server.

Export the SSL certificate of a PSE (e.g. the SSL certificate of the SAP WebApplication Server or the SSL certificate of the SAP Message Server) and import itinto the Web Dispatcher’s client PSE.

Export the server’s certificatesapgenpse export_own_cert -p SAPSSLS.pse -x WASPIN

Save the output to a file WAS.cer and import it to the Web Dispatcher’s clientPSE using the commandsapgenpse.exe maintain_pk -a WAS.cer -p SAPSSLC.pse -x ABCPIN

The opposite direction of importing the Web Dispatcher’s client certificate into theserver PSE is not required, unless the server explicitely requests that a clientcertificate is provided using parameter icm/HTTPS/verify_client=2.

Instead of importing a server’s SSL certificate directly it would also be possible toimport the root certificate of the CA which was used to sign the server’s certificate.This is not described here.

It is possible to use certificates which are not signed by a CA between SAP WebDispatcher and SAP Web Application Server or SAP Web Dispatcher and SAPMessage Server. However, in this case the certificates must be identical. This canbe achieved by copying the server’s server PSE file to the Web Dispatcher clientPSE file.

3.11 Sample Profile for the SAP Web Dispatcher WhenReencrypting SSL and retrieving meta data using SSL

When SSL reencryption is used, the SAP Web Application Server must beconfigured to support SSL.

When meta data is retrieved using SSL, additionally the SAP Message Server mustbe 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

# 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:\ProgramFiles\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

http://www.mycompany.com


SAP AG 1.18.07

4 SAP Web Dispatcher Configuration

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

4.1 How to configure the URL filterTo configure the URL filter you have to set the following profile parameter in theinstance 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 followingcontent:

# URL permission table

P /sap/bc/*

P /sap/public/bsp/*

D *

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 UseFor each Error Code, you can create an HTML page, which is sent to the clientwhen this error occurs. You can define both static pages (ending .html) anddynamic pages (ending .shtml).

Moreover, you can create a file ICMERR-EDEFAULT.{html,shtml} in directoryicm/HTTP/error_templ_path, whose contents are returned if there is no othertemplate for the error.

If external resources (such as images) should be referenced in the error templates,these can be delivered with the ICM’s file access handler. See alsoicm/HTTP/file_access_<xx>.

http://help.sap.com/saphelp_nw2004s/helpdata/en/f5/51c7d170bc4a98b1b5a03392

SAP AG 1.18.07

4.2.2 PrerequisitesTo use dynamic error handling in the ICM or Web dispatcher, you must set theprofile parameter icm/HTTP/error_templ_path to the directory with the errortemplate 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 messagesmust be deactivated. You can set this from the menu: Tools Internet OptionsAdvanced under Browsing.

4.2.3 ProcedureCreate files ICMERR-<error code>.(s)html in the relevant directory for theerror codes you want. You can create static or dynamic error pages.

4.2.3.1 Static Error PagesIf a static error page is defined for an error (ending .html), this is returned to theclient.

4.2.3.2 Dynamic Error PagesThe dynamic pages support the following SSI commands (server-die includes, seehttp://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html).

For the dynamic substitutions, the whole file must be searched for the SSI tags "

You can set the following variables:

Variable Name Meaning

DATE_LOCAL Current time/date: Tue Mar 26 17:15:32 2002

DATE_GMT Current GMT time/date: Tue Mar 26 17:15:32 2002

LAST_MODIFIED The time when the current file was last modified

FILE_SIZE Size of the current file in Bytes

SERVER_SOFTWARE SAP Web Application Server 6.30

SERVER_NAME The name of the server

SERVER_PORT The server port

http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html).

SAP AG 1.18.07

PATH_TRANSLATED URL path (without parameters)

ICM_SERVER Host name and port through which this server canbe reached. For example: Is3022.wdf.sap-ag.de:1080

ICM_INSTANCE Instance name: ls3022_BIN_12

ICM_ERR_CODE Error that occurred (numeric)

ICM_ERR_VERSION ICM version

ICM_ERR_COMPONENT Component

ICM_ERR_MODULE Module Name

ICM_ERR_LINE Line

ICM_ERR_DETAIL 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 iswhy field PATH_TRANSLATED has not been set.

In your page you can write, for example:

<tr><td>Server:</td><td></td></tr>

</tr><tr><td background="http:///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.



Your error page can be framed, for example, by the two INCLUDE statements:



...



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

4.2.4 ExampleYou can find an example of a dynamic error page and the .shtml file in Examplesof a Dynamic Error Page.


SAP AG 1.18.07

4.3 How to display a welcome page

4.3.1 UseThe parameter icm/HTTP/file_access_<xx> determines for which URL prefixes staticfile 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 URLprefix, ‘virtual_root’ is replaced by ‘document_root’. The handler then attempts toread the file from the file system and to send it back to the client.

4.3.2 PropertiesWork area Internet Communication Manager, SAP Web Dispatcher

Unit Character string

Standard value -

Dynamicallychangeable

No

4.3.2.1 Value Range and SyntaxThe parameter has the following syntax:

icm/HTTP/file_access_<xx> = PREFIX=<URL-prefix>, DOCROOT=<rootdirectory 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 offile 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 followingvalues are permitted:

0: Function is inactive – directory contents are notdisplayed.

1: Only the file names are displayed.

2: File names are displayed together with their size anddate last changed.


SAP AG 1.18.07

DIRINDEX Name of file that is to be displayed instead of thedirectory contents.

IGNORE The display of the directory contents can be restricted.Files to which the template applies are not listed.

4.3.2.1.2 Caching

With the option CACHECTRL you can specify the cache time in seconds. This is thelength of time the ICM temporarily stores data for after it has sent the data to theclient. If the same request arrives within this time interval, it is dealt with in thecache.

You can specify the following values for this option: (default is +3600 – that is, onehour)

18. 0 or -1: Files are not passed to the cache.

19. +7200: Files are kept in the cache for two hours.

Note that you have to enter a “+” sign.

4.3.2.2 ExampleYou 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=core *.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 theend). 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 fileindex.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 bedisplayed or the file specified with DIRINDEX (in this example, index.htm).

4.3.2.3 CachingWith the option CACHECTRL you can specify the cache time in seconds. This is thelength of time the ICM temporarily stores data for after it has sent the data to theclient. If the same request arrives within this time interval, it is dealt with in thecache.

You can specify the following values for this option: (default is +3600 – that is, onehour)

20. 0 or -1: Files are not passed to the cache.

21. +7200: Files are kept in the cache for two hours.


SAP AG 1.18.07

Note that you have to enter a “+” sign.

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

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

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

4.4.3 PropertiesWork area Internet Communication Manager, SAP Web Dispatcher

Unit Character string

Standard value -

Dynamicallychangeable

Local and on all servers

4.4.3.1 Value Range and SyntaxThe parameter has the following syntax:icm/HTTP/redirect_<xx> = PREFIX=<URL prefix>[, FROM=<patternfor URL>, FROMPROT=<incoming protocol>, FOR=<pattern for hostname: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 selectedfor which a redirect is to be created:


SAP AG 1.18.07

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 iscreated.

23. FROMPROT:

Value range: http or https. This argument is used to restrict requests to onereceive protocol. If FROMPROT is not specified, a redirect is created for allprotocols.

With the optional parameter FOR you can check whether a redirect is to be createdat 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 HOSTheader field is not set, a redirect is likewise not sent.

The pattern *.sap.com:* matches the HOST header field wassrv.sap.com:80 orwassrv2.sap.com:1080.

If the option FOR is not set, a redirect is executed for any value of the header fieldHOST.

You can use optional parameters PROT, HOST, PORT and TO to set the destination toa different protocol, a different host, a different port, or to a different URL. You canonly specify the port and protocol once you have specified a host name. If youspecify 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 isforwarded. With TO no variable from the URL derived from the incoming URL can becreated.

The default values for PROT, HOST, PORT and TO are values that are set when anincoming request is received. If the options are not set, these values are notchanged for the redirect that is created.

4.4.3.2 ExamplesParameter Value Description

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

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


SAP AG 1.18.07

icm/HTTP/redirect_0 =PREFIX=/,FROM=/mime/*,HOST=mimeserver,PORT=8080

Only requests with specific URLpatterns are redirected to HTTPS

icm/HTTP/redirect_0 =PREFIX=/sap/bc/bex,FROMPROT=http, PROT=https,HOST=px155.sap.com

Only requests with a specific URL areredirected to HTTPS

icm/HTTP/redirect_0 =PREFIX=/, FROM=/sap*,FROMPROT=http, PROT=https,HOST=px155.sap.com

Only specific HTTP requests areredirected to HTTPS

icm/HTTP/redirect_0 =PREFIX=/, FROM=*,FROMPROT=http, PROT=https,HOST=px155.sap.com

All HTTP requests are redirected toHTTPS

icm/HTTP/redirect_0 =PREFIX=/,FROM=/mime/*,FOR=crm.sap.com*,HOST=crmserver, PORT=80

Requests with the URL prefix /mime/and the HTTP header field HOST thatmatches the pattern crm.sap.com:*are redirected to the servercrmserver:80.

4.4.4 More InformationNote the following documentation associated with this parameter:

Generic Profile Parameters with the Ending _<xx>

5 References

5.1 SAP Notes538405 Composite SAP Note on the SAP Web Dispatcher

974284 Patch History 7.00

908097 Install Patches for SAP Web Dispatcher 7.00

552286 Troubleshooting for the SAP Web Dispatcher

634262 Preclarification of SAP Web dispatcher problems


SAP AG 1.18.07

870127 Security recommendations

833960 Requirements for reverse proxies (Application Gateways)

750292 URL Generation in SAP Web AS

597059 License conditions SAP-Cryptographic Library

397175 SAP Cryptographic Software - Export control

5.2 How-To Guideshttp://service.sap.com/nw-howtoguides -> SAP Web Application Server.

configure SAP Web Dispatcher for SSL

www.sdn.sap.com -> Guidelines for Successful Implementation of SAPWeb Dispatcher in Customer Landscapes

5.3 External ReferencesHTTP1.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 Change

28.11.2006 OL 1st version

12.12.2006 OL Added several chapters

17.12.2006 OL Review & New design

8.1.2007 CG Corrections and Additions (sample profile for reencryption)

http://service.sap.com/nw-howtoguides

http://www.sdn.sap.com

http://www.faqs.org/rfcs/rfc1945.html



Web Disp Step by Step Docu

Documents

Transcript of Web Disp Step by Step Docu