wiki:AUTH_gw_scripts

Context Navigation

Version 2 (modified by lttoth@…, 10 years ago) (diff)
--

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)

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

20081031 elm added reference to runtime_common.cfg

Download in other formats:

Plain Text

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

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 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)