CGISession
view release on metacpan or search on metacpan
Session/blib/man3/CGI::Session.3 view on Meta::CPAN
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.ds oe o\h'-(\w'o'u*4/10)'e
.ds Oe O\h'-(\w'O'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds v \h'-1'\o'\(aa\(ga'
. ds _ \h'-1'^
. ds . \h'-1'.
. ds 3 3
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
. ds oe oe
. ds Oe OE
.\}
.rm #[ #] #H #V #F C
.SH "NAME"
.PP
.Vb 1
\& CGI::Session - CGI cookie authentication against an LDAP database
.Ve
.SH "ABSTRACT"
.PP
.Vb 3
\& 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.
.Ve
.Vb 4
\& 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.
.Ve
.Vb 2
\& CGI::Session also contains a subclass of CGI which transparently injects
\& the passkey into forms. It is strongly suggested that you use this class.
.Ve
.SH "SYNOPSIS"
.Sh "Setting Things Up"
use \s-1CGI::\s0Session;
use \s-1CGI\s0;
.PP
.Vb 3
\& my $cgi = new CGI::Session::CGI;
\& my $session = new CGI::Session( $cgi );
\& $cgi->session( $session );
.Ve
.Vb 8
\& my $session_store = new CGI::Session::CookieJar::DBI;
\& $session_store->set( -cookie_name=>'cookie_name',
\& -username=>'myuser',
\& -password=>'kjsdfdf',
\& -host=>'dbhost',
\& -database=>'mydb',
\& -cookie_table=>'cookiejar' );
\& $session->set( -cookie_jar => $session_store );
.Ve
.Vb 8
\& $session->auth_servers(
\& [ new CGI::Session::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
\& ) ] );
.Ve
.Vb 1
\& $session->open;
.Ve
.Sh "Performing the Initial Login"
.PP
.Vb 2
\& my $action = $cgi->param('action');
\& my $passkey = $cgi->param('passkey');
.Ve
.Vb 8
\& 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 );
.Ve
.Vb 5
\& # Notice that we use $session->header and not $cgi->header
\& #
\& print $session->header();
\& print $cgi->start_html( 'Login Succeeded' );
\& ...
.Ve
.Vb 4
\& # The passkey is sent via the cgi wrapper.
\& #
\& my $passkey = $session->passkey;
\& print $cgi->start_form( -action=>'http://my.stupid/script.cgi' );
.Ve
.Vb 1
\& print ...your form here...
.Ve
.Vb 14
\& print $cgi->end_form;
\& ...
\& print $cgi->end_html;
\& exit 0;
\& }
\& else
Session/blib/man3/CGI::Session.3 view on Meta::CPAN
\& $cgi->session( $cgi );
.Ve
Now you have to tell the CGIviaLDAP several things. You have to tell it
which \s-1LDAP\s0 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.
.Sh "Setting the Authentication Servers"
.PP
.Vb 3
\& $session->auth_servers( new CGI::Session::LDAPServer( -host=>'my.host.my.domain',
\& -port=>389,
\& -bind=>'uid=$username,ou=people,dc=my,dc=domain' ) );
.Ve
The string \*(L'$username\*(R' within the \-bind argument will be replaced with
the username when authentication occurrs.
.PP
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.
.PP
.Vb 7
\& my $server1 = new CGI::Session::LDAPServer( -host=>'ldap1.my.domain',
\& -port=>389,
\& -bind=>'uid=$username,ou=people,dc=my,dc=domain' );
\& my $server2 = new CGI::Session::LDAPServer( -host=>'ldap2.your.domain',
\& -port=>389,
\& -bind=>'uid=$username,ou=people,dc=your,dc=domain' );
\& $session->auth_servers( [ $server1, $server2 ] );
.Ve
.Sh "Describing the Database Connection"
CGIviaLDAP uses perl \s-1DBI\s0 modules to access the database. There are
three items of major importance. These are the connection \s-1DN\s0, the
the database user, and their associated password.
.PP
.Vb 3
\& $session->dbi_dn( 'dbi:mysql:my_apps_database' );
\& $session->dbi_username( 'my_apps_user' );
\& $session->dbi_password( '!CENSORED' );
.Ve
.Sh "Describing the Database Table"
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.
.PP
.Vb 1
\& $session->cookie_table( 'login_cookies' );
.Ve
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, \*(L'user_id\*(R',
\&'cookie\*(R', and \*(L'cookie\*(R', and \*(L'passkey\*(R'. You may never need to change
these. If you do need to change them then you would write:
.PP
.Vb 3
\& $session->user_column('username');
\& $session->cookie_column('login_cookie');
\& $session->passkey_column('login_passkey');
.Ve
.Sh "Setting Cookie Parameters"
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.
.PP
.Vb 5
\& $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
.Ve
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.
.PP
.Vb 1
\& $session->cookie_expiration( 60*60*2 ); # Cookies will be good for two hours.
.Ve
.Sh "Setting Login Behavior"
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.
.PP
.Vb 2
\& $session->auto_refresh_cookie(1) # 1=always refresh the session cookie
\& # 0=never automatically refresh the session cookie
.Ve
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.
.PP
.Vb 3
\& $session->allowed_user_file( '/var/etc/allowed_users' );
\& $session->restricted_access( 1 ) # 1=use allowed user file
\& # 0=do not use allowed user file
.Ve
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.
.PP
.Vb 2
\& $session->register(1); # 1=automatically register users in the cookie table.
\& # 0=do not automatically register users in the cookie table.
.Ve
Some day we may support check \s-1LDAP\s0 group memberships as a third mechanism.
.Sh "Sending Back a Page"
You have to do two things. The first is that you have to generate the \s-1HTTP\s0 header
using \s-1CGI::\s0Session instead of \s-1CGI\s0, and the second is that you have to make sure
that the passkey gets sent back with the results of the next page.
.PP
The call \s-1CGI::\s0Session::header is used _exactly_ like \s-1CGI::\s0header.
The only difference is that it automatically injects the session
cookie if it needs to.
.PP
.Vb 1
\& print $session->header;
.Ve
The best way to get the passkey back to the user is by using
\s-1CGI::\s0Session::\s-1CGI\s0 instead of \s-1CGI\s0, and using the start_form
and end_form functions. These will automatically inject the
necessary html. The code looks something like this:
.PP
.Vb 3
\& print $cgi->start_form( -action=>$cgi->self_url );
\& print "YOUR FORM HERE";
\& print $cgi->end_form;
.Ve
As long as you use \s-1CGI::\s0Session::\s-1CGI\s0 then you don't have to do
anything else.
.PP
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 \s-1CGI::\s0Session::passkey. The code to create the form
might look something like the next snippet.
.PP
Session/blib/man3/CGI::Session.3 view on Meta::CPAN
If you don't send the passkey along then confirmation of the next
session login will fail.
.Sh "Authenticating a New Session"
Read the user name, and password from the incoming \s-1CGI\s0 form, and then
pass them to CGIviaLDAP::authenticated. If the user is authenticated
the we must generate a passkey and a session cookie.
.PP
.Vb 16
\& 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
\& ...
\& }
.Ve
.Sh "Confirming an Existing Session"
.PP
.Vb 2
\& Read the passkey from the incoming CGI form, and then ask
\& CGIviaLDAP to confirm it.
.Ve
.Vb 13
\& 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
\& ...
\& }
.Ve
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.
.Sh "Changing the Passcode"
.PP
.Vb 7
\& if ( $session->confirmed( $key ) )
\& {
\& $session->set_passcode;
\& ...
\& Session was confirmed and this is a valid session
\& ...
\& }
.Ve
.Sh "Changing the Cookie Identifier"
.PP
.Vb 7
\& if ( $session->confirmed( $key ) )
\& {
\& $session->set_login_cookie;
\& ...
\& Session was confirmed and this is a valid session
\& ...
\& }
.Ve
.Sh "Refreshing the Cookie Expiration"
.PP
.Vb 7
\& if ( $session->confirmed( $key ) )
\& {
\& $session->refresh_login_cookie;
\& ...
\& Session was confirmed and this is a valid session
\& ...
\& }
.Ve
.Sh "Logging Out"
.PP
.Vb 11
\& 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;
\& }
.Ve
.Sh "Creating the Cookie Table"
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.
.PP
.Vb 1
\& $session->create_cookie_table;
.Ve
.SH "TO DO"
.Ip "1. Provide function to retreive username from the database using the cookie." 4
.Ip "2. Provide support for Net::\s-1LDAP\s0" 4
.Ip "3. Clean up \s-1DBI\s0 code. (\s-1DBI\s0 provides the independence that the old routines did.)" 4
.Ip "4. Clean up \s-1DBI\s0 connection creation. (Makes way too many database connections.)" 4
.Ip "5. Make an \*(N'add_cookie_table\*(T' function to alter existing tables." 4
.Ip "6. Date tracking and garbage collection of expired cookie entries for auto-registered tables." 4
.SH "REFERENCE"
Creates a new session object. Requires at least one argument. This
argument is a \s-1CGI\s0 object of some kind.
.Sp
.Vb 2
\& my $cgi = new CGI::Session::CGI;
\& my $session = new CGI::Session( $cgi );
.Ve
You can then set values with function calls. Or, you can use the
handy-dandy \*(L'\-\s-1PARAMETER\s0=>\s-1VALUE\s0\*(R' syntax just like the standard module
\s-1CGI\s0.pm uses. This is in fact the prefered method, and I strongly
suggest that you use it.
.Sp
.Vb 20
\& my $cgi = new CGI::Session::CGI;
\& my $session = new CGI::Session( $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 );
.Ve
.Sh "Parameters for a new \s-1CGI::\s0Session"
.Ip "-cookie_name" 12
.Sp
.Vb 1
\& The name of the cookie that will be passed back to the browser.
.Ve
.Ip "-cookie_expiration" 12
.Sp
.Vb 1
\& The lifetime of the cookie in seconds.
.Ve
Session/blib/man3/CGI::Session.3 view on Meta::CPAN
.Ip "-debug" 12
.Sp
.Vb 1
\& Set to non-zero to generate debugging information.
.Ve
.Ip "\s-1CGI::\s0Session::open" 4
Internal function. Opens up the cookie jar. This function is called by
methods just before they first access a cookie jar.
.Sp
$session->open;
.Ip "\s-1CGI::\s0Session::cgi" 4
Accessor method. The cgi to which the session is attached.
.Ip "\s-1CGI::\s0Session::cookie" 4
Accessor method. The value of the current cookie.
.Ip "\s-1CGI::\s0Session::passkey" 4
Accessor method. The value of the current passkey. Set by \fIconfirmed()\fR and \fIauthenticated()\fR.
.Ip "\s-1CGI::\s0Session::is_authenticated" 4
Accessor method. Authentication state. True if the session has been successfully authenticated. False if it has not.
.Ip "\s-1CGI::\s0Session::cookie_name" 4
Accessor method. The name of the login cookie.
.Ip "\s-1CGI::\s0Session::cookie_logged_out" 4
Accessor method. Vestigial logout cookie. Unused. Like the wings of an
archeopertyx. But with no hairy feathers. Left here for strictly
archeological reasons.
.Ip "\s-1CGI::\s0Session::cookie_expiration" 4
Accessor method. The lifetime of the cookie specified in seconds.
.Ip "\s-1CGI::\s0Session::cookie_path" 4
Accessor method. The path of the cookie.
.Ip "\s-1CGI::\s0Session::cookie_domain" 4
Accessor method. The domain of the cookie.
.Ip "\s-1CGI::\s0Session::cookie_secure" 4
Accessor method. True if the cookie requires \s-1SSL\s0. False otherwise.
.Ip "Authentication Behavior Variables" 4
These are variables which affect the behavior of the authentication mechanism.
.Ip "\s-1CGI::\s0Session::auth_servers" 4
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.
.Sp
Currently these servers are definied by \s-1CGI::\s0Session::LDAPServer objects.
.Ip "\s-1CGI::\s0Session::restricted_access" 4
Accessor method. If set to a non-zero value then the allowed_user_file is turned on.
.Ip "\s-1CGI::\s0Session::allowed_user_file" 4
Accessor method. The full path to the allowed_user_file.
.Ip "\s-1CGI::\s0Session::unikey" 4
Accessor method. Boy this one sucks. This is a backdoor value. If this is
set then any user matching this \s-1ID\s0 will be successfully authenticated. Why? Strictly
for testing. \s-1NEVER\s0, \s-1EVER\s0 \s-1SET\s0 \s-1THIS\s0 \s-1VALUE\s0 \s-1UNLESS\s0 \s-1YOU\s0 \s-1KNOW\s0 \s-1WHAT\s0 \s-1THE\s0 \s-1FUCK\s0 \s-1YOU\s0 \s-1ARE\s0 \s-1DOING\s0.
.Ip "\s-1CGI::\s0Session::register" 4
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.
.Ip "\s-1CGI::\s0Session::auto_refresh_cookie" 4
Accessor method. Normally the cookie will expire X seconds after it is created, where X is
specified by \s-1CGI::\s0Session::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.
.Ip "\s-1CGI::\s0Session::used_with_custom_cgi" 4
Forget about this one. This is an internal function used by \s-1CGI::\s0Session and \s-1CGI::\s0Session::\s-1CGI\s0.
Normally set to zero. Setting \s-1CGI::\s0Session::\s-1CGI::\s0session causes this value to be set.
.Ip "\s-1CGI::\s0Session::cookie_jar" 4
# Cookiejar. This handles all cookie storage.
#
Accessor method. The object encapsulating cookie storage.
.Ip "\s-1CGI::\s0Session::passkey_name" 4
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.
.Ip "\s-1CGI::\s0Session::debug" 4
Accessor method. Turns on debugging. Currently this doesn't do much. I need
to add more instrumentation.
.Ip "\s-1CGI::\s0Session::has_passkey" 4
.Sp
.Vb 2
\& True if the CGI session has a value for the parameter specified with
\& -passkey_name.
.Ve
.Vb 1
\& print "Session has passkey: ".( $session->has_passkey ? "YES" : "NO" )."\en";
.Ve
.Ip "\s-1CGI::\s0Session::passkey_field" 4
.Sp
.Vb 1
\& The value of the CGI parameter specified by -passkey_name.
.Ve
.Vb 1
\& $passkey_field = $session->passkey_field;
.Ve
.Ip "\s-1CGI::\s0Session::confirmed" 4
.Sp
.Vb 3
\& 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.
.Ve
.Vb 3
\& Once this routine is called the variable of
\& CGI::Session::is_authenticated will contain the status of the
\& session.
.Ve
.Vb 4
\& 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.
.Ve
.Vb 4
\& if ( $session->confirmed )
\& {
\& Session was confirmed...
\& }
.Ve
.Vb 1
\& If you want to handle the extraction of the passkey on your own...
.Ve
.Vb 5
\& my $passkey = $cgi->param( 'passkey_name' );
\& if ( $session->confirmed( $passkey ) )
\& {
\& Session was confirmed...
\& }
.Ve
Session/blib/man3/CGI::Session.3 view on Meta::CPAN
.Ve
.Ip "\s-1CGI::\s0Session::refresh_login_cookie" 0
Resets the expiration time for the current cookie.
.PP
.Vb 1
\& $self->refresh_login_cookie();
.Ve
.Ip "\s-1CGI::\s0Session::user($)" 0
The cached name.
.PP
.Vb 1
\& my $username = $self->user();
.Ve
.Ip "\s-1CGI::\s0Session::username($)" 0
Pulls the username for the current cookie/passkey pair from
the database or local cache.
.PP
.Vb 1
\& my $username = $self->username();
.Ve
.Ip "\s-1CGI::\s0Session::logout_cookie" 0
Returns a login_cookie which has expired. (Expiration date
is set to epoch.)
.PP
.Vb 1
\& my $cookie = $self->logout_cookie();
.Ve
.rn }` ''
.IX Title "Session 3"
.IX Name "CGI::Session - CGI cookie authentication against an LDAP database"
.IX Header "NAME"
.IX Header "ABSTRACT"
.IX Header "SYNOPSIS"
.IX Subsection "Setting Things Up"
.IX Subsection "Performing the Initial Login"
.IX Subsection "Confirming an Existing Session"
.IX Subsection "Logging out of an Existing Session"
.IX Header "REQUIRES"
.IX Header "DESCRIPTION"
.IX Header "USAGE"
.IX Subsection "Setting up the Authentication Object"
.IX Subsection "Setting the Authentication Servers"
.IX Subsection "Describing the Database Connection"
.IX Subsection "Describing the Database Table"
.IX Subsection "Setting Cookie Parameters"
.IX Subsection "Setting Login Behavior"
.IX Subsection "Sending Back a Page"
.IX Subsection "Authenticating a New Session"
.IX Subsection "Confirming an Existing Session"
.IX Subsection "Changing the Passcode"
.IX Subsection "Changing the Cookie Identifier"
.IX Subsection "Refreshing the Cookie Expiration"
.IX Subsection "Logging Out"
.IX Subsection "Creating the Cookie Table"
.IX Header "TO DO"
.IX Item "1. Provide function to retreive username from the database using the cookie."
.IX Item "2. Provide support for Net::\s-1LDAP\s0"
.IX Item "3. Clean up \s-1DBI\s0 code. (\s-1DBI\s0 provides the independence that the old routines did.)"
.IX Item "4. Clean up \s-1DBI\s0 connection creation. (Makes way too many database connections.)"
.IX Item "5. Make an \*(N'add_cookie_table\*(T' function to alter existing tables."
.IX Item "6. Date tracking and garbage collection of expired cookie entries for auto-registered tables."
.IX Header "REFERENCE"
.IX Subsection "Parameters for a new \s-1CGI::\s0Session"
.IX Item "-cookie_name"
.IX Item "-cookie_expiration"
.IX Item "-cookie_path"
.IX Item "-cookie_domain"
.IX Item "-cookie_secure"
.IX Item "-auth_servers"
.IX Item "-restricted_access"
.IX Item "-allowed_user_file"
.IX Item "-unikey"
.IX Item "-register"
.IX Item "-dbi_dn"
.IX Item "-dbi_username"
.IX Item "-dbi_password"
.IX Item "-cookie_table"
.IX Item "-user_column"
.IX Item "-passkey_column"
.IX Item "-cookie_column"
.IX Item "-cookie_name_column"
.IX Item "-login_expiration_column. \s-1CURRENTLY\s0 \s-1UNUSED\s0"
.IX Item "-passkey_name"
.IX Item "-debug"
( run in 2.121 seconds using v1.01-cache-2.11-cpan-39bf76dae61 )