Geomap Authentication - Documentation for the Geomap::Auth system
Geomap::Auth is an authentication and authorization system (made up of a collection of mod_perl based modules) which allows restriction of web resources based on multiple criteria. It also provides an interface for users to perform some administration of their own accounts, as well as an interface for Geomap employees to perform additional administrative tasks.
A Geomap::Auth user session may involve several actions. Certain actions are handled directly by Geomap::Auth:
Other actions are handled by Geomap::FormApp applications:
Users are authenticated initially by matching a username and password login against a user table in the database, and thereafter by using a cookie-based session identifier.
Authenticated users are authorized for access to a particular resource by matching
their access level and/or group membership(s) against an access table in the database.
Which access criteria are checked is dependent on the 'require' directives used in
the Apache configuration files. (See the Configuration section.)
When a user first attempts to access a resource that is protected by Geomap::Auth, he/she is presented with a login screen requesting a username and password. If the login is successfully authenticated, the user is given a cookie-based token which is used as a 'ticket' for accessing any resources that are requested.
The user will also be brought to the login screen (with an appropriate 'error' message) anytime he/she requests access to resource for which the authenticated username does not have sufficient access level or group membership.
If a user forgets the login password, he/she can enter the e-mail address under which the account is registered, and be e-mailed a new randomly-generated password.
Geomap customers who have never used Geomap Online can request access by filling out an online form. The access request is sent by e-mail to a Geomap employee, where it can approved or declined.
Requests for access to Geomap Online are sent by e-mail to a Geomap employee, who can approve or decline the request by clicking on the appropriate link in the e-mail message.
If the Geomap employee chooses to approve a request, they must provide a valid
customer account ID which will be linked to the online account. They can also
assign a specific access level and group membership(s) at this time.
A user can change the account password or e-mail address.
An administrator can enable or disable accounts, or modify an account's access level or group membership.
Configuration for the various elements is done in two places:
Actions based on Geomap::Auth (Authentication, Authorization, Login/Logout, Changing Passwords) are configured either in the 'httpd.conf' Apache configuration file or in '.htaccess' files in particular directories.
Here is a standard 'httpd.conf' configuration:
# Configuration of Login process
PerlModule Geomap::Login
<Location /Login>
SetHandler perl-script
PerlHandler Geomap::Login
PerlSetVar AuthDB geomap:localhost
PerlSetVar AuthDBLogin username:password
PerlSetVar TemplatePath "/var/www/templates"
PerlSetVar Template "login.html"
</Location>
# Configuration of Password Change process
PerlModule Geomap::Password
<Location /Password>
SetHandler perl-script
PerlHandler Geomap::Password
PerlSetVar AuthDB geomap:localhost
PerlSetVar AuthDBLogin username:password
PerlSetVar TemplatePath "/var/www/templates"
PerlSetVar Template "password.html"
PerlSetVar ConfirmTemplate "confirm_pass.html"
PerlSetVar EmailTemplate "password.tmpl"
PerlSetVar EmailFrom "Geomap Online<contact@geomap.com>"
</Location>
# Configuration of a protected directory
<Location /apps/protected>
AuthType Geomap
AuthName "Protected"
PerlAuthenHandler Geomap::Auth::authenticate
PerlAuthzHandler Geomap::Auth::authorize
PerlSetVar AuthDB geomap:localhost
PerlSetVar AuthDBLogin username:password
require access-level
require access-group
ErrorDocument 403 /Login
</Location>
Or a directory could be protected by putting a '.htaccess' file in the directory itself:
# .htaccess file AuthType Geomap AuthName "Protected" PerlAuthenHandler Geomap::Auth::authenticate PerlAuthzHandler Geomap::Auth::authorize PerlSetVar AuthDB geomap:localhost PerlSetVar AuthDBLogin username:password require access-level require access-group ErrorDocument 403 /Login
Actions based on Geomap::FormApp (User Sign-up, Self-Administration, User Administration, Account Activation) are configured within the 'geomap.ini' file located in '/var/www'.
The 'geomap.ini' configuration file has a structure similar to that of a Windows .INI file. It consists of a number of sections containing a number of name = value pairs. The file contains a section for each application, plus a 'default' section of values used when no corresponding value is found in the application-specific section.
Geomap::Auth uses Template-Toolkit 2 for its presentation layer. A TT2 template consists of either an HTML file (for page templates) or a plain text file (for e-mail templates) with special embedded tags of the form [% TAG %]. Most tags represent simple values that should be diplayed on the page. However, some tags are used as loop constructs, or for conditional display, or for display formatting.
Templates exist for the following Geomap::Auth elements/pages:
Each Geomap::FormApp-based action will also include its own templates.
The Geomap Authentication system requires an Apache server running mod_perl.
Brad Smithart, <brad@smithart.net>
For Geomap Company