Web Disp Step by Step Docu

How-To install&configure the SAP Web Dispatcher

Last modification: 18. January 2007

Oliver Luik / Christian Goldbach

1

INTROD INTRODUCTI UCTION ON ................................................................................................................................. 4

2

SAP WEB DISPATC DISPATCHER HER INSTALL INSTALLATI ATION ON WITH SAPINS SAPINST T .......................................................... 4

3

SSL INSTALL INSTALLATIO ATION N AND CONFIGU CONFIGURATI RATION................................................................................ ON................................................................................ 4

3. 1 THE SAP SAP CRYPTOGRAPHIC LIBRARY INSTALLATION PACKAGE .......................................................... 5 3.1.1 Definition Definition .................................................................................................................................. 5 3.1.2 Structu Structure.................................................................................................................................... re.................................................................................................................................... 5 3. 2 3.2.1 3.2.2

INSTALLING THE SAP SAP CRYPTOGRAPHIC LIBRARY .................................................................... 5 Proced Procedure.................................................................................................................................. ure.................................................................................................................................. 5 Result ........................................................................................................................................ 6 

3. 3

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

3. 4 3.4.1 3.4.2 3.4.3

CREATING THE PSES AND CERTIFICATE REQUESTS.................................................................. 8 Use ............................................................................................................................................ 8 Prerequisites.............................................................................................................................. Prerequisites.............................................................................................................................. 8 Proced Procedure.................................................................................................................................. ure.................................................................................................................................. 9

3. 5 3.5.1 3.5.2 3.5.3 3.5.4

SENDING THE CERTIFICATE REQUESTS TO A CA .................................................................... 10 Use .......................................................................................................................................... 10 Prerequisites............................................................................................................................ Prerequisites............................................................................................................................ 11 Procedur Proceduree ................................................................................................................................ 11 Result ...................................................................................................................................... 12

3. 6 3.6.1 3.6.2 3.6.3 3.6.4

IMPORTING THE CERTIFICATE REQUEST RESPONSES .............................................................. 13 Use .......................................................................................................................................... 13 Prerequisites............................................................................................................................ Prerequisites............................................................................................................................ 13 Procedur Proceduree ................................................................................................................................ 13 Result ...................................................................................................................................... 14

3. 7 3.7.1 3.7.2 3.7.3 3.7.4

CREATING CREDENTIALS FOR THE SAP SAP WEB DISPATCHER..................................................... 14 Use .......................................................................................................................................... 14 Prerequisites............................................................................................................................ Prerequisites............................................................................................................................ 14 Procedur Proceduree ................................................................................................................................ 14 Result ...................................................................................................................................... 15

3. 8 3.8.1 3.8.2 3.8.3 3.8.4

TESTING THE SSL SSL CONNECTION TO THE SAP SAP WEB DISPATCHER ............................................ 16 Use .......................................................................................................................................... 16  Prerequisites............................................................................................................................ Prerequisites............................................................................................................................ 16  Procedur Proceduree ................................................................................................................................ 16  Result ...................................................................................................................................... 16 

3. 9 3.10

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

SAP WEB DISPATC DISPATCHER HER CONFIGU CONFIGURATI RATION................................................................................. ON................................................................................. 20

4. 1

CONFIGURING THE WEB DISPATCHER WEB ADMINISTRATION INTERFACE . ERROR! BOOKMARK

NOT DEFINED.

4. 2

SAP AG

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

1.18.07

