How-To install&configure the SAP Web DispatcherLast 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 6 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 Dispatcher’s 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 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=<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 Dispatcher’s 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 tool’s command get_pse as shown below to create the SAP Web Dispatcher’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 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 Dispatcher’s 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 server’s 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 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. 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 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 <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 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. 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 Dispatcher’s 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 tool’s 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 Dispatcher’s 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 Dispatcher’s 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 Dispatcher’s 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 server’s 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 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 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.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 ICM’s 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