Typical use of the LDAP XPI functions by XWBAUTH

The expected use of the DFHDDAPX functions (in association with the XWBAUTH global user exit) include opening and closing an LDAP session, browsing results for credentials, scanning and locating results, closing the browse, returning the correct value and closing the search.

BIND_LDAP
Establishes a session with an LDAP server. Used once on the first call to the global user exit XWBAUTH. The LDAP session token is stored in XWBAUTH's global work area (if one is provided) for use by subsequent calls to LDAP_SEARCH.
UNBIND_LDAP
Releases the connection with the LDAP server. This function is only required during CICS shutdown processing. This function can be used during the XSTERM (system termination) global user exit.
SEARCH_LDAP
Searches for credentials, specifying an LDAP distinguished name, that identifies the URL and realm of the required user information. Distinguished name is specified in the following format:
racfcid=uuuuuuuu, ibm-httprealm=rrrrrrrr, labeledURI=xxxxxxxx, cn=BasicAuth
where:
  • uuuuuuuu is the current userid, obtained from the XWBAUTH parameter, UEPUSER.
  • rrrrrrrr is the HTTP 401 realm, obtained from the XWBAUTH parameter, UEPREALM (if this exists).
  • xxxxxxxx is the target URL, obtained by concatenating http:// with the hostname from the XWBAUTH parameter, UEPHOST, and the path from the XWBAUTH parameter, UEPPATH.
  • cn=BasicAuth is an arbitrary suffix that is configured into the LDAP server for storing Basic Authentication credentials.
START_BROWSE_RESULTS
Starts scanning the results returned by SEARCH_LDAP.
GET_NEXT_ENTRY
Locates the next result entry in a series of entries returned by SEARCH_LDAP. Typically, the URL specified in SEARCH_LDAP will locate a unique entry and the GET_NEXT_ENTRY function is not used.
GET_NEXT_ATTRIBUTE
Locates the next attribute in the current result entry. Typically, specific attributes will be selected and the GET_NEXT_ATTRIBUTE function is not used.
END_BROWSE_RESULTS
Ends the browse session started by SEARCH_LDAP.
GET_ATTRIBUTE_VALUE
Returns the values for various attributes of the target distinguished name. For XWBAUTH, these attributes values are the username and password, stored in the attributes uid and userpassword. XWBAUTH returns these attribute values as credentials.
FREE_SEARCH_RESULTS
Closes the search initiated by SEARCH_LDAP and releases associated storage.