= UPDATE GATEWAY SCRIPTS = The update interface underlying the EDIR/AUTHSERV web gateways is tightly linked to both the iPlanet directory and to the Oracle registry and implements business rules about who may perform what update actions. The update interface originated with the EDIR web gateway but was separated from the EDIR interface in May of 2007. Because it started out as part of EDIR, the runtime.cfg file and Perl modules that are utilized by the update interface contain many references that are not pertinent to the update interface. Someday they may be dropped. == CONFIG FILES: ($HOME/EDIR/config) == === ldap_admin_actions.cfg === Contains data from which Admin Actions pick list is built; this file can be copied to all servers hosting the same UPDT instance === ldap_left_links.cfg === Contains data used to build links under EDIR banner this file can be copied to all servers hosting the same UPDT instance === runtime_common.cfg === Contains a subset of runtime configuration elements that are constant between servers hosting gateway - see runtime.cfg; this file can be copied to all servers hosting the same UPDT instance ||= Variable =||= Description =|| ||all_servers || list of all supported EDIR hosts ( - this list must include all functioning EDIR/AUTHSERV hosts) || ||bypassRegistryAttributes || list of attributes that bypass registry processing; see also corresponding *_validate.pm scripts || ||debug || 0|1: debugging is ON when value is 1 || ||directory_agent || RDN of credentials used by gateway for normal query access || ||directory_gateway_name || name of EDIR web gateway || ||directory_manager_passwd_file || path reference for privileged credential password file (Directory Manager issue) || ||directory_passwd_file || path reference to directory_agent password file || ||kerberos_conversion || 0|1: conversion of accounts to kerberos authentication is ON when value is 1 || ||kerberos_krb5_config || path reference to krb5 file that configures kerberos access || ||kerberos_mail_to || email address to which kerberos related error messages are sent || ||kerberos_passwd_file || path reference to kerberos_agent password file || ||kerberos_reset_expiration_days || offset number of days used to compute password expiration for reset passwords || ||kerberos_server_access || id@host reference used in ssh to server supporting kerberos account creation || ||kerberos_server_account || id of UNIX account on server supporting kerberos account creation || ||kerberos_servers || list of supported kerberos servers for this instance of directory/kerberos || ||local_announcements_file || path reference to local announcements text file || ||lock_file || path reference to file used to disable EDIR updates || ||log_dir || path reference to EDIR log location || ||mail_from_authserv || email address used in FROM of mail generated for AUTHSERV || ||mail_from_edir || email address used in FROM of mail generated for EDIR || ||mail_host || email domain expected in vanity addresses || ||mail_to || address list for recipients of troubleshooting/batch reporting email || ||max_updateable_attrib_values || max number of multiply occuring attribute values allowed by ldap_update || ||nsactivate_port || port used when ns[in]activate invoked || ||oitdest || path reference to directory (on remote server) that is destination for datafiles used during kerberos account creation || ||oracle_home || path reference to explicit ORACLE_HOME directory || ||registry_agent || Oracle schema for EDIR registry || ||registry_db || Oracle instance for EDIR registry || ||registry_passwd_file || path reference to registry_agent password file || ||release || major release number for EDIR web gateway || ||slapd_port || port for iPlanet directory access || ||_passwdSync_URL || URL of MAU web site called by AUTHSERV to sync password changes || ||_passwdSync_domain ||domain of MAU specific servers pushing password changes to us (insures we don't get in loop passing password back and forth)|| ||_passwdSync_key ||password/phrase used in MAU web site called by AUTHSERV to sync password changes|| ||_passwdSync_scope ||none|all|: determines accounts to which sync does[n't] apply|| ||_passwdSync_success ||character string returned by MAU web site when password sync is successful|| ||_passwdSync_ ||edirAttrib_: where attrib is the name of the EDIR attribute holding the data that will be returned as to the MAU web site|| ||version ||gateway instance: TEST PREP or PROD || == runtime.cfg == Contains runtime configuration data used by EDIR CGI scripts this file is server/instance specific; **do not** copy to other servers. ||= Variable =||= Description =|| ||directory_gateway_link ||URL to EDIR web gateway|| ||directory_instance ||iPlanet directory instance|| ||directory_server_link ||URL to server specific EDIR web gateway (Equalizer issue)|| ||kerberos_agent ||kerberos principle used during kerberos account management|| ||query_servers ||list of servers that may respond to query requests [#point1 (1)].|| ||slapd_ssl_clause ||additional clause required if slapd_port is SSL configured port|| ||update_server ||server(s) that may respond to update requests (local machine issue) [#point2 (2)]|| [=#point1 (1)] sxmpa 2/13/2010 - This variable should be assigned a single value, which is the host housing the LDAP server queried by this UPDATE gateway instance. This value should be the same as that of the update_server variable. The UPDATE gateway instance is normally co-located with that LDAP server on the same host, but you have the option of choosing an LDAP server on some other host. Assigning this variable a list of hostnames rather than a single hostname appears to work correctly, but examination of the code suggests that behaviour in this case is undefined [=#point2 (2)] sxmpa 2/13/2010 - This variable should be assigned a single value, which is the host housing the LDAP server queried by this UPDATE gateway instance. This value should be the same as that of the query_servers variable. == LIBRARIES: ($HOME/EDIR/cgi-bin/) == === ldap_lib.pm === '''sub Authenticate :''' accepts credentials (UID or mailAlternateAddress and password) returns whether authenticated [Y|N] and if successful: null msg, UID, displayName and list of user's roles if unsuccessful: error msg, UID, null, null '''sub !CampusPickList : ''' generates generic HTML form element for campus picklist using ldap_uakEmployeeCampus.txt as input '''sub Credentials : ''' generates HTML form elements for LDAP credentials (id and password) '''sub UAclose : ''' generates closing HTML elements for standard window look and feel '''sub UAopen : ''' generates opening HTML elements for standard window look and feel '''sub abort : ''' uses mailx to send $body with $subject to $MAILTO '''sub appendMsg : ''' formats $msg_in according to $msg_type and appends to $MSG '''sub bldgCampusPickList : ''' generates HTML form element for building pick list for MAU '''sub bldgExists : ''' checks static file to determine if building code exists (issue: building codes are stored in registry and in static file but not in directory) '''sub bldgPicklist : ''' generates HTML form element for building pick list '''sub crypt : ''' simple encryption of strings; used to encrypt password before storing in LDAP cookie '''sub debug :''' utility used to record debugging information (utilizes debug runtime config parm) '''sub deptUnitPickList : ''' generates HTML form element for department picklist; elements of list taken from external file ldap_deptUnits.txt '''sub embeddedAttributes : ''' (may be obsolete; was formatting solution for uakPhonebookFlag attribute, the values of which could represent an unlimited number of MAU specific phonebook "attributes") '''sub employeeCampusPickList : ''' generates HTML form element for an employee's campus picklist using ldapsearch to locate that employee's uakEmployeeCampus attribute values '''sub employeeDeptPickList : ''' generates generic HTML form element for campus picklist using ldap_uakEmployeeAffiliation.txt '''sub formatAttributes : ''' function returning hash of attribute characteristics used to control formatting of HTML form elements; elements with exceptional (non-standard) formatting requirements are recorded here '''sub formatLabel : ''' formats field descriptions with or without accompanying comments '''sub formatValue : ''' formats attribute values, generating href tags for specific attribute types '''sub genClearCookie : ''' Generates Set-Cookie metadata that clears old cookie (where ldapstring is assumed to be the cookie being cleared) '''sub genClearSimpleCookie : ''' Generates Set-Cookie metadata that clears new simple cookie (where name/value are passed to funtion). '''sub genSetCookie : ''' Generates Set-Cookie metadata that establishes a specific cookie (new or old) '''sub getACL : ''' Returns hash of permissions for requested list of ACL names. '''sub getAttributes : ''' returns a hash of arrays for attributes meeting specified criteria the hash keys are LDAP attribute names each hash value is an array of attribute characteristics '''sub getEntityDisplayLabel : ''' function returning one of DISPLAY_NAME, TITLE_, UNITDISPLAYNAME, UNITNAME or UID from an array of attributes passed to the function '''sub getUserAttributes : ''' returns array of attribute=value pairs for $filter '''sub getSecureAttributes : ''' returns array of attribute=value pairs for $filter (utilizes privileged credentials) '''sub is_deptAdmin : ''' function that determines if credentialed user is admin for department record '''sub is_emplAdmin : ''' function that determines if credentialed user is admin for people record '''sub lookUpParentUnit : ''' function that returns parent unit for department record '''sub pad : ''' returns string padded with character to specified length '''sub parseCookie : ''' parses old, complex cookie; returning the UID, password, name and role elements '''sub parseDN : ''' parses $dn and returns UID and OU elements '''sub parseSimpleCookie : ''' parses new simple cookie; returning a single string value '''sub post_admin : ''' executes HTTPS request to call ldap_bulk_admin CGI script as though from the web (utilizes directory_server_link runtime config parm) '''sub post_updates : ''' executes HTTPS request to call ldap_bulk_update CGI script as though from the web (utilizes directory_server_link runtime config parm) '''sub returnIdentifierFilter : ''' used to return a generic filter that can be used to search for a people record by name or any identifier accepted during AUTHSERV authentication (see ldap_dlevelx CGI script) '''sub studentDeptPickList : ''' generates generic HTML form element for student department picklist using ldap_uakStudentAffiliation.txt '''sub uidLDAPlookup : ''' returns (last) $attribute value for matching $filter where query executed by credentialed user or default gateway user (weak - utilized currently only by ldap_lib.pm) === ldap_mod.pm === '''sub bypassRegistryUpdates :''' both determines if attribute is supposed to bypass registry (see runtime configurartion parameter bypassRegistryAttributes) and then - if attrib **will** bypass registry - look for and execute attribute specific validation script (see *_validate.pm) '''sub closing :''' executes $dbh->rollback followed by $dbh->finish (dhb->commit executed explicitly elsewhere) '''sub connect :''' establishes ORACLE_HOME and executes DBI->connect utilizing $eff_login to establish $dbh '''sub copy_to_oitdest :''' copies LDIF processed by process_admin_request to location identified in runtime parameter oitdest, if runtime parameter defined '''sub directory_update :''' executes ldapmodify statements to update LDAP directory '''sub evaluate :''' executes $dbh->prepare on $sql to establishes $sth '''sub execute :''' performs $sth->execute which executes sql statement in Oracle database '''sub getSecureAttributes :''' returns array of attribute=value pairs for $filter (utilizes privileged credentials) '''sub getSecureAttributes :''' process that utilizes privileged application credentials to obtain secure attribute values when needed for processing (don't rely on credentials of requester which might not have needed access) '''sub kerberos_change :''' process by which a kerberos principal *changes* his known kerberos password to a new value '''sub kerberos_create :''' process by which a kerberos principal is created '''sub kerberos_date_to_time :''' process by which a kerberos date/time stamp is converted Perl date/time '''sub kerberos_directory :''' Principal process which returns kerberos principal associated with given UID '''sub kerberos_getprinc :''' process which executes kadmin getprinc command '''sub kerberos_inactivate :''' process which inactivates a kerberos principal (creates random preexpired password) '''sub kerberos_initialize :''' process which activates a kerberos principal (establishes the default password with 14 day password expiration) '''sub kerberos_lock :''' process which locks a kerberos account (establishes a known expiration date/time on account) '''sub kerberos_reset :''' process which resets a kerberos password to its default value '''sub kerberos_unlock :''' process which removes the expiration date/time from an account '''sub kerberos_update :''' process which determines if a password update request is a non-owner reset or an owner change; also directs conversion processing steps (which entails a reset followed by a change) '''sub lock_account :''' executes iPlanet ns[in]activate command to disable/enable account '''sub log_admin_update :''' logs admin updates for historical reference '''sub log_error :''' writes $msg to $ERRORLOG '''sub log_history :''' logs normal gatewway updates '''sub log_update :''' writes $msg to $UPDATELOG using flock in coordination with gateway_move_logs.pl to get a file lock before performing an action calls report_fatal if fails to write update to $UPDATELOG === sub mauPasswdSync === '''sub process_admin_request :''' main routine for processing admin updates; like process_request only restricted to EDIR administrator use to add/delete entities (results in creation or removal of a DN). Gets EDIRrole values from directory and looks for acceptable role before proceeding. First line of file input *must* reference a supported action (add or delete). Returns output from ldif processing which the calling program is expected to parse to determine result. '''sub process_request :''' main routine for processing updates; checks process type ($action) and performs rudimentary error checking, then attempts to update the Oracle registry. if successful, calls directory_update to update directory. returns success (1) or failure (0) and $return_msg generated by either the registry update or the directory update '''sub registry_update :''' executes $sql in registry, capturing success (1) or failure (0), $sql_msg and $sql_row_count resulting from sql execution; returns success or failure and $sql_msg. [[br]][[br]] Note: $sql_row_count use is deprecated (not capturing row counts in EDIR package to return); will be removed from sub routine. '''sub report_error :''' utilizes mailx to send $body with $subject to $MAILTO without disabling updates '''sub report_fatal :''' utilizes mailx to send $body with $subject to $MAILTO generates $ldap_lib::LOCKFILE (gateway_updates_disabled) to disable updates until problem resovled '''sub special_logging :''' (obsoleted; discarded method of providing UAA with record of EDIR updates) '''sub uakEmployeeLocatorSubProcessing :''' process by which individual attributes underlying uakEmployeeLocator (office, telephonenumber, facsimiletelephonenumber) are maintained as a byproduct of uakEmployeeLocator maintenance '''sub user_notification :''' routine for notifying account holders of events (assuming they are not a UAA student or staff member) === _validation.pm === '''sub validate :''' apply business rules to requested update of and return success or failure (these *.pm created for attributes which bypass registry processing; attrib must be listed in runtime parameter bypassRegistryAttributes for the *pm to be executed == CGI SCRIPTS: ($HOME/EDIR/cgi-bin/) == '''ldap_bulk_admin :''' Script performing all special administration of EDIR records not supported in other EDIR forms. * When called via web browser, generates HTML form with file form variable for specifying file containing administative requests. * When called via web browser, utilizes credentials stored in LDAP cookie by ldap_auth. * When called via UNIX shell and HTTP request, generates *no* HTML form and credentials must be passed with the request along with name of file contaiing update requests. [[br]][[br]]ldap_bulk_admin calls ldap_mod::process_admin_request which performs the actual Directory update. '''ldap_bulk_update :''' Script performing all EDIR gateway updates. * When called via web browser, generates HTML form with file form variable for specifying file containing update requests. * When called via web browser, utilizes credentials stored in LDAP cookie by ldap_auth. * When called via UNIX shell and HTTP request, generates *no* HTML form and credentials must be passed with the request along with name of file contaiing update requests.[[br]][[br]] ldap_bulk_update calls ldap_mod::process_request which performs the actual Directory update. #######################[[br]] DOCUMENT CHANGE HISTORY 20081031 elm added reference to runtime_common.cfg and updated lists of runtime parameters[[br]] 20081114 elm updated document to include *.pm functions not already documented[[br]] sxmpa 2/13/2010 - noted list requirements for all_servers