CGI::LDAPSession - CGI cookie authentication against an LDAP database
Provides a simple API authenticate users against an LDAP server, and then to cache this authentication information between invokations of CGI scripts without sending passwords subsequent to login. The state information is maintained in a combination of a cookie, a database, and a magic passkey which is sent in the contents of the web page. Acquiring the login thus requires stealing both the cookie and a current copy of the web page. CGI::LDAPSession also contains a subclass of CGI which transparently injects the passkey into forms. It is strongly suggested that you use this class.
use CGI::LDAPSession; use CGI;
my $cgi = new CGI::LDAPSession::CGI; my $session = new CGI::LDAPSession( $cgi ); $cgi->session( $session );
$session->auth_servers( [ new CGI::LDAPSession::LDAPServer( 'ldap.server.my.domain', # host 389, # port 'ou=my,ou=domain', # root 'ou=people,ou=my,ou=domain' # base 'uid=$username,ou=people,ou=my,ou=domain' # bind ) ] ); $session->cookie_table( 'myCookieTable' );
my $action = $cgi->param('action'); my $passkey = $cgi->param('passkey'); if ( defined $action and $action eq 'Log In' ) { my $username = $cgi->param('username'); my $password = $cgi->param('password'); if ( $session->authenticated( $username, $password ) ) { $session->set_passkey( $user ); $session->set_login_cookie( $user ); # Notice that we use $session->header and not $cgi->header # print $session->header(); print $cgi->start_html( 'Login Succeeded' ); ... # The passkey is sent via the cgi wrapper. # my $passkey = $session->passkey; print $cgi->start_form( -action=>'http://my.stupid/script.cgi' ); print ...your form here... print $cgi->end_form; ... print $cgi->end_html; exit 0; } else { ... Login Failed ... exit 0; } }
my $passkey = $cgi->param('passkey'); if ( defined $passkey and !$session->confirm_userlogin( $passkey ) ) { print $session->header(); print $cgi->start_html( 'Open Session' ); ... my $passkey = $session->passkey; print $cgi->start_form( -action=>'http://my.stupid/script.cgi' ); print ...your form here... print $cgi->end_form; ... print $cgi->end_html; exit 0; } else { ... Authentication Failed Page ... }
$session->set_logout_cookie; print $session->header; print $cgi->start_html( 'Logout Complete' ); print "You have logged out."; print $cgi->end_html; exit 0;
CGI.pm CGI::Carp DBI (and at least one DBD) Mozilla::LDAP Date::Format
When a user first authenticates the LDAP database is consulted. If the user is successfully authenticated the information is cached. For subsequent login attempts. The successful login is recorded in a database, and opaque references to this information are passed back to the client.
One of the opaque references is a cookie which is managed by the client, and the other is a randomly chosen string which is passed within the content of the web pages. The random string is referred to as a passkey, and it must be resent with every page.
On subsequent executions the cookie and the passkey are checked. If either of these do not match the record in the database then the user is rejected.
When the program is complete the user is logged out by expiring the cookie.
There are four major operations. The first is setting up the CGIviaLDAP. Gotta do this every time. The second is authenticating a new user/connection. The third is authenticating an existing session. The fourth is logging out an existing session. ( And somewhere in there you have to send the cookie and passkey back to the client. )
The first step is to include the necessary libraries. These are CGI::LDAPSession.pm and CGI.
use CGI::LDAPSession::CGI; use CGI::LDAPSession;
The second step is to create the CGI::LDAPSession object which will be used. It requires a CGI object when it is created. The CGI object provides the machinery to manage cookies.
my $cgi = new CGI::LDAPSession::CGI; my $session = new CGI::LDAPSession( $cgi ); $cgi->session( $cgi );
Now you have to tell the CGIviaLDAP several things. You have to tell it which LDAP servers it should use for authentication. You need to tell it how to connect to the database. You need to describe the database table in which it will store its information. You need to describe the cookie that it will send to the client's web browser. Finally, you need to describe various aspects of the login behavior.
$session->auth_servers( new CGI::LDAPSession::LDAPServer( -host=>'my.host.my.domain', -port=>389, -bind=>'uid=$username,ou=people,dc=my,dc=domain' ) );
The string '$username' within the -bind argument will be replaced with the username when authentication occurrs.
You can also supply more than one ldap server by passing an array of servers. The servers will be checked from first to last in the array.
my $server1 = new CGI::LDAPSession::LDAPServer( -host=>'ldap1.my.domain', -port=>389, -bind=>'uid=$username,ou=people,dc=my,dc=domain' ); my $server2 = new CGI::LDAPSession::LDAPServer( -host=>'ldap2.your.domain', -port=>389, -bind=>'uid=$username,ou=people,dc=your,dc=domain' ); $session->auth_servers( [ $server1, $server2 ] );
CGIviaLDAP uses perl DBI modules to access the database. There are three items of major importance. These are the connection DN, the the database user, and their associated password.
$session->dbi_dn( 'dbi:mysql:my_apps_database' ); $session->dbi_username( 'my_apps_user' ); $session->dbi_password( '!CENSORED' );
You've now told the object how to connect to the database. Now you need to tell it what the table it stores the information in will look like. The most important is the name of the table in which the information will be stored.
$session->cookie_table( 'login_cookies' );
There are three columns it expects. The first is the name of the user; the second is the contents of the cookie; and the third is the passkey. By default these are called, respectively, 'user_id', 'cookie', and 'cookie', and 'passkey'. You may never need to change these. If you do need to change them then you would write:
$session->user_column('username'); $session->cookie_column('login_cookie'); $session->passkey_column('login_passkey');
When your program sends back a cookie, the cookie needs to have several parameters set. These include the name of the cookie, the path which it covers, the domain for which it is good, and wether or not it should be used without a secure connection.
$session->cookie_name( 'MySessionCookie123587098' ); # The name of the cookie $session->cookie_path( '/' ); $session->cookie_domain( '.drinktomi.com' ); $session->secure( 1 ); # 1=requires secure transport # 0=does not require secure transport
Most importantly you need describe how long the cookie should be valid for. This is the expiration. It is given in seconds. If using the refresh option (more on this later) then the expiration determines how long the web browser can sit idle. If not using the refresh option then it determines how long the user will remain logged in.
$session->cookie_expiration( 60*60*2 ); # Cookies will be good for two hours.
Setting the auto refresh cookie option to 1 will the cookie's expiration time to be updated every time a page is sent to the client. As long as the user keeps using the application they will never be logged out.
$session->auto_refresh_cookie(1) # 1=always refresh the session cookie # 0=never automatically refresh the session cookie
In some instances you only want people to log in when they have a pre-existing database entry. In this case there are two ways of managing things. The first is to create an external file containing the valid user IDs. This is kind of a hack.
$session->allowed_user_file( '/var/etc/allowed_users' ); $session->restricted_access( 1 ) # 1=use allowed user file # 0=do not use allowed user file
The second way of managing things is a little more to my taste. Normally the auth object will register the user (create an entry for them) in the cookie table. You can change this so it will not log a person in unless they already have an entry in the cookie table.
$session->register(1); # 1=automatically register users in the cookie table. # 0=do not automatically register users in the cookie table.
Some day we may support check LDAP group memberships as a third mechanism.
You have to do two things. The first is that you have to generate the HTTP header using CGI::LDAPSession instead of CGI, and the second is that you have to make sure that the passkey gets sent back with the results of the next page.
The call CGI::LDAPSession::header is used _exactly_ like CGI::header. The only difference is that it automatically injects the session cookie if it needs to.
print $session->header;
The best way to get the passkey back to the user is by using CGI::LDAPSession::CGI instead of CGI, and using the start_form and end_form functions. These will automatically inject the necessary html. The code looks something like this:
print $cgi->start_form( -action=>$cgi->self_url ); print "YOUR FORM HERE"; print $cgi->end_form;
As long as you use CGI::LDAPSession::CGI then you don't have to do anything else.
If you want to inject passkey into the document yourself then the simplest way is to use a hidden text field. The current passcode is contained in CGI::LDAPSession::passkey. The code to create the form might look something like the next snippet.
print "<form...>" ... my $key = $session->passkey; print "<input type=hidden name=passkey value=$key>"; ... print "</form>"
If you don't send the passkey along then confirmation of the next session login will fail.
Read the user name, and password from the incoming CGI form, and then pass them to CGIviaLDAP::authenticated. If the user is authenticated the we must generate a passkey and a session cookie.
my $username = $cgi->param('username'); my $password = $cgi->param('password'); if ( $session->authenticated( $username, $password ) ) { $session->set_passkey( $username ); $session->set_login_cookie( $username ); ... Successfully authenticated, send response ... } else { ... Login Failed ... }
Read the passkey from the incoming CGI form, and then ask CGIviaLDAP to confirm it. my $key = $cgi->param('passkey'); if ( $session->confirmed($key) ) { ... Session was confirmed and this is a valid session ... } else { ... Session was not confirmed, and this is not a valid session ... }
Once a session has been confirmed you can do several things with it. You can change the passcode; you can change the cookie identifier; or you can refresh the cookie so that the expiration time will be reset.
if ( $session->confirmed( $key ) ) { $session->set_passcode; ... Session was confirmed and this is a valid session ... }
if ( $session->confirmed( $key ) ) { $session->set_login_cookie; ... Session was confirmed and this is a valid session ... }
if ( $session->confirmed( $key ) ) { $session->refresh_login_cookie; ... Session was confirmed and this is a valid session ... }
if ( $session->confirmed( $key ) and $logout ) { $session->set_logout_cookie; ... print $session->header() # You must send back a cookie using the $session print $cgi->start_html( 'Logout Page' ); print "You have been logged out."; # Notice that the passkey does not # need to be sent back. print $cgi->end_html; exit 0; }
Guess what? Once you have configured your CGIviaLDAP there is a function which will create the table that you have described. It only works for MySQL at the moment, but in the future it may work for other databases.
$session->create_cookie_table;
Creates a new session object. Requires at least one argument. This argument is a CGI object of some kind.
my $cgi = new CGI::LDAPSession::CGI; my $session = new CGI::LDAPSession( $cgi );
You can then set values with function calls. Or, you can use the handy-dandy '-PARAMETER=>VALUE' syntax just like the standard module CGI.pm uses. This is in fact the prefered method, and I strongly suggest that you use it.
my $cgi = new CGI::LDAPSession::CGI; my $session = new CGI::LDAPSession( $cgi, -auth_servers => [ $ldap1, $ldap2 ], -dbi_dn => 'dbi:mysql:stock', -cookie_table => 'everyones_cookies', -dbi_username => 'your_mythical_db_user', -dbi_password => 'its_password', -cookie_expiration => 900, -cookie_name => '1FA6FAACE01B7A2677', -cookie_path => '/', -cookie_domain => '.inktomi.com', -cookie_secure => 0, -passkey_name => 'passkey', -restricted_access => 0, -register => 1, -auto_refresh_cookie => 1 );
The name of the cookie that will be passed back to the browser.
The lifetime of the cookie in seconds.
The path of the cookie.
The domain of the cookie.
If set to 1 (-cookie_secure=>1) then SSL will be required for this connection. If set to 0 or undef then then normal http can be used. Defaults to 1.
Points to either a single authentication server, or an anonymous array of authentication servers. Currently authentication servers are defined using CGI::LDAPSession::LDAPServer. Others may be added in the future. (At that time this will become a very poorly named module.) my $ldap1 = new CGI::LDAPSession::LDAPServer( -host=>'ldap.inktomi.com', -port=>389, -bind=>'uid=$username,ou=People,dc=inktomi,dc=com' ); my $ldap2 = new CGI::LDAPSession::LDAPServer( -host=>'mccoy.inktomi.com', -port=>389, -bind=>'uid=$username,ou=People,dc=inktomi,dc=com' ); $session => new CGI::LDAPSession( $cgi, -auth_servers => $ldap1 ); --or-- $session => new CGI::LDAPSession( $cgi, -auth_servers => [ $ldap1, $ldap2 ] );
This is set to either a 1 or 0 (undef is the same as 0). If set to a one then access will be restricted to those users which are specfied in the file corresponding to -allowed_user_file. This file contains the names of the users which can be successfully authenticated. One username is listed on each line of this file.
The full path to a file containing the usernames of the users which can be successfully authenticated. Each line of the file contains one username. If a user is not specified in this file then authentication will fail. This file is only consulted if -restricted_access is set to 1.
DANGER. The password for a back door. If this value is set to 0 or undef then no back door exists. This is ONLY A TESTING feature. DO NOT SET THIS VARIABLE IN PRODUCTION CODE.
If set to 1 then an entry is automatically created in the cookie table if one does not exist. If set to 0 then authentication will fail if the user does not exist.
The DBI connection string which will be used to connect to the database.
The username which will be used to connect to the database.
The password which will be used to connect to the database.
The database table in which the cookie information will be stored.
The column in the cookie_table containing the username.
The column in the cookie_table containing the passkey.
The column in the cookie_table containing the cookie value.
The column in the cookie_table containing the session expiration time.
The name of the CGI parameter which contains the passkey.
Set to non-zero to generate debugging information.
Creates the database tables that are described by a CGI::LDAPSession. my $session = new CGI::LDAPSession; $session->create_cookie_table; exit; Fill out your CGI::LDAPSession just like your going to make a connection. Call this routine, and voila! Your database tables are created.
Accessor method. The cgi to which the session is attached.
Accessor method. The value of the current cookie.
Accessor method. The value of the current passkey. Set by confirmed() and authenticated().
Accessor method. Authentication state. True if the session has been successfully authenticated. False if it has not.
These accessor methods specify the details of the cookies which are generated.
Accessor method. The name of the login cookie. Use cookie_name instead.
Accessor method. The name of the login cookie. Use this instead of cookie_logged_in.
Accessor method. Vestigial logout cookie. Unused. Like the wings of an archeopertyx. But with no hairy feathers.
Accessor method. The lifetime of the cookie specified in seconds.
Accessor method. The path of the cookie.
Accessor method. The domain of the cookie.
Accessor method. True if the cookie requires SSL. False otherwise.
These are variables which affect the behavior of the authentication mechanism.
Accessor method. The list of authentication servers which will be contacted. This value can either be a single server or a reference to an array of servers.
Currently these servers are definied by CGI::LDAPSession::LDAPServer objects.
Accessor method. If set to a non-zero value then the allowed_user_file is turned on.
Accessor method. The full path to the allowed_user_file.
Accessor method. Boy this one sucks. This is a backdoor value. If this is set then any user matching this ID will be successfully authenticated. Why? Strictly for testing. NEVER, EVER SET THIS VALUE UNLESS YOU KNOW WHAT THE FUCK YOU ARE DOING.
Accessor method. Login requires an entry to exist in the cookie table for each user. If this variable is set then an entry will automatically be created for users which are successfully authenticated.
Accessor method. Normally the cookie will expire X seconds after it is created, where X is specified by CGI::LDAPSession::cookie_expiration. Whenever the cookie is refreshed this timer resets. Setting this variable to a non-zero value causes the cookie to be refreshed every time that it is successfully verified.
Forget about this one. This is an internal function used by CGI::LDAPSession and CGI::LDAPSession::CGI. Normally set to zero. Setting CGI::LDAPSession::CGI::session causes this value to be set.
Interal accessor methods pertaining to various aspects of the database connection. These WILL change in future releases, and are documented here for the developer's use.
Accessor method. The active DBI connection. The connection to the database will be created when first required, and the DBI connection will be cached in this variable.
Accessor method. Internal use only. The current DBI statement.
Accessor method. Internal use only. The current results object.
Accessor method. Internal use only. The prefetched results from a results object. Not really necessary with DBI, but I haven't altered the original authentication logic that required this.
These are variables which are used to make the database connection. They must be specified in order to make a connection.
Accessor method. DBI connection string.
Accessor method. Password for the connection.
Accessor method. Username for the connection.
The names of the database tables.
Accessor method. The name of the cookie table.
Accessor method. The column containing the usernames.
Accessor method. The column containing the passkey.
Accessor method. The column containing the cookie id.
Accessor method. The expiration time for the cookie. Currently not used, but it will be used in the future.
Accessor method. The name of the passkey field in the form is stored here. Not currently important, but it will be if/when the table becomes a shared resource.
Accessor method. Turns on debugging. Currently this doesn't do much. I need to add more instrumentation.
Internal function. Turns a CGI::LDAPSession::LDAPServer into a Mozilla::LDAP::Utils::ldapArgs. The user to be checked is stored is taken from the -bind variable.
Within the -bind variable the string $username will be replaced with the $user passed to setup_ldap_auth.
$server = new CGI::LDAPSession::LDAPServer( -host => 'myhost', -port => 389, -base => 'ou=People,dc=inktomi,dc=com', -bind => 'uid=$username,ou=People,dc=inktomi,dc=com' ); my %mozilla_ldap = $self->setup_ldap_auth( $ldap_server, $user, $password );
True if the CGI session has a value for the parameter specified with -passkey_name. print "Session has passkey: ".( $session->has_passkey ? "YES" : "NO" )."\n";
The value of the CGI parameter specified by -passkey_name. $passkey_field = $session->passkey_field;
Confirms that the cookie and a passkey constitute a valid login. If the session confirmation succeeds then it will return a true value. If the session confirmation fails then it will return a false value. Once this routine is called the variable of CGI::LDAPSession::is_authenticated will contain the status of the session. The function may be called in one of two ways. You can either let it extract the passkey value on its own, or you can hand it the passkey value to be checked. It is much less work to let it extract the passkey value. if ( $session->confirmed ) { Session was confirmed... } If you want to handle the extraction of the passkey on your own... my $passkey = $cgi->param( 'passkey_name' ); if ( $session->confirmed( $passkey ) ) { Session was confirmed... }
The preferred way of confirming a valid login session. It extracts the cookie and session key from the CGI, checks their validity, and then sets the variable CGI::LDAPSession::is_authenticated. Used as follows:
$session->confirm; if ( $session->is_authenticated ) { Authentication Succeeded } else { Authentication Failed }
Call the method authenticated with the username and password that you want to check. Authenticated will check their validity. If user was successfully authenticated then it will return a true value. If the user was not successfully authenticated then it will return a false value.
Once authenticated is called then is_authenticated will return the authentication status.
$username = $cgi->param('your_username_field'); $password = $cgi->param('your_password_field'); if ( $session->authenticated( $username, $password ) ) { Authentication Succeeded } else { Authentication Failed }
The preferred method of authenticating a user. Call the method authenticate with the username and password that you want to check. Authenticate will check their validity and then set the variable is_authenticated with the status. For example:
$username = $cgi->param('your_username_field'); $password = $cgi->param('your_password_field'); $session->authenticate( $username, $password ); if ( $session->is_authenticated ) { Authentication Succeeded } else { Authentication Failed }
Acts just like CGI.pm's header function, but it injects the authentication cookie.
If you are using CGI::LDAPSession::CGI then this function will not be used. If you are using CGI.pm directly then call this function instead of CGI.pm's header method.
print $session->header; print $cgi->start_html( 'my html' ); ...
Internal function. Checks the database to see if a user has an existing record within the cookie table. True if the cookie table contains an entry for the username, and false if it does not.
if ( $self->user_exists( $username ) ) { ... perform action for defined user ... }
Internal function. Creates an entry for the specified user within the cookie table.
if ( ! $self->user_exists( $username ) ) { $self->register_username( $username ); }
Internal function. Returns the cookie string for the current session. The expiration time is a unix timestamp as returned by the function time(). The expiration time is not a lifetime in seconds.
my $cookie_string = $self->login_cookie( $cookie_name, $expiration_time );
Sets the login cookie for an authenticated session. If a username is not specified then it pulls the username corresponding to the current cookie and passkey combination.
$self->set_login_cookie( $username ); ..or.. $self->set_login_cookie();
Resets the expiration time for the current cookie.
$self->refresh_login_cookie();
Pulls the username for the current cookie/passkey pair from the database.
my $username = $self->username();
Sets the passkey for the current session, and writes it into the backing store. The passkey is chosen randomly. The can either be specified within the call, or if the passkey and cookie are already set it can be extracted automatically by the session.
$self->set_passkey( $username ); ..or.. $self->set_passkey();
Returns a login_cookie which has expired. (Expiration date is set to epoch.)
my $cookie = $self->logout_cookie();
Expires the cookie in the backing store.
my $cookie = $self->set_logout_cookie();
Returns the cookie for this session if it exists. If a cookie does not exist then it returns nothing.
my $login_cookie = $self->check_cookie();
5 POD Errors
The following errors were encountered while parsing the POD:
=pod directives shouldn't be over one line long! Ignoring all 2 lines of content
=over should be: '=over' or '=over positive_number'
You forgot a '=back' before '=head2'
'=item' outside of any '=over'
=over without closing =back
To install CGI::Session, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::Session
CPAN shell
perl -MCPAN -e shell install CGI::Session
For more information on module installation, please visit the detailed CPAN module installation guide.