When basic authentication is used for an HTTP connection, CICS® Web support
checks the user ID and password in the external security manager. If the password
has expired, the CICS-supplied utility program DFHWBPW is used to prompt the
user to select a new password. You can customize or replace the pages presented
to the user by DFHWBPW.
DFHWBPW is used only for password expiry management when the TCPIPSERVICE
definition that applies to the request is defined with the BASIC, AUTOREGISTER,
or AUTOMATIC option for the AUTHENTICATE attribute. Although DFHWBPW has a
structure similar to a converter program, it is not part of the normal CICS Web
support processing path, so you do not need to add code to it for any other
purpose. When the user has selected their new password, DFHWBPW restarts the
request submission by redirecting the client to the URL for the original request,
so that the complete processing path for the request occurs as normal.
DFHWBPW presents two Web pages
to the user:
- Password prompt page. This page contains two elements:
- A message about password validity. The initial message displayed to the
user states that the password has expired. If there is a problem with the
user's attempt to change the password (for example, the two supplied copies
of the new password do not match), further messages are displayed to explain
the problem.
- An HTML form for the user to change their password.
- Confirmation and request refresh page. This page confirms that the expired
password has been successfully replaced, and provides a refresh tag and URL
link so that the request can be remade automatically or manually.
DFHWBPW builds these web pages using three CICS document templates, DFHWBPW1, DFHWBPW2,
and DFHWBPW3. The CICS-supplied definitions for these templates define them
as loadable programs: that is, they are of type PROGRAM(DFHWBPW1) and so on.
The definitions are in the CICS-supplied RDO group DFHWEB. You can change
these definitions by copying them to another group and using the RDO ALTER
command to change them so that the templates are derived from a different
source. Alternatively, you can leave the RDO definitions unchanged, and modify
the programs that are loaded instead. The three programs DFHWBPW1, DFHWBPW2,
and DFHWBPW3 are assembler language data-only modules, and their source is
shipped to you in corresponding members of the CICS sample library, SDFHSAMP. You can
modify these samples and reassemble and linkedit them into one of your normal CICS program
libraries that are concatenated into the DFHRPL data definition statement.
Tip: When you code ampersands (&) in Assembler language you have
to type them as double ampersands (&&).
The content and
function of each of the DFHWBPW templates is as follows:
- DFHWBPW1
- Part of the password prompt page. Provides the HTML page heading for the
page, and sets symbols for the possible password validity messages (using
the server-side include technique for setting symbols). The messages convey
the following information to the user:
- message.1
- Password has expired.
- message.2
- The entered userid is invalid.
- message.3
- The two copies of the proposed new password do not match.
- message.4
- The previous password entered (the one that has just expired) is not correct.
- message.5
- The proposed new password is not permitted by the external security manager,
because of password quality rules.
- message.6
- The userid has now been revoked.
The DFHWBPW program selects the appropriate symbol to insert
into the document for the password prompt page. You can customize DFHWBPW1
to change the page heading and title, or alter the <body>
tag to change the page colors or background. You can also change the content
of the message symbols.
- DFHWBPW2
- Part of the password prompt page. Builds an HTML form where the user can
input a user ID, the old (expired) password, and two identical copies of a
proposed new password. You can customize DFHWBPW2 to change the text used
to prompt the user, or otherwise change the layout of the page. However, you
must not modify the contents of the <form> tag, or
any of the <input> tags. If you do, DFHWBPW may not
work as intended.
- DFHWBPW3
- Confirmation and request refresh page. The text notifies the user that
the expired password has been successfully replaced, and explains that the
user will shortly be prompted by the client to enter the password again, and
that the new password should then be re-entered. You can customize the text
and layout of the page.
DFHWBPW3 is designed to restart the request process.
It contains a <meta http-equiv="Refresh"> tag that
causes an automatic redirection after ten seconds to the page that the user
had originally requested when the expired password was detected. You can change
the time limit on this tag or remove it altogether if you do not want users
to be redirected automatically. However, the modified page should always contain
a link forward to the originally requested page. The URL for that page is
in the symbol &dfhwbpw_target_url; . Restarting the request
process means that if the Web client has cached the old password, this can
be replaced with the new password right away, and also means that the CICS Web
support processing path is unaffected.