4. 3 SETTING UP YOUR OWN ERROR PAGES ................................................................................. 20 4.3.1 Use .......................................................................................................................................... 20 4.3.2 Prerequisites............................................................................................................................ Prerequisites............................................................................................................................ 21 4.3.3 Procedur Proceduree ................................................................................................................................ 21 4.3.3.1 4.3 .3.1 Static Static Error Error Pages Pages ...... ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ...... 21 4.3.3.2 4.3 .3.2 Dynamic Dynamic Error Error Page Pages..... s........... ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ......... ... 21 4.3.4 Example................................................................................................................................... Example................................................................................................................................... 22 4. 4 HOW TO DIS PLAY A WELCOME PAGE ...................................................................................... 23 4.4.1 Use .......................................................................................................................................... 23 4.4.2 Properties................................................................................................................................ Properties................................................................................................................................ 23 4.4.2.1 4.4 .2.1 Value Value Rang Range e and and Syntax Syntax...... ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ......... ... 23 4.4.2.2 4.4 .2.2 Exampl Example e ...... ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ......... ... 24 4.4.2.3 4.4 .2.3 Cachin Caching........... g................. ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ........... ..... 24 4. 5 HOW TO CONFIGURE AUTOMATIC REDIRECTS TO HTTPS........................................................ HTTPS........................................................ 25 4.5.1 Use .......................................................................................................................................... 25 4.5.2 Integrat Integration............................................................................................................................... ion............................................................................................................................... 25 4.5.3 Properties................................................................................................................................ Properties................................................................................................................................ 25 4.5.3.1 4.5 .3.1 Value Value Rang Range e and and Syntax Syntax...... ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ......... ... 25 4.5.3.2 4.5 .3.2 Exampl Examples es ...... ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ............ ........ 26 4.5.4 More Informatio Information n .................................................................................................................... 27  5

REFEREN REFERENCES CES .................................................................................................................................... 27

5. 1 5. 2 5. 3 6

SAP NOTES ................................................................................................................................... 27 HOW-TO GUIDES ........................................................................................................................... 28 EXTERNAL REFERENCES ................................................................................................................ 28

HISTORY 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 Thi Thissecti ction des describe cri best he ins inst all at ion of the t he SAPWeb Dis Dispat pat cher cher wit wi t h SAPinst. It It can te t echnica chni cal ly bedone on the t he same server asthe We Web AS. Th Thesetup on t he same server isfor securi cur it y re r easons only onl y re r ecomme commende nded for for demo/ demo/iinte nt ernal syst yst ems. ms. In I n a product productiive set up t he SAPW APWeb Dispatcher and the t he We Web ASshould ASshoul d besepar parated 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 t he SAP Web Dispatcher is to pass the SSL connection to the server in the backend (End-to-End SSL), SSL), then set the parameter icm/server_port_ to PROT=ROUTER, PORT=, TIMEOUT=.

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.

The SAP Cryptographic Library ( sapcrypto.dll for Windows NT or libsapcrypto. for UNIX) 

2.



A corresponding license ticket ( ticket)

3.



The configuration tool sapgenpse.exe

3.2 3. 2

Inst Insta allin lling g the the SA SAP P Cr Cry yptog ptogrraphi aphic c Libr ibrar ary y

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

3.2.1 Procedure As user adm : 1. Extract Extract the contents contents of the SAP SAP Cryptographic Cryptographic Library installation package. package. 2. Cop Copy y the the library library file and and the the conf configura iguration tion too tooll 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//SYS/exe/run/

Location of SAP Cryptographic Library:

/usr/sap//SYS/exe/run/ /usr/sap//SYS/exe/run/libsapcrypto.s libsapcrypto.so o Windows NT:

SAP AG

1.18.07

3.



DIR_EXECUTABLE: :\usr\sap\\SYS\exe\run\

4.



Location of SAP Cryptographic Library:

:\usr\sap\\SYS\ :\usr\sap\\SYS\exe\run\sapcry exe\run\sapcrypto.dll pto.dll

