PQ77887: Documentation needs to be changed to better explain what private headers are used for when using Form Based Login

APAR status
Closed as documentation error.

Error description
The documentation for W401500 (WebSphere HTTP Plug-in for z/OS
APAR 
PQ68250, Service Level W401500) states that
BBOC_HTTP_(SSL_)MODE=
INTERNAL is needed "only if you intend to use private headers."
It
further states that "If you try to use private headers without
adding
this variables (sic.) to the current.env file, . . .WebSphere
for z/OS
might not be able to locate the requested application."  Also, a
note
says "If you add these environment variables to the current.env
file,
the HTTP(S) Transport Handler will trust all private headers it
receives.  Therefore, you must ensure that there are no
untrusted
paths to the HTTP(S) Transport Handler."
The documentation does not explain what information flows in the
private headers.
For the Web server plug-ins on non-z/OS Web servers, the only
data that we know of that flows in private headers is client
certificates.
It appears, however, that the HTTP Plug-in for z/OS also places
prot and protocol (http or https) information ONLY in private
headers.  This means that even for trivial configurations, it is
necessary to set BBOC_HTTP_(SSL_)MODE=INTERNAL, opening a
security
exposure that may not be trivial to close.
We have found the following problems when MODE=INTERNAL is not
specified:
- If the IBM HTTP Server is listening on a port other than 80,
and
webcontainer.conf contains a virtual host alias that maps to the
HTTP Server's port, but does not contain a virtual host alias
that
maps to port 80, HTTP requests will result with a 404 response.
This
would appear to be because the Web container does not receive
information about the port in the original URL, and tries to
match
the host without a port number (defaulting to 80).
- If the Transport Handler does not happen to be listening on
port 80,
Form Based authentication (and other techniques involving
redirection)
do not work.  This appears to be because the request for a
protected
resource reaches the Transport Handler without port information
(except
in the ignored private headers).  When the Web container
redirects
to the login form, it does not include a port number in the
redirect,
and, since no one is listening on port 80, the login form cannot
be
found.
- If a browser connects to the IBM HTTP Server via SSL (HTTPS),
any
redirection or url rewriting will cause subsequent requests to
go
via non-ssl sessions, since the Web container seems to be
unaware that
the connection with the HTTP Server was via https.  This is
especially
dangerous when the response includes a form on which the user is
supposed to enter private or confidential information.
None of these problems appear to exist with the distributed
plug-in,
even when MODE=INTERNAL is not specified.
If this situation represents the intended design of the z/OS
plug-in,
then the documentation needs to be much more explicit about the
need for MODE=INTERNAL, and about preventing unsecured paths.
Local fix
n/a
Problem summary
****************************************************************
* USERS AFFECTED: All users of WebSphere Application Server    *
*                 V4.0.1 for z/OS and OS/390                   *
****************************************************************
* PROBLEM DESCRIPTION: When using Form Based authentication    *
*                      for security, if the HTTP Host header   *
*                      field does not contain port             *
*                      information, HTTP requests will fail    *
*                      with a response code of 404 if the      *
*                      BBOC_HTTP_SSL_MODE=INTERNAL             *
*                      environment variable is not included    *
*                      in the current.env file.                *
*                                                              *
*                      Also, if the connection between a       *
*                      browser and the IBM HTTP Server are not *
*                      the same type as the connection between *
*                      the WebSphere HTTP Plug-in for z/OS and *
*                      the HTTP Transport Handler (both either *
*                      HTTP or HTTPS), any redirection or URL  *
*                      rewriting will cause subsequent         *
*                      requests to fail with a 404 error code. *
****************************************************************
* RECOMMENDATION:                                              *
****************************************************************
The information about using the WebSphere HTTP Plug-in contained
in "WebSphere Application Server V4.0.1 for z/OS and OS/390:
Assembling J2EE Applications" does not mention that:
  1. If you are using HTTP 1.0 protocol, and Form Based
     authentication (or some other technique that involves
     redirection) for security, you must include the
     BBOC_HTTP_SSL_MODE=INTERNAL environment variable in the
     current.env file.
  2. The connection between a browser and the IBM HTTP Server
     must be the same type as the connection between the
     WebSphere HTTP Plug-in for z/OS and the HTTP Transport
     Handler; both must be either HTTP or HTTPS.
Problem conclusion
The information about the WebSphere HTTP Plug-in for z/OS
contained in "WebSphere Application erver V4.0.1 for z/OS and
OS/390: Assembling J2EE Applications" states that the
environment variable BBOC_HTTP_(SSL_)MODE=INTERNAL is needed
"only if you intend to use private headers." It further states
that "If you try to use private headers without adding this
variable to the current.env file, WebSphere for z/OS might
not be able to locate the requested application." "WebSphere
Application Server V4.0.1 for z/OS and OS/390: Assembling J2EE
Applications" does not explain:
  1. If you are using HTTP 1.0 protocol, and Form Based
     authentication (or some other technique that involves
     redirection) for security, you must include the
     BBOC_HTTP_SSL_MODE=INTERNAL environment variable in the
     current.env file.
  2. The connection between a browser and the IBM HTTP Server
     must be the same type as the connection between the
     WebSphere HTTP Plug-in for z/OS and the HTTP Transport
     Handler; both must be either HTTP or HTTPS.
Temporary fix Comments
APAR information
APAR number PQ77887
Reported component name WEBSPHERE OS/39
Reported component ID 5655A9800
Reported release 401
Status CLOSED DOC
PE NoPE
HIPER NoHIPER
Submitted date 2003-08-27
Closed date 2003-10-29
Last modified date 2003-10-29

APAR is sysrouted FROM one or more of the following:

APAR is sysrouted TO one or more of the following:

Modules/Macros

Fix information

Applicable component levels


Document Information


Product categories: Software > Application Servers > Distributed Application & Web Servers > WebSphere Application Server for z/OS
Operating system(s):
Software version: 401
Software edition:
Reference #: PQ77887
IBM Group: Software Group
Modified date: Oct 29, 2003