Show TOC

X.509-Based Logon to NetWeaver AS from SAP Web DispatcherLocate this document in the navigation structure

Use

Introduction

With end-to-end SSL the SAP Web Dispatcher does not terminate the SSL data stream. The client certificate is extracted (after SSL termination) in the ICM of the application server and transported to the application server (AS ABAP or AS Java). The client certificate of the user can be used to log on to the application server.

But if the SAP Web Dispatcher does terminate SSL, the (public) certificate of the user will be in the Web Dispatcher unpacked, and has to be passed securely to the application server.

To use the X.509 client certificate on the application server for logging on, it has to be transported (over a secure channel) to the ICM of the application server.

The certificate data has to be written from the Web Dispatcher to the HTTP header.

There are the following use cases for the application server:

  1. The client is directly connected with the ICM of the application server through a Web Dispatcher that is configured for end-to-end SSL. In this case the certificate data of the SSL connection is used for the logon.

  2. The Web Dispatcher terminates SSL and forwards the certificate data in the HTTP request header. We strongly recommend that you configure SSL termination with re-encryption in order to transfer certificate data securely.

    To create a trust relationship between the Web Dispatcher and ICM, the Web Dispatcher requires an X.509 client certificate for the SSL connection to the ICM.

Problem

If the Web Dispatcher sets the SSL header fields, and uses a client certificate for ICM authentication, the ICM is not permitted to use this certificate for user authentication of the client.

Solution

If the ICM of the application server receives SSL information via HTTP header fields, they have a higher priority than certificate data from the SSL connection. The Web Dispatcher must always add header fields if the connection between client and Web Dispatcher was SSL-encrypted.

Implementation

Data Transfer and Formats

The Web Dispatcher can add the following HTTP header fields (SSL header fields) to an HTTP request.

Name of Header Field

Value

Format

SSL_CLIENT_CERT

Client certificate

