| | 1 | = UPDATE GATEWAY SCRIPTS = |
| | 2 | |
| | 3 | |
| | 4 | The update interface underlying the EDIR/AUTHSERV web gateways is tightly linked to |
| | 5 | both the iPlanet directory and to the Oracle registry and implements business rules |
| | 6 | about who may perform what update actions. |
| | 7 | |
| | 8 | The update interface originated with the EDIR web gateway but was separated from the |
| | 9 | EDIR interface in May of 2007. Because it started out as part of EDIR, the runtime.cfg |
| | 10 | file and Perl modules that are utilized by the update interface contain many references |
| | 11 | that are not pertinent to the update interface. Someday they may be dropped. |
| | 12 | |
| | 13 | |
| | 14 | |
| | 15 | == CONFIG FILES: ($HOME/EDIR<INST>/config) == |
| | 16 | |
| | 17 | |
| | 18 | === ldap_admin_actions.cfg === |
| | 19 | Contains data from which Admin Actions pick list is built; this file can be copied to all servers hosting the same UPDT instance |
| | 20 | |
| | 21 | === ldap_left_links.cfg === |
| | 22 | Contains data used to build links under EDIR banner this file can be copied to all servers hosting the same UPDT instance |
| | 23 | === runtime_common.cfg === |
| | 24 | 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 |
| | 25 | |
| | 26 | ||all_servers || list of all supported EDIR hosts ( - this list must include all functioning EDIR/AUTHSERV hosts) || |
| | 27 | ||bypassRegistryAttributes ||list of attributes that bypass registry processing; see also corresponding *_validate.pm scripts|| |
| | 28 | ||debug ||0|1: debugging is ON when value is 1|| |
| | 29 | ||directory_agent ||RDN of credentials used by gateway for normal query access |
| | 30 | ||directory_gateway_name ||name of EDIR web gateway|| |
| | 31 | ||directory_manager_passwd_file ||path reference for privileged credential password file (Directory Manager issue)|| |
| | 32 | ||directory_passwd_file ||path reference to directory_agent password file|| |
| | 33 | ||kerberos_conversion ||0|1: conversion of accounts to kerberos authentication is ON when value is 1|| |
| | 34 | ||kerberos_krb5_config ||path reference to krb5 file that configures kerberos access|| |
| | 35 | ||kerberos_mail_to ||email address to which kerberos related error messages are sent|| |
| | 36 | ||kerberos_passwd_file ||path reference to kerberos_agent password file|| |
| | 37 | ||kerberos_reset_expiration_days ||offset number of days used to compute password expiration for reset passwords|| |
| | 38 | ||kerberos_server_access ||id@host reference used in ssh to server supporting kerberos account creation|| |
| | 39 | ||kerberos_server_account ||id of UNIX account on server supporting kerberos account creation|| |
| | 40 | ||kerberos_servers ||list of supported kerberos servers for this instance of directory/kerberos|| |
| | 41 | ||local_announcements_file ||path reference to local announcements text file|| |
| | 42 | ||lock_file ||path reference to file used to disable EDIR updates|| |
| | 43 | ||log_dir ||path reference to EDIR log location|| |
| | 44 | ||mail_from_authserv ||email address used in FROM of mail generated for AUTHSERV|| |
| | 45 | ||mail_from_edir ||email address used in FROM of mail generated for EDIR|| |
| | 46 | ||mail_host ||email domain expected in vanity addresses|| |
| | 47 | ||mail_to ||address list for recipients of troubleshooting/batch reporting email|| |
| | 48 | ||max_updateable_attrib_values ||max number of multiply occuring attribute values allowed by ldap_update|| |
| | 49 | ||nsactivate_port ||port used when ns[in]activate invoked|| |
| | 50 | ||oitdest ||path reference to directory (on remote server) that is destination for datafiles used during kerberos account creation || |
| | 51 | ||oracle_home ||path reference to explicit ORACLE_HOME directory|| |
| | 52 | ||registry_agent ||Oracle schema for EDIR registry|| |
| | 53 | ||registry_db ||Oracle instance for EDIR registry|| |
| | 54 | ||registry_passwd_file ||path reference to registry_agent password file|| |
| | 55 | ||release ||major release number for EDIR web gateway|| |
| | 56 | ||slapd_port ||port for iPlanet directory access|| |
| | 57 | ||<mau>_passwdSync_URL ||URL of MAU web site called by AUTHSERV to sync password changes || |
| | 58 | ||<mau>_passwdSync_domain ||domain of MAU specific servers pushing password changes to us (insures we don't get in loop passing password back and forth)|| |
| | 59 | ||<mau>_passwdSync_key ||password/phrase used in MAU web site called by AUTHSERV to sync password changes|| |
| | 60 | ||<mau>_passwdSync_scope ||none|all|<list of UIDs>: determines accounts to which sync does[n't] apply|| |
| | 61 | ||<mau>_passwdSync_success ||character string returned by MAU web site when password sync is successful|| |
| | 62 | ||<mau>_passwdSync_<var> ||edirAttrib_<attrib>: where attrib is the name of the EDIR attribute holding the data that will be returned as <var> to the MAU web site|| |
| | 63 | || version ||gateway instance: TEST PREP or PROD || |
| | 64 | |
| | 65 | == runtime.cfg == |
| | 66 | Contains runtime configuration data used by EDIR CGI scripts this file is server/instance specific; **do not** copy to other servers. |
| | 67 | |
| | 68 | ||directory_gateway_link ||URL to EDIR web gateway|| |
| | 69 | ||directory_instance ||iPlanet directory instance|| |
| | 70 | ||directory_server_link ||URL to server specific EDIR web gateway (Equalizer issue)|| |
| | 71 | ||kerberos_agent ||kerberos principle used during kerberos account management|| |
| | 72 | ||query_servers ||list of servers that may respond to query requests [#point1 (1)].|| |
| | 73 | ||slapd_ssl_clause ||additional clause required if slapd_port is SSL configured port|| |
| | 74 | ||update_server ||server(s) that may respond to update requests (local machine issue) [#point2 (2)]|| |
| | 75 | |
| | 76 | [=#point1 (1)] sxmpa 2/13/2010 - |
| | 77 | This variable should be assigned a single value, which is the host |
| | 78 | housing the LDAP server queried by this UPDATE gateway instance. |
| | 79 | This value should be the same as that of the update_server variable. The |
| | 80 | UPDATE gateway instance is normally co-located with that LDAP server |
| | 81 | on the same host, but you have the option of choosing an LDAP server on |
| | 82 | some other host. Assigning this variable a list of hostnames rather |
| | 83 | than a single hostname appears to work correctly, but examination of |
| | 84 | the code suggests that behaviour in this case is undefined |
| | 85 | |
| | 86 | [=#point2 (2)] sxmpa 2/13/2010 - This variable should be assigned a single value, |
| | 87 | which is the host housing the LDAP server queried by this UPDATE |
| | 88 | gateway instance. This value should be the same as that of the |
| | 89 | query_servers variable. |
| | 90 | |
| | 91 | == LIBRARIES: ($HOME/EDIR<INST>/cgi-bin/) == |
| | 92 | |
| | 93 | |
| | 94 | === ldap_lib.pm === |
| | 95 | |
| | 96 | sub Authenticate accepts credentials (UID or mailAlternateAddress and password) |
| | 97 | returns whether authenticated [Y|N] and |
| | 98 | if successful: null msg, UID, displayName and list of user's roles |
| | 99 | if unsuccessful: error msg, UID, null, null |
| | 100 | |
| | 101 | sub CampusPickList generates generic HTML form element for campus picklist using |
| | 102 | ldap_uakEmployeeCampus.txt as input |
| | 103 | |
| | 104 | sub Credentials generates HTML form elements for LDAP credentials (id and password) |
| | 105 | |
| | 106 | sub UAclose generates closing HTML elements for standard window look and feel |
| | 107 | |
| | 108 | sub UAopen generates opening HTML elements for standard window look and feel |
| | 109 | |
| | 110 | sub abort uses mailx to send $body with $subject to $MAILTO |
| | 111 | |
| | 112 | sub appendMsg formats $msg_in according to $msg_type and appends to $MSG |
| | 113 | |
| | 114 | sub bldgCampusPickList generates HTML form element for building pick list for MAU |
| | 115 | |
| | 116 | sub bldgExists checks static file to determine if building code exists (issue: building |
| | 117 | codes are stored in registry and in static file but not in directory) |
| | 118 | |
| | 119 | sub bldgPicklist generates HTML form element for building pick list |
| | 120 | |
| | 121 | sub crypt simple encryption of strings; used to encrypt password before storing |
| | 122 | in LDAP cookie |
| | 123 | |
| | 124 | sub debug utility used to record debugging information (utilizes debug runtime config parm) |
| | 125 | |
| | 126 | sub deptUnitPickList generates HTML form element for department picklist; elements of list |
| | 127 | taken from external file ldap_deptUnits.txt |
| | 128 | |
| | 129 | sub embeddedAttributes (may be obsolete; was formatting solution for uakPhonebookFlag attribute, |
| | 130 | the values of which could represent an unlimited number of MAU specific |
| | 131 | phonebook "attributes") |
| | 132 | |
| | 133 | sub employeeCampusPickList generates HTML form element for an employee's campus picklist using |
| | 134 | ldapsearch to locate that employee's uakEmployeeCampus attribute values |
| | 135 | |
| | 136 | sub employeeDeptPickList generates generic HTML form element for campus picklist using |
| | 137 | ldap_uakEmployeeAffiliation.txt |
| | 138 | |
| | 139 | sub formatAttributes function returning hash of attribute characteristics used to control |
| | 140 | formatting of HTML form elements; elements with exceptional (non-standard) |
| | 141 | formatting requirements are recorded here |
| | 142 | |
| | 143 | sub formatLabel formats field descriptions with or without accompanying comments |
| | 144 | |
| | 145 | sub formatValue formats attribute values, generating href tags for specific attribute types |
| | 146 | |
| | 147 | sub genClearCookie Generates Set-Cookie metadata that clears old cookie (where ldapstring |
| | 148 | is assumed to be the cookie being cleared) |
| | 149 | |
| | 150 | sub genClearSimpleCookie Generates Set-Cookie metadata that clears new simple cookie (where |
| | 151 | name/value are passed to funtion). |
| | 152 | |
| | 153 | sub genSetCookie Generates Set-Cookie metadata that establishes a specific cookie (new or old) |
| | 154 | |
| | 155 | sub getACL Returns hash of permissions for requested list of ACL names. |
| | 156 | |
| | 157 | sub getAttributes returns a hash of arrays for attributes meeting specified criteria |
| | 158 | the hash keys are LDAP attribute names |
| | 159 | each hash value is an array of attribute characteristics |
| | 160 | |
| | 161 | sub getEntityDisplayLabel function returning one of DISPLAY_NAME, TITLE_<something>, UNITDISPLAYNAME, |
| | 162 | UNITNAME or UID from an array of attributes passed to the function |
| | 163 | |
| | 164 | sub getUserAttributes returns array of attribute=value pairs for $filter |
| | 165 | |
| | 166 | sub getSecureAttributes returns array of attribute=value pairs for $filter (utilizes privileged |
| | 167 | credentials) |
| | 168 | |
| | 169 | sub is_deptAdmin function that determines if credentialed user is admin for department record |
| | 170 | |
| | 171 | sub is_emplAdmin function that determines if credentialed user is admin for people record |
| | 172 | |
| | 173 | sub lookUpParentUnit function that returns parent unit for department record |
| | 174 | |
| | 175 | sub pad returns string padded with character to specified length |
| | 176 | |
| | 177 | sub parseCookie parses old, complex cookie; returning the UID, password, name and role elements |
| | 178 | |
| | 179 | sub parseDN parses $dn and returns UID and OU elements |
| | 180 | |
| | 181 | sub parseSimpleCookie parses new simple cookie; returning a single string value |
| | 182 | |
| | 183 | sub post_admin executes HTTPS request to call ldap_bulk_admin CGI script as though |
| | 184 | from the web (utilizes directory_server_link runtime config parm) |
| | 185 | |
| | 186 | sub post_updates executes HTTPS request to call ldap_bulk_update CGI script as though |
| | 187 | from the web (utilizes directory_server_link runtime config parm) |
| | 188 | |
| | 189 | sub returnIdentifierFilter used to return a generic filter that can be used to search for |
| | 190 | a people record by name or any identifier accepted during AUTHSERV |
| | 191 | authentication (see ldap_dlevelx CGI script) |
| | 192 | |
| | 193 | sub studentDeptPickList generates generic HTML form element for student department picklist using |
| | 194 | ldap_uakStudentAffiliation.txt |
| | 195 | |
| | 196 | sub uidLDAPlookup returns (last) $attribute value for matching $filter where query |
| | 197 | executed by credentialed user or default gateway user |
| | 198 | (weak - utilized currently only by ldap_lib.pm) |
| | 199 | |
| | 200 | |
| | 201 | === ldap_mod.pm === |
| | 202 | |
| | 203 | sub bypassRegistryUpdates both determines if attribute is supposed to bypass registry |
| | 204 | (see runtime configurartion parameter bypassRegistryAttributes) |
| | 205 | and then - if attrib **will** bypass registry - look for and |
| | 206 | execute attribute specific validation script (see |
| | 207 | *_validate.pm) |
| | 208 | |
| | 209 | sub closing executes $dbh->rollback followed by $dbh->finish |
| | 210 | (dhb->commit executed explicitly elsewhere) |
| | 211 | |
| | 212 | sub connect establishes ORACLE_HOME and executes DBI->connect utilizing $eff_login |
| | 213 | to establish $dbh |
| | 214 | |
| | 215 | sub copy_to_oitdest copies LDIF processed by process_admin_request to location identified |
| | 216 | in runtime parameter oitdest, if runtime parameter defined |
| | 217 | |
| | 218 | sub directory_update executes ldapmodify statements to update LDAP directory |
| | 219 | |
| | 220 | sub evaluate executes $dbh->prepare on $sql to establishes $sth |
| | 221 | |
| | 222 | sub execute performs $sth->execute which executes sql statement in Oracle database |
| | 223 | |
| | 224 | sub getSecureAttributes returns array of attribute=value pairs for $filter (utilizes privileged |
| | 225 | credentials) |
| | 226 | |
| | 227 | sub getSecureAttributes process that utilizes privileged application credentials to obtain |
| | 228 | secure attribute values when needed for processing (don't rely on |
| | 229 | credentials of requester which might not have needed access) |
| | 230 | |
| | 231 | sub kerberos_change process by which a kerberos principal *changes* his known kerberos |
| | 232 | password to a new value |
| | 233 | |
| | 234 | sub kerberos_create process by which a kerberos principal is created |
| | 235 | |
| | 236 | sub kerberos_date_to_time process by which a kerberos date/time stamp is converted Perl date/time |
| | 237 | |
| | 238 | sub kerberos_directoryPrincipal process which returns kerberos principal associated with given UID |
| | 239 | |
| | 240 | sub kerberos_getprinc process which executes kadmin getprinc command |
| | 241 | |
| | 242 | sub kerberos_inactivate process which inactivates a kerberos principal (creates random |
| | 243 | preexpired password) |
| | 244 | |
| | 245 | sub kerberos_initialize process which activates a kerberos principal (establishes the |
| | 246 | default password with 14 day password expiration) |
| | 247 | |
| | 248 | sub kerberos_lock process which locks a kerberos account (establishes a known |
| | 249 | expiration date/time on account) |
| | 250 | |
| | 251 | sub kerberos_reset process which resets a kerberos password to its default value |
| | 252 | |
| | 253 | sub kerberos_unlock process which removes the expiration date/time from an account |
| | 254 | |
| | 255 | sub kerberos_update process which determines if a password update request is a non-owner |
| | 256 | reset or an owner change; also directs conversion processing steps |
| | 257 | (which entails a reset followed by a change) |
| | 258 | |
| | 259 | |
| | 260 | sub lock_account executes iPlanet ns[in]activate command to disable/enable account |
| | 261 | |
| | 262 | sub log_admin_update logs admin updates for historical reference |
| | 263 | |
| | 264 | sub log_error writes $msg to $ERRORLOG |
| | 265 | |
| | 266 | sub log_history logs normal gatewway updates |
| | 267 | |
| | 268 | sub log_update writes $msg to $UPDATELOG using flock in coordination with |
| | 269 | gateway_move_logs.pl to get a file lock before performing an action |
| | 270 | calls report_fatal if fails to write update to $UPDATELOG |
| | 271 | |
| | 272 | === sub mauPasswdSync === |
| | 273 | |
| | 274 | sub process_admin_request main routine for processing admin updates; like process_request only |
| | 275 | restricted to EDIR administrator use to add/delete entities (results |
| | 276 | in creation or removal of a DN). Gets EDIRrole values from directory |
| | 277 | and looks for acceptable role before proceeding. First line of file |
| | 278 | input *must* reference a supported action (add or delete). Returns |
| | 279 | output from ldif processing which the calling program is expected to |
| | 280 | parse to determine result. |
| | 281 | |
| | 282 | sub process_request main routine for processing updates; checks process type ($action) |
| | 283 | and performs rudimentary error checking, then attempts to update |
| | 284 | the Oracle registry. if successful, calls directory_update to |
| | 285 | update directory. returns success (1) or failure (0) and $return_msg |
| | 286 | generated by either the registry update or the directory update |
| | 287 | |
| | 288 | sub registry_update executes $sql in registry, capturing success (1) or failure (0), |
| | 289 | $sql_msg and $sql_row_count resulting from sql execution; returns |
| | 290 | success or failure and $sql_msg |
| | 291 | |
| | 292 | Note: $sql_row_count use is deprecated (not capturing row counts |
| | 293 | in EDIR package to return); will be removed from sub routine. |
| | 294 | |
| | 295 | sub report_error utilizes mailx to send $body with $subject to $MAILTO without |
| | 296 | disabling updates |
| | 297 | |
| | 298 | sub report_fatal utilizes mailx to send $body with $subject to $MAILTO |
| | 299 | generates $ldap_lib::LOCKFILE (gateway_updates_disabled) to |
| | 300 | disable updates until problem resovled |
| | 301 | |
| | 302 | sub special_logging (obsoleted; discarded method of providing UAA with record of |
| | 303 | EDIR updates) |
| | 304 | |
| | 305 | sub uakEmployeeLocatorSubProcessing |
| | 306 | process by which individual attributes underlying uakEmployeeLocator |
| | 307 | (office, telephonenumber, facsimiletelephonenumber) are maintained |
| | 308 | as a byproduct of uakEmployeeLocator maintenance |
| | 309 | |
| | 310 | sub user_notification routine for notifying account holders of events (assuming they are |
| | 311 | not a UAA student or staff member) |
| | 312 | |
| | 313 | |
| | 314 | === <attrib>_validation.pm === |
| | 315 | |
| | 316 | sub validate apply business rules to requested update of <attrib> and return |
| | 317 | success or failure (these *.pm created for attributes which bypass |
| | 318 | registry processing; attrib must be listed in runtime parameter |
| | 319 | bypassRegistryAttributes for the *pm to be executed |
| | 320 | |
| | 321 | |
| | 322 | |
| | 323 | ++++++++++++ |
| | 324 | CGI SCRIPTS: ($HOME/EDIR<INST>/cgi-bin/) |
| | 325 | ++++++++++++ |
| | 326 | |
| | 327 | ldap_bulk_admin Script performing all special administration of EDIR records not supported in other |
| | 328 | EDIR forms. When called via web browser, generates HTML form with file form variable |
| | 329 | for specifying file containing administative requests. When called via web browser, |
| | 330 | utilizes credentials stored in LDAP cookie by ldap_auth. When called via UNIX shell |
| | 331 | and HTTP request, generates *no* HTML form and credentials must be passed with the |
| | 332 | request along with name of file contaiing update requests. ldap_bulk_admin calls |
| | 333 | ldap_mod::process_admin_request which performs the actual Directory update. |
| | 334 | |
| | 335 | ldap_bulk_update Script performing all EDIR gateway updates. When called via web browser, generates |
| | 336 | HTML form with file form variable for specifying file containing update requests. |
| | 337 | When called via web browser, utilizes credentials stored in LDAP cookie by ldap_auth. |
| | 338 | When called via UNIX shell and HTTP request, generates *no* HTML form and credentials |
| | 339 | must be passed with the request along with name of file contaiing update requests. |
| | 340 | ldap_bulk_update calls ldap_mod::process_request which performs the actual Directory |
| | 341 | update. |
| | 342 | |
| | 343 | |
| | 344 | ####################### |
| | 345 | DOCUMENT CHANGE HISTORY |
| | 346 | |
| | 347 | 20081031 elm added reference to runtime_common.cfg and updated lists of runtime parameters |
| | 348 | 20081114 elm updated document to include *.pm functions not already documented |
| | 349 | sxmpa 2/13/2010 - noted list requirements for all_servers |
| | 350 | |
| | 351 | # eof |
