= AUTHSERV GATEWAY SCRIPTS =
    Original author:  Beth Mercer - 20081031              

== Overview ==
The AUTHSERV interface originated with the EDIR web gateway but was separated from the 
EDIR interface in July of 2005.  Because it started out as part of EDIR, the Perl
modules that are utilized by the AUTHSERV interface contain many functions that are
simply not pertinent to the AUTHSERV interface.  Someday they may be dropped.

== Configuration Files ==

Configuration files are located for every instance under $HOME/AUTHSERV<''INST''>/config

=== admin_actions.cfg ===
This file contains data from which Admin Actions pick list is built.  The 
file can be copied to all servers hosting the same AUTHSERV instance.

=== registered_clients.cfg ===
This file contains data used by authentication service to determine if authentication is performed and.  If authentication was performed it then determines what information is provided as a result of authentication and confirmation of authentication.  The file can be copied to all servers hosting the same AUTHSERV instance
=== runtime_common.cfg ===
This file contains a subset of runtime configuration elements that are constant between servers hosting gateway - see runtime.cfg.  The file can be copied to all servers hosting the same AUTHSERV instance.
=== runtime.cfg ===
This file contains runtime configuration data used by AUTHSERV CGI scripts

        ||= Parameter Name =||= Description =||
        ||all_servers        ||           list of all supported AUTHSERV hosts (sxmpa 2/13/2010 - I cannot find anywhere in the AUTHSERV gateway code where this configuration variable is read out of runtime.cfg) ||
        ||authserv_agent    ||   RDN of credentials utilized by AUTHSERV web gateway for unauthenticated directory access ||
        ||authserv_gateway_link   ||      URL to AUTHSERV web gateway ||
        ||authserv_server_link       ||   URL to server specific AUTHSERV web gateway (Equalizer issue) ||
        ||authserv_gateway_name   ||      name of AUTHSERV web gateway ||
        ||authserv_passwd_file       ||   path reference to authserv_agent password file ||
        ||authserv_server_link    ||      URL to server specific AUTHSERV web gateway (Equalizer issue) ||
        ||debug             ||            0|1: debugging is ON when value is 1 ||
        ||directory_adminupdate_link  ||  URL to update interface for admin updates (record creation, not attribute updates) ||
        ||directory_bulkupdate_link  ||   URL to update interface for self service attribute updates ||
        ||directory_gateway_link  ||      URL to EDIR web gateway ||
        ||directory_instance       ||     iPlanet directory instance ||
        ||directory_server_link    ||     URL to EDIR web gateway utilized by server to server POST processes ||
        ||local_announcements_file    ||  path reference to local announcements text file ||
        ||lock_file           ||          path reference to file used to disable AUTHSERV updates ||
        ||log_dir              ||         path reference to AUTHSERV log location ||
        ||mail_from         ||            email address used in FROM of mail generated for AUTHSERV ||
        ||mail_host        ||             email domain expected in vanity addresses ||
        ||mail_to            ||           address list for recipients of troubleshooting/batch reporting email ||
        ||privileged_agent      ||        RDN of credentilas utilized by by AUTHSERV web gateway to access privileged information ||
        ||privileged_agent_passwd_file ||  path reference to authserv_agent password file
        ||query_servers       || list of servers that may respond to query requests.  ''Note: (sxmpa 2/13/2010): This variable should be assigned a single value, which is the host  housing the LDAP server queried by this AUTHSERV gateway instance.  The AUTHSERV 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.'' ||
        ||registry_agent    ||            Oracle schema for AUTHSERV registry ||
        ||registry_db         ||          Oracle instance for AUTHSERV registry ||
        ||registry_passwd_file   ||       path reference to registry_agent password file ||
        ||release             ||          major release number for AUTHSERV web gateway ||
        ||slapd_port         ||           port for iPlanet directory access ||
        ||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. ''Note: (sxmpa 2/13/2010) I cannot find anywhere in the AUTHSERV gateway code where this variable is read out of runtime.cfg).'' ||
        ||version         ||              gateway instance: TEST PREP or PROD ||

        ''Note:'' runtime.cfg files are machine specific. Do not copy between servers.

== Libraries ==

Libraries are located at $HOME/AUTHSERV<''INST''>/cgi-bin/) for every instance.

=== authserv_lib.pm ===