3. Check the file file permissions permissions for the SAP Cryptographi Cryptographic c Library. Library. If, for 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 adm (or SAPServiceunder 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.



DIR_INSTANCE: /usr/sap//

6.



Location of the ticket:

/usr/sap///sec/ticket Windows NT:

7. 8.

DIR_INSTANCE: :\usr\sap\\





Location of the ticket:

:\usr\sap\\\sec\ticket ket

5. Set Set the the env enviro ironm nmen entt v vari ariab able le 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 t he environment variable using the command line, then the value v alue 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 (W indows 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 3. 3

Sett etting ing the the SSL SSL Pr Profil ofile e Pa Para ram meter eters s for for th the SA SAP Web Web Dispatcher

In addition to the standard parameters used by the SAP Web Dispatcher, set the following SSLrelevant parameters. 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//SYS/profile (:\usr\sap\\SYS\profile on Windows), the name of the profile file is __.

1. Location of the SAP Cryptographic Library and Personal Security Environments Environments to use: ssl/ssl_lib= ssl/server_pse= 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_=PROT=H icm/server_port_=PROT=HTTPS, TTPS, PORT=, PORT=, TIMEOUT=900 icm/HTTPS/verify_client= Documentation for parameter icm/HTTPS/verify_client icm/HTTPS/verify_client

5.

Connection Parameters Parameters to the SAP Web AS Message Server in the backend rdisp/mshost= ms/https_port= if you want to use

Metadata Exchange Using SSL. SSL . Otherwise, use ms/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. Displ ay. 6.

Parameter for Client Protocol wdisp/add_client_protocol_h wdisp/add_client_protocol_header=

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=

Documentation for wdisp/ssl_encrypt wdisp/ssl_auth=

Documentation for wdisp/ssl_auth wdisp/ssl_cred=

This parameter is only necessary if wdisp/ssl_auth = 2. Documentation for wdisp/ssl_cred wdisp/ssl_certhost=

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 3. 4

Crea eati ting ng the the PSEs SEs and and Ce Cerrtific ificat ate e Re Requ que ests sts

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 Dispatcher’s SSL server PSE. 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. 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 t he 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 Dispatcher’s 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=, OU=I-, 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 Dispatcher’s PSEs. Before you can use sapgenpse to create the SSL server PSE, the environment envi ronment variable SECUDIR must be set to the directory where the license ticket is located. If the environment variable v ariable is not yet set, then set it using the command line as shown below.

Setting the environment variable v ariable SECUDIR on Windows: set SECUDIR=

On Unix systems the syntax for f or setting environment variables is dependent dependent on the Unix shell.

Use the tool’s tool’ s command get_pse as shown below to create the SAP Web Dispatcher’s PSE. sapgenpse get_pse -p -r -x

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

Where: Standard Options Option

Parameter

Description

Allowed Values

Default

-p



Path and file name for the PSE.

The file name must correspond correspond to the file f ile 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).

None

Path description (in quotation marks, if

Stdout

If the complete path is not included, then the PSE file is created in the SECUDIR directory.

-r

SAP AG



File name for the certificate request request

1.18.07

spaces exist) -x



PIN that protects the PSE

Character string

None

None



The Distinguished Name for the SAP Web Dispatcher

Character string (in quotation marks, if spaces exist)

None

Additional Options Option

Parameter

Description

Allowed Values

Default

-s



Key length

512, 1024, 2048

1024

-a



Algorithm used

RSA, DAS

RSA

-noreq

None

Only generate a key pair and PSE. Do not create a certificate request. request.

Not applicable

Not set

-only req

None

Generate a certif icate request request for the public key stored in the PSE specified by the –p parameter.

Not applicable

Not set

The command line below creates the SAP W eb Dispatcher’s Dispatcher’s SSL server PSE and certificate request using the following information:

9.

The environment variable SECUDIR is set to C:\Program Files\SAP\SAPWebDisp\sec.



10. 

The PSE is to be located at C:\Program

Files\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 fullyqualified host name host123.mycompany.com. 14. 

The CA used is the SAP CA.

15. 

Therefore, the server’s Distinguished Name is

CN=host123.mycompany.com, CN=host123.mycompany.com, OU=I1234567890OU=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 Trust Community, Community, C=DE"

SAP AG

1.18.07

3.5

Sendin ding th the Ce Certific ica ate Re Requests to 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 r esponse in this thi s 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 CA’s 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.. 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 v alid for two months. In order to create a CA response in format PKCS#7, select “Choose server type” => PKCS#7 certificate chain.

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

The example below shows a correct certif icate request.

SAP AG

1.18.07

-----BEGIN CERTIFICATE REQUEST----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 3. 6

Impor mportting ing the Cer erti tifi fica cate te Re Req quest uest Re Resp spo onse ses s

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 Dispatcher’s 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 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 Procedure You can use the configuration tool sapgenpse to import the certificate request response into the PSEs. Use the tool’s command import_own_cert as shown below. sapgenpse import_own_cert import_own_cert -p -c [-r ] ] -x

