NAME

OpenInteract2::Auth - Base class for logging in OpenInteract users

SYNOPSIS

 # Set the classes responsible for the various auth pieces (in server
 # configuration, default is normally ok)
 
 [login]
 auth_user_class      = OpenInteract2::Auth::User
 auth_group_class     = OpenInteract2::Auth::Group
 auth_admin_class     = OpenInteract2::Auth::AdminCheck
 ...
 
 # Call from your adapter (most common):
 
 my $auth_info = OpenInteract2::Auth->new()->login();
 
 # Hey, you picked up a user from somewhere (e.g., HTTP auth)
 
 my $auth_info = OpenInteract2::Auth->new({ user => $user });
 $auth_info->login();
 
 # Wow, a user AND groups? Okay, you're the boss...
 
 my $auth_info = OpenInteract2::Auth->new({ user   => $user,
                                            groups => $groups });
 $auth_info->login();

 # Require that all users be logged into your site; users not logged
 # in always see /login.html unless they request one of the URL
 # patterns specified in 'required_skip'
 
 [login]
 ...
 required             = 0
 required_url         = /login.html
 required_skip        = ^/$
 required_skip        = ^/index.html$
 required_skip        = ^/Login.*
 required_skip        = ^/help.*

 # Define a custom handler to run with each login
 
 [login]
 ...
 custom_login_handler = My::Auth::Class
 custom_login_method  = login

DESCRIPTION

Parent class for OpenInteract2 authentication. Normally the adapter (the mod_perl content handler, CGI script, event handler, etc.) will just call 'login()' and let everything sort itself out.

But if you're getting a user from somewhere else (HTTP authentication, out of a hat, etc.) then you can pass in a user and OI will gladly accept it, looking up the groups to which the user object belongs and making them available.

The classes used by this class are all soft-settable via the server configuration. Check under the 'login' key for the various settings. This means you can implement your own user location methodology, or (perhaps more common) your own code to indicate whether a user is an administrator.

METHODS

Class Methods

new( \%params )

Creates a new auth object. You can pass in any of the properties 'user', 'groups', 'is_admin', 'is_logged_in' in \%params and they'll be assigned as if you called the mutator.

Object Methods

login()

Sets the user and groups in the request object and checks whether this user and/or one of the member groups is an administrator. The term 'administrator' is highly amorphous; here it only determines whether the request auth_is_admin call will return true or not.

If the user is not already set in the object we call get_user() on the class set in the 'login.auth_user_class' configuration key. That should return a two-item list. The first is a user object and the second a flag indicating whether the user is actually logged in. These get passed to the auth_user and auth_is_logged_in mutators of the request object. Both are also set in the auth object.

Once the user is set we also call create_theme on the request object.

Next, if there are no groups already set we call get_groups() on the class set in the 'login_auth_group_class' configuration key, passing the user and logged-in flag. That should always return an arrayref. It should be filled with groups that user belongs to, but no matter what it should at least be an empty arrayref. These groups should also be set in the auth object.

Next, we call is_admin() on the class set in the 'login.auth_admin_class', passing in the auth object. This returns a boolean which we pass to the auth_is_admin method of the request object. The admin checking method should also set it in this auth object.

Next we check the login requirement status. If logins are not required (server configuration key 'login.required' is undefined), if the user is logged in or if the requested URL (without the deployment context) matches one of the patterns in 'login.required_skip' then we move on to the next step. Otherwise we set the requested URL to 'login.required_url' so that OI will internally always display its content, no matter what URL the user requests.

Finally, if there's a custom handler and method defined ('login.custom_handler' and 'login.custom_method', respectively) we call it, passing in the auth object as the first and only argument.

Object Properties

user( [ $user ] )

User for this request. May be a 'fake' user, one not actually existing in the system. If it is then the is_logged_in property should return undef.

is_logged_in( [ 'yes' | 'no' ] )

Returns 'yes' if the user from user() is actually logged in, undef otherwise.

is_admin( [ 'yes' | 'no' ] )

Returns 'yes' if the user from user() is an administrator, undef otherwise.

groups()

Returns the groups user() is a member of.

SEE ALSO

OpenInteract2::Auth::AdminCheck

OpenInteract2::Auth::Group

OpenInteract2::Auth::User

COPYRIGHT

Copyright (c) 2002-2005 Chris Winters. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Chris Winters <chris@cwinters.com>

cpanm OpenInteract2::URL

perl -MCPAN -e shell
install OpenInteract2::URL