X.509-Based Logon to NetWeaver AS from SAP Web Dispatcher

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:

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.
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-encoded data, one line, 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 Note

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

End of the note.

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).
Syntax
The parameter must contain the whole character string of the certificate. So if the certificate 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 as this.

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
End of the code.
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). We recommend that you do not use this operation mode. Set this parameter only after careful consideration of the security risks. 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.
  
  End of the caution.
- 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). We recommend that you do not use this operation mode. Only set this parameter to TRUE after carefully considering the security risks. 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.
  
  End of the caution.
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.

Example

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.

This graphic is explained in the accompanying text.

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.

More Information

SAP Web Dispatcher and SSL

Establishing Trust

End-to-End SSL

Memory Pipes and MPI Buffers