HTTP client send exit XWBAUTH

With XWBAUTH, you can specify basic authentication credentials (user name and password) for a target server or service provider. XWBAUTH passes them to CICS® on request, to create an Authorization header, which is forwarded using HTTP.

When you specify AUTHENTICATE(BASICAUTH) in the EXEC CICS WEB SEND (Client) or WEB CONVERSE command, the application can provide a user name and password. If they are not supplied, XWBAUTH is called, providing an alternative way of specifying these credentials. XWBAUTH is also called when you specify AUTHENTICATE(BASIC) in a URIMAP resource definition for USAGE(CLIENT), unless the application provides a user name and password in the EXEC CICS WEB SEND (Client) or WEB CONVERSE command. XWBAUTH is also called with EC INVOKE SERVICE() URIMAP() when urimap specifies AUTHENTICATE(BASIC)

The user name and password are typically specific to the remote server environment, and might be longer than the standard eight characters used by RACF® systems. The user name and password fields can be up to 256 characters in length. The syntax of these fields is not validated.

The host is passed to the user exit program as the UEPHOST parameter, and the path is passed as the UEPPATH parameter. The realm is passed optionally as the UEPREALM parameter. In response, the user exit program returns the user name and password as the UEPUSNM and UEPPSWD parameters. When encoding the supplied userid and password CICS uses the EBCDIC code pages.

The following sample exit programs are shipped in the CICS sample library, SDFHSAMP:

DFH$WBPI
DFH$WBEX
DFH$WBX1
DFH$WBX2
DFH$WBGA, a copybook to map the global work area used by the DFH$WBPI, DFH$WBX1, DFH$WBX2, and DFH$WBEX samples.

For more information about the client sample exit programs, see The HTTP client sample exit programs. For more information about setting up your LDAP profile, see Authorizing CICS to access CRLs.

Exit XWBAUTH

When invoked

When the EXEC CICS WEB SEND or WEB CONVERSE command specifies AUTHENTICATE(BASICAUTH), but the USERNAME and PASSWORD are not specified.

Exit-specific parameters

UEPHOST (Input supplied by CICS): The address of a field containing the address of the host name, IPv4, or IPv6 address specified in the HOST option of the WEB OPEN command for the connection. The host name is converted into lowercase characters when it is saved in this field. Your user exit program must take this conversion into account when matching the host name.
UEPHOSTL (Input supplied by CICS): The address of a field containing the halfword length of the host name.
UEPPATH (Input supplied by CICS): The address of a field containing the address of the path specified in the PATH option of the WEB SEND or WEB CONVERSE command. The path is mixed case, as it was specified.
UEPPATHL (Input supplied by CICS): The address of a field containing the halfword length of the path.
UEPREALM (Input supplied by CICS): The address of a field containing the address of the realm name associated with the target destination, if a realm name was returned in a previous HTTP 401 response from the server.
UEPREALML (Input supplied by CICS): The address of a field containing the halfword length of the realm name.
UEPAUTHT (Input supplied by CICS): The address of a 1-byte code that indicates the authentication type. This code is a binary 01, indicating Basic Authentication.
UEPUSNM (Output supplied by user exit): The address of a fullword field, containing the address of the user name required to access the HTTP server. A predefined address and 64-byte area are created by CICS to store the user name. You can place your user name in this 64-byte area, leaving the address in UEPUSNM unchanged. Alternatively, you can place your user name in your own area and replace the address in UEPUSNM with your user name address. If you create your own user name area, the field can be up to 256 bytes in length.
UEPUSNML (Input supplied by CICS and output supplied by user exit): The address of a halfword field, which initially contains the length of the buffer address supplied in UEPUSNM. Your user exit program must set the length of this buffer to the user name length, as supplied in UEPUSNM.
UEPPSWD (Output supplied by user exit): The address of a fullword field, containing the address of the password required to access the HTTP server. A predefined address and 100-byte area are created by CICS to store the password or password phrase. You can place your password in this 100-byte area, leaving the address in UEPPSWD unchanged. Alternatively, you can place your password in your own area and replace the address in UEPPSWD with the address of your password. If you create your own password area, the field can be up to 256 bytes in length.
UEPPSWDL (Input supplied by CICS and output supplied by user exit): The address of a halfword field, which initially contains the length of the buffer address supplied in UEPPSWD. Your user exit program must set the length of this buffer to the actual password length, as supplied in UEPPSWD.
UEPHOSTT (Input supplied by CICS): The address of a 1-byte code that indicates the host type contained in the UEPHOST parameter.
Binary 01 indicates host name, binary 02 indicates an IPv4 address, and binary 03 indicates an IPv6 address.

Return codes

UERCNORM: The exit has successfully returned a user name and password.
UERCBYP: The exit cannot identify a user name and password. An Authorization header is not sent.
UERCERR: The exit cannot identify a user name and password. The WEB SEND (Client) or WEB CONVERSE command must be stopped.

XPI calls

All XPI calls can be used.

API and SPI commands

All API and SPI commands can be used, except for EXEC CICS SHUTDOWN and EXEC CICS XCTL.