HTTP client sample exit programs (DFH$WB*)

This program, whose purpose is to initialize the supplied Web-related global user exits, is specified in the PLTPI and is invoked during the CICS post-initialization phase. It is specified with the INITPARM system initialization parameter as follows:

INITPARM=(DFH$WBPI='PROXY=proxyurl,LDAPBIND=profilename,STS=sts-server-url')

where

PROXY=proxyurl

This optional keyword stores the URL (in the form http://proxyserver) of a proxy server into the Web global work area, then enables the supplied DFH$WBEX sample program as the XWBOPEN global user exit.

LDAPBIND=profilename

This optional keyword stores the name of an LDAP bind profile into the Web global work area, then enables the supplied DFH$WBX1 sample program as the XWBAUTH global user exit.

Note that you cannot specify both LDAPBIND and STS. To do so causes DFH$WBPI to abend with code WBPI. Message DFHSI1580D is issued, which may cause CICS to be terminated.

STS=sts-server-url

This optional keyword stores the URL (usually in the form https://sts-server) of a Secure Token Service into the Web global work area, then enables the supplied DFH$WBX2 sample program as the XWBAUTH global user exit.

Note that you cannot specify both STS and LDAPBIND. To do so causes DFH$WBPI to abend with code WBPI. Message DFHSI1580D is issued, which may cause CICS to be terminated.

Note that the total length of the INITPARM quoted text cannot exceed 60 characters.

If all the requests from your CICS system should use a single proxy server, you can use the proxy server name from the INITPARM system initialization parameter, that DFH$WBPI used to initialize the global work area.

• The proxy name must be specified as:

  INITPARM=(DFH$WBPI='PROXY=proxyurl')

where proxyurl is the URL if a proxy server. If you use a number of proxy servers or want to apply a security policy to different host names, you can load or build a table that matches host names to appropriate proxy servers or marks them as barred, which can then be used as a look-up table during processing of the EXEC CICS WEB OPEN command.

This sample global user exit program has the following functions:

• If a GLUE global workarea is provided and it contains a non-zero LDAP connection token, it uses that token in subsequent SEARCH requests.
• If the exit is called at the XSTERM (system termination) exit point, it terminates the LDAP connection by invoking the DFHDDAP UNBIND_LDAP function. Otherwise, it obtains a connection token by issuing DFHDDAP BIND_LDAP and stores it in the global workarea. The LDAPBIND profile specified in the INITPARM parameter for DFH$WBPI is used to obtain LDAP credentials.
• Composes a distinguished name in the following format: racfcid=uuuuuuuu, ibm-httprealm=rrrrrrrr, labeledURI=xxxxxxxx, cn=BasicAuth where:

  racfcid=uuuuuuuu

  is the current userid, obtained from UEPUSER

  ibm-httprealm=rrrrrrrr

  is the HTTP 401 realm, obtained from UEPREALM (if this exists)

  labeledURI=xxxxxxxx

  is the target URL, obtained by concatenating “http://” with the hostname from UEPHOST and the path from UEPPATH

  cn=BasicAuth

  is an arbitrary suffix that is configured into the LDAP server for the purpose of storing Basic Authentication credentials.

• Issues DFHDDAP SEARCH_LDAP with this distinguished name
• If the SEARCH_LDAP fails, DFH$WBX1 removes the REALM parameter from the distinguished name and repeats the search. If the search fails again, DFH$WBX1 removes the UID parameter from the distinguished name and repeats the search. If the search fails for the third time, DFH$WBX1 returns from the exit with return code UERCERR.
• If the search was successful, issue DFHDDAP START_BROWSE_RESULTS
• Obtains the target username credential by obtaining the value of the UID attribute with DFHDDAP GET_ATTRIBUTE_VALUE. This is set into the response area provided by UEPUSNM.
• Obtains the target password credential by obtaining the value of the UserPassword attribute with DFHDDAP GET_ATTRIBUTE_VALUE. This is set into the response area provided by UEPPSWD.
• Releases the browse storage by issuing DFHDDAP END_BROWSE_RESULTS
• If the bind token was not stored in the global workarea, terminate the LDAP session by issuing DFHDDAP UNBIND_LDAP
• If all is successful, DFHWBX1 returns from the exit with return code UERCNORM.

This sample global user exit program has the following functions:

• Obtains the destination HTTP host from UEPHOST/UEPHOSTL and the destination HTTP path from UEPPATH/UEPPATHL, and uses them to construct the URL of the HTTP server for which the basic authentication credentials are required, as follows: http://hostname/pathname.
• If a realm exists (that is, if UEPREALML is non-zero), DFH$WBX2 appends the realm from UEPREALM to the URL created above, separated by a number sign (#) to make it look like a URL fragment identifier, as follows: http://hostname/pathname#realm. If necessary, the realm is URL-encoded.
• Stores the URL in the DFHWS-SERVICEURI container in the DFHWSTC-V1 channel.
• Stores the URL of the Security Token Service (STS), obtained from the global work area, in the DFHWS-STSURI container in the DFHWSTC-V1 channel.
• Stores architecturally appropriate URIs into the DFHWS-STSACTION and DFHWS-TOKENTYPE containers in the DFHWSTC-V1 channel.
• Constructs a username token from the caller's userid passed in UEPUSER, and store it in the DFHWS-IDTOKEN container in the DFHWSTC-V1 channel.
• Note: It is not necessary to specify a pipeline in the DFHWS-PIPELINE container. The pipeline is dynamically created by DFHPIRT when CHANNEL(DFHWSTC-V1) is specified on the command.
• Links to DFHPIRT, specifying CHANNEL(DFHWSTC-V1), after constructing all the required containers. This sends the request to the STS and receives the response into the DFHWS-RESTOKEN container.
• If the LINK was successful, DFHWBX2 recovers the response from the DFHWS-RESTOKEN container, which contains an username token in XML format.
• Extracts the username and password from this token, and returns them as responses from the user exit in UEPUSNM/UEPUSNML and UEPPSWD/UEPPSWDL. Returns from the user exit with return code UERCNORM.
• If the LINK was unsuccessful, or if a SOAP fault response is returned, DFH$WBX2 returns from the exit with return code UERCERR.

The above implementation assumes that the STS server is configured to respond with an appropriate username token when presented with the URI formatted by DFH$WBX2 in the AppliesTo element of the STS issue request.