Base64-coded data, one row, no additions ( -----BEGIN..., -----END..., no formatting ( CR, LF, HT

,...)

SSL_CLIENT_CERT_CHAIN_1

First non-root CA certificate issued by the client.

Same as SSL_CLIENT_CERT

SSL_CLIENT_CERT_CHAIN_n

Last non-root CA certificate

Same as SSL_CLIENT_CERT

SSL_CLIENT_CERT_CHAIN_n+1

This element is the corresponding root certificate It must not be transferred to the server.

Same as SSL_CLIENT_CERT

SSL_CIPHER_USEKEYSIZE

Number of encryption bits actually used

Numeric decimal value transferred as a string (for example, 0, 40, 56, 128, 168)

SSL_CIPHER_SUITE

Cipher suite in accordance with the definition in the SSL and TLS specification (draft free ssl version 3-02 or RFC 2246)

The cipher suite consists of two numerical 8 bit values (SSL 3.0 / TLS).

Mutual Trust Between SAP Web Dispatcher and ICM on Application Server

The trusted relationship between the SAP Web Dispatcher and the ICM is based on a client certificate, which the Web Dispatcher uses for the SSL connection. The ICM uses this Web Dispatcher certificate to decide whether the “intermediate” server is trustworthy or not.

Note

This client certificate must not be used for user authentication in the application server.

The first server in the chain of network stations that terminates the SSL connection from the browser must add the SSL header fields to the HTTP request. Subsequent stations in the chain must forward this information to the application server where it is needed for user authentication.

The SSL header fields contain security-critical data that is used to log on to the application server without additional checks. To avoid manipulation of this data, it must be transferred securely.

For this reason each station in the chain (the application server and all “intermediates”) must be able to trust their predecessor.

Security Measures in the SAP Web Dispatcher and ICM

The following actions should guarantee security when certificates are forwarded:

  • With incoming HTTP requests any SSL header fields that may have been set are deleted.

  • If the intermediate server is not trustworthy, any SSL header fields that may have been set are deleted.

Configuration

Configure the trust relationship in the ICM of the application server and the Web Dispatcher.

  • ICM Configuration

    In the ICM profile set the following parameters to specify the Web Dispatcher as the “trusted intermediate”:

    icm/HTTPS/trust_client_with_issuer = <issuer>

    icm/HTTPS/trust_client_with_subject = <subject>

    If <subject> and <issuer> of the Web Dispatcher client certificate are the same as these values, the ICM accepts the SSL header fields. If they are not the same, the ICM deletes them.

    If the SSL header fields are not set, the HTTPS request carries its own certificate and this is used to log on to the application server (direct connection from the browser to the application server, or end-to-end SSL).

    The parameter must contain the whole character string of the certificate. If the certificate also contains the issuer CN=SAP CA, O=SAP CA INT, C=DE and the subject CN=sapwebdisp, O=SAP-AG, C=DE, the parameters must be set exactly in this way.

    Each character, including spaces, must match exactly.

    To simplify the configuration, wildcards can be used:

    • * stands for any number of characters:

    • ? stands for one character

    The following settings in the ICM are possible, but for security reasons, are not recommended.

    • Accept certificate without trusted relationship

      A special case is the following:

      icm/HTTPS/trust_client_with_issuer = *

      icm/HTTPS/trust_client_with_subject = *

      This means that any certificate that matches one of the configured root CAs (“Trust Anchors”) is accepted as a client certificate. It is even accepted if the client does not send an X.509 certificate.

      Caution

      This means that there is no longer a mutual trust specified between the ICM and Web Dispatcher (or other load balancers). SAP recommends that you do not use this operation mode. Only set this parameter after weighing up the security risks carefully. With this operation mode, anyone who can send an HTPS request directly to the ICM can pass any SSL client certificate to the application without additional checks.

    • Accept unencrypted forwarded certificates

      You can configure the ICM so that it also accepts a client certificate that was forwarded over HTTP (not HTTPS). To do this set parameter:

      icm/accept_forwarded_cert_via_http = TRUE

      Caution

      This removes the trust relationship and the associated security measures (deletion of header fields for unencrypted HTTP requests). SAP recommends that you use this operation mode. Only set this parameter to TRUE after weighing up the security risks carefully. With this operation mode, anyone who can send an unencrypted HTP request directly to the ICM can pass any SSL client certificate to the application without additional checks.

  • Web Dispatcher configuration

    In the profile of the SAP Web Dispatcher you have to set parameters to terminate SSL and to re-encrypt data.

    More information: SAP Web Dispatcher and SSL

    You have to set the parameters below to encrypt the request with SSL again.

    wdisp/ssl_encrypt=2

    wdisp/ssl_auth=2

    wdisp/ssl_cred= <file_name_of_client_PSE>

    The client certificate of the Web Dispatcher is specified with file <file_name_of_client_PSE> . The trusted connection between the ICM and application server is created with this certificate.

    Set the parameters below to transfer the user certificate to the header fields:

    icm/HTTPS/forward_ccert_as_header = true

    In this case the Web Dispatcher behaves as follows:

    • If no SSL header field is set in the incoming request, and the Web Dispatcher trusts the predecessor, all the SSL header fields described above are set in the HTTP request. If the client is not trusted, all the following SSL header fields are set: SSL_CIPHER_SUITE und SSL_CIPHER_USEKEYSIZE.

    • If the Web Dispatcher receives one of the SSL header fields described above, no information from the SSL connection is added to the SSL header fields. If the predecessor is not trusted, the Web Dispatcher removes all SSL header fields.

The following figure shows an example of the ICM and Web Dispatcher configuration, which enables users to log on from the browser to their client certificate in the application server.

Figure 1: Example Configuration

Cascading SAP Web Dispatchers

You can activate several SAP Web Dispatchers (“intermediates”) one after the other. In this case each node that is to accept the SSL header fields has to trust its direct predecessor. You can control this using parameters icm/HTTPS/trust_client_with_issuer and icm/HTTPS/trust_client_with_subject for the Web Dispatcher (see above).

For more information about the cascading of Web Dispatchers, refer to SAP Note 740234 Information published on SAP site.