Where: Standard Options Option

Parameter

Description

Allowed Values

Default

-p



Path and file name of the PSE.

Path description (in quotation marks, if spaces spaces exist) ex ist)

None

Path descrip cripti tio on (in

Non No ne

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). exists). -c

SAP AG



Path and file file name of the the

1.18.07

certificate request request response

quotation marks, if spaces spaces exist) ex ist)

-r



File containing the CA’s 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.

Path description (in quotation marks, if spaces spaces exist) ex ist)

Not set

-x



PIN that protects the PSE

Character string

None

3.6.4 Result The certificate request response is imported into the PSE. The following command line li ne imports the certificate certif icate request response response (ABC.cer) into the SAP Web W eb Dispatcher’s SSL server 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 3. 7

Cre reat atin ing g Cr Credenti ential als s fo for the the SAP Web Web Dis isp patche tcherr

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 tool’s command command seclogin to “open” each PSE. The credentials are are located in the file fi le 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 f ile (including (i ncluding read access). 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.



SAP AG

You know the user that runs the SAP Web Dispatcher.

1.18.07

3.7.3 Procedure Use the following command line to open each PSE and create credentials. sapgenpse seclogin seclogin -p -x -O [\]

Where: Standard Options Option

Parameter

Description

Allowed Values

Default

-p



Path and file name for the PSE.

Path description (in quotation marks, if spaces exist)

None

-x



PIN that protects the PSE

Character string

None

-O

[\]

User for which the credentials are created. (The user that runs the SAP Web W eb Dispatcher process.)

Valid operating system user

The current user

If the t he 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

Parameter

Description

Allowed Values

Default

-l

None

List all av ailable credentials for the current user.

Not applicable

Not set

-d

None

Delete credentials

Not applicable

Not set

-chpin

None

Specifies that you want to change the PIN

Not applicable

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 Dispatcher’s SSL server server PSE that t hat 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 - O ABCadm

SAP AG

1.18.07

3.8

Testi sting th the SSL Co Connecti ction to th the SA SAP We 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.



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 HTTPS connections. The port number is specified in the profile parameter icm/server_port_ in the SAP Web Dispatcher’s profile.

3.8.3 Procedure 2.

Start Start a BSP BSP usin using g an HTTPS HTTPS conn connec ection tion to your your SAP Web Dispa Dispatch tcher er and and the the corresponding SSL port. For example, start the standard standard BSP test t est 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 you trus trustt the the serve server's r's certif certifica icate te (eithe (eitherr autom automatic atically ally or manu manually ally), ), then then the 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

3.9 3. 9

-18-

Sampl ample e Pr Profil ofile e fo for the the SA SAP P Web Web Dis Dispa pattche cher When 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 Cryptographic Library can # find the sec sub-directory. DIR_INSTANCE = C:\Program Files\SAP\SAPWebDisp Files\SAP\SAPWebDisp

# Message Server Description rdisp/mshost = abcmain ms/http_port = 8081

# Description of the Access Points icm/server_port_0 icm/server_port_0 = PROT=HTTP, PORT=1081, TIMEOUT=900 icm/server_port_1 icm/server_port_1 = PROT=HTTPS, PORT=1443, TIMEOUT=900 icm/HTTPS/verify_client icm/HTTPS/verify_client = 0

# Parameters for the SAP Cryptographic Library ssl/ssl_lib = C:\Program Files\SAP\SAPWebDisp\sapcrypto.dll Files\SAP\SAPWebDisp\sapcrypto.dll ssl/server_pse ssl/server_pse = C:\Program Files\SAP\SAPWebDisp\sec\SAPSSLS.pse

SAP AG

1.18.07

SAP R/3 und HTTP

-19-

3.10 3. 10 Impo Import rtin ing g the the appli pplica cattion ion ser serve verr’s ce cert rtif ific icat ate e to to the 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 Dispatcher’s client PSE. Export the server’s certificate sapgenpse export_own_cert -p SAPSSLS.pse -x WASPIN

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

The opposite direction of importing the Web Dispatcher’s client certificate into the server PSE is not required, unless the server explicitely requests that a client certificate is provided using using parameter parameter icm/HTTPS/verify_client=2. Instead of importing a server’s SSL certificate directly it would also be possible to import 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 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 server’s server PSE file to the Web Dispatcher client PSE file.

3.1 .11 1 Samp Sample le Prof Profil ile e for for the the SA SAP Web Web Dis ispa pattche cher Whe When n 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

SAP AG

= ABC

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 Cryptographic Library can # find the sec sub-directory. DIR_INSTANCE = C:\Program Files\SAP\SAPWebDisp Files\SAP\SAPWebDisp

# Message Server Description rdisp/mshost = abcmain ms/https_port = 8443

# Description of the Access Points icm/server_port_0 icm/server_port_0 = PROT=HTTP, PORT=1081, TIMEOUT=900 icm/server_port_1 icm/server_port_1 = PROT=HTTPS, PORT=1443, TIMEOUT=900 icm/HTTPS/verify_client icm/HTTPS/verify_client = 0

# Parameters for the SAP Cryptographic Library ssl/ssl_lib = C:\Program Files\SAP\SAPWebDisp\sapcrypto.dll Files\SAP\SAPWebDisp\sapcrypto.dll ssl/server_pse ssl/server_pse = C:\Program Files\SAP\SAPWebDisp\sec\SAPSSLS.pse

# Parameters for Using SSL to the backend server wdisp/ssl_encrypt wdisp/ssl_encrypt = 2 wdisp/ssl_auth wdisp/ssl_auth = 2 wdisp/ssl_cred wdisp/ssl_cred = SAPSSLC.pse wdisp/ssl_certhost 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 wdisp/permission_table = $(DIR_DATA)/perm.txt $(DIR_DATA)/perm.txt

and create a textfile named perm.txt in the instance data directory with the following content: # 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 Use For each Error Code, 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 ICM’s file access handler. See also icm/HTTP/file_access_.. icm/HTTP/file_access_

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 Advanced  under Browsing.

4.2.3 Procedure Create files ICMERR-.(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 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 whole file fil e 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 ime when the current file ile was last modified

FILE_SIZE

Size of the current file in Bytes

SERVER_SO _SOFTWA FTWAR RE

SAP SAP Web Web App Appli lica cati tion on Serv Server er 6.30 6.30

SERVER_NAME

The name of the server

SERVER_PORT

The server port

SAP AG

1.18.07

SAP R/3 und HTTP

-23-

PATH_TR _TRANSLAT LATED

URL pa path (w (withou thoutt pa param rameters) rs)

ICM_SERVER

Host name and port through which this server can be reached. For example: Is3022.wdf.sapag.de:1080

ICM_INSTANCE

Instance name: ls3022_BIN_12

ICM_ERR_CODE

Error that occurred (numeric)

ICM_ERR_VERSION

ICM version

ICM_ ICM_ER ERR_ R_COM COMPO PONE NENT NT Co Com mpo pone nent nt ICM_ERR_MODULE

Module Name

ICM_ERR_LINE

Line

ICM_ERR_DETAIL

Detail on 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, write, for f or example: Server: