Password expiry management for HTTP basic authentication

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:
  1. Password prompt page. This page contains two elements:
    1. 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.
    2. An HTML form for the user to change their password.
  2. 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.