Perl Sub procedures are identified by the demarcation of "sub Authenticate", e.g.  In the listing below for lib.pm, the "sub" portion of the procedure is dropped.

        ||= Library Sub Procedure =||= Description =||
        || 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 ||
        || !CampusPickList      || generates generic HTML form element for campus picklist using  ldap_uakEmployeeCampus.txt as input ||
        || Credentials      || generates HTML form elements for LDAP credentials (id and password) ||
        || UAclose      || generates closing HTML elements for standard window look and feel ||
        || UAopen      || generates opening HTML elements for standard window look and feel ||
        || abort      || uses mailx to send $body with $subject to $MAILTO ||
        || appendMsg       || formats $msg_in according to $msg_type and appends to $MSG ||
        || bldgCampusPickList  || generates HTML form element for building pick list for MAU ||
        || 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) ||
        || bldgPicklist      || generates HTML form element for building pick list ||
        || crypt       || simple encryption of strings; used to encrypt password before storing in LDAP cookie ||
        || debug      || utility used to record debugging information (utilizes debug runtime config parm) ||
        || deptUnitPickList       || generates HTML form element for department picklist; elements of list taken from external file ldap_deptUnits.txt ||
        || embeddedAttributes      || (may be obsolete; was formatting solution for uakPhonebookFlag attribute,  the values of which could represent an unlimited number of MAU specific   phonebook "attributes") ||       
        || employeeCampusPickList    || generates HTML form element for an employee's campus picklist using ldapsearch to locate that employee's uakEmployeeCampus attribute values  ||        
        || employeeDeptPickList    || generates generic HTML form element for campus picklist using  ldap_uakEmployeeAffiliation.txt ||
        || 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 ||
        || formatLabel      || formats field descriptions with or without accompanying comments ||
        || formatValue      || formats attribute values, generating href tags for specific attribute types ||
        || genClearCookie      || Generates Set-Cookie metadata that clears old cookie (where ldapstring is assumed to be the cookie being cleared) ||
        || genClearSimpleCookie      || Generates Set-Cookie metadata that clears new simple cookie (where  name/value are passed to funtion). ||
        || genSetCookie      || Generates Set-Cookie metadata that establishes a specific cookie (new or old) ||
        || getACL      || Returns hash of permissions for requested list of ACL names. ||
        || 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 ||
        || getEntityDisplayLabel      ||   function returning one of DISPLAY_NAME, TITLE_<something>, UNITDISPLAYNAME, UNITNAME or UID from an array of attributes passed to the function ||
        || getUserAttributes      || returns array of attribute=value pairs for $filter  ||
        || getSecureAttributes     || returns array of attribute=value pairs for $filter (utilizes privilege  credentials) ||
        || log_registry_error      || appends text to a SID specific registry error log ||
        || pad  || returns string padded with character to specified length ||
        || parseCookie      || parses old, complex cookie; returning the UID, password, name and role elements  ||
        || parseDN      || parses $dn and returns UID and OU elements ||
        || parseSimpleCookie     || parses new simple cookie; returning a single string value  ||
        || prefixMsg       || like appendMsg but adds text to start of message string ||
        || post_admin        || executes HTTPS request to call ldap_bulk_admin CGI script as though  from the web (utilizes directory_server_link runtime config parm) ||
        || post_updates      || executes HTTPS request to call ldap_bulk_update CGI script as though  from the web (utilizes directory_server_link runtime config parm) ||
        || 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) ||
        || simpleIdentity     || generates HTML form elements prompting for UA Username and elements  of default password (last for of SSN and birthdate) ||
        || stockBoilerPlate     || generates HTML, stock or "style" specific, displayed only in the various log in or password change related pages ||
        || studentDeptPickList   || generates generic HTML form element for student department picklist using  ldap_uakStudentAffiliation.txt ||
        || tokenCleanUP     || deletes authentication tokens where age is greater than the expecte lifetime ||
        || 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) ||
        || connect         || establishes ORACLE_HOME and executes DBI->connect utilizing $eff_login to establish $dbh ||
        || evaluate         || executes $dbh->prepare on $sql to establishes $sth ||
        || execute         || performs $sth->execute which executes sql statement in Oracle database ||
        || getSecureAttributes    || returns array of attribute=value pairs for $filter (utilizes privileged credentials) ||


== CGI Scripts ==
CGI scripts are located at $HOME/AUTHSERV<''INST''>/cgi-bin/) for every instance.

''Note:''All update processing is performed by the UPDATE gateway which reports success or failure 
to the calling CGI script.
        ||= CGI Script Name =||= Description =||
	||activate                      ||  generates form utilized to request account activation ||
	||admin_lock                    ||  generates form utilized to request administrative lock/unlock of account; administrative locks can be performed only by users with edirAdmin role ||
	||authenticate                  ||  generates form used to authenticate using directory credentials ||
	||bulk_update                   ||  generates form used to submit updates in bulk ||
	||change_history                ||  generates form used to view UPDATE gateway logs ||
	||first_time                    ||  generates form used to authenticate using id and elements of default password ||
	||home                          ||  generates home page for AUTHSERV interface in which AUTHSERV cookie is set ||
	||lock                          ||  generates form used to request lock/unlock of account; normal locks can be set and removed by users with helpDesk role ||
	||logout                        ||  generates logout page which destroys AUTHSERV cookie ||
	||passwd_chg -> authenticate    ||  link to authenticate; when called as passwd_chg, additional fields  are displayed for new password ||
	||passwd_help                   ||  generates help text and positions display at section on passwords ||
	||post_reset -> first_time      ||  link to first time; when called as post_reset, introductory text is modified ||
	||reset                         ||  generates form used to change password during authentication ||
	||seed_group                    ||  generates form used to create ou=group records ||
	||seed_resource                 ||  generates form used to create ou=resource records ||
	||self_reset                    ||  generates form used to perform self reset of directory password ||
	||self_reset_help               ||  generates help text displayed to users if they click on corresponding link in page collecting the security question/response used by self  reset process ||
	||self_reset_setup              ||  generates form used to change self reset related attributes ||
	||simpleSearch                  ||  ???? (research) ???? ||
	||smallauth -> authenticate     ||  link to authenticate; results in small footprint authentication form ||
	||sponsor_account               ||  generates form used to create (if not already exists) and sponsor ou=people  records for Banner entities and/or for guests ||
	||sponsor_account_help          ||  generated help text specific to sponsoring accounts ||
	||token_cleanup                 ||  deletes token files where the age of the file exceeds expected life time ||
	||validate                      ||  page called by registered AUTHSERV clients to confirm authentication token  supplied with redirect from AUTHSERV; results in confirmation of redirect and additional attributes (if so registered) ||

######################################################## [[br]]
LEGACY CHANGE HISTORY - NOTE: All subsequent changes are recorded in TracWiki [[br]]
######################################################## [[br]]

20081031 elm	added reference to runtime_common.cfg