NAME

CGI::Bus::uauth - default or base user authentication class

SYNOPSIS

 use CGI::Bus;
 $s =CGI::Bus->new();
 $s->ugroups;         # get groups current user belongs to

 use CGI::Bus;
 $s =CGI::Bus->new();
 $s->set(-login => '/cgi-bin/login-screen.cgi');
 $s->uauth;           # go to login screen

 use CGI::Bus;
 $s =CGI::Bus->new();
 $s->set(-login => undef);
 $s->uauth->authscr   # login script under web server authentication

 use CGI::Bus;
 $s =CGI::Bus->new();
 $s->uauth->loginscr; # ... with authentication by application

DESCRIPTION

This is default or base user authentication class. It provides user, ugroups, uglist, auth methods for CGI::Bus 'user' and 'group' methods, which are wrappers to CGI::Bus::uauth. It contains platform specific methods and may be overwritten in CGI::Bus with '-import'. It implements a three user authentication methods:

Web server user authentication on Win32 IIS or Apache with 'NTLM' module. Win32 operation use Windows 2000 ADSI via Win32::OLE module or 'findgrp.exe' Windows NT Resource Kit utility or Win32API::Net module.

Apache user authentication with 'AuthUserFile' and 'AuthGroupFile'. Apache itself may use 'uagroup' buffer file produced from Windows 2000 ADSI within dpath.

User authentication by application (with loginscr or auth/authscr), where user data are stored within CGI::Bus::udata or its replacement.

Cookie operation (auth, loginscr, signchk, signset, logout) use Digest modules, default is 'MD5'.

Microsoft IIS deimpersonation requires Win32::API for 'RevertToSelf' call.

See CGI::Bus::Base for inherited slots and methods.

SLOTS

-AuthUserFile

Pointer to Apache's 'AuthUserFile'

-AuthGroupFile

Pointer to Apache's 'AuthGroupFile'

-digest

Digest submodule to use with signchk and signset. Default used is 'MD5'

-login

Login screen URL. Used by auth

-udata

If true, user authentication by application will be supposed with CGI::Bus::udata component for ugroups and uglist calls

METHODS

auth (?[types], ?redirect URL)

User authentication request or login operation. Redirect to -login and exit may be used for authentication. Login screen should set $ENV{REMOTE_USER} (by web server or itself) and call auth; signset(?redirect) will be called inside. This operation is for optional web server authentication. It is not needed when web server authentication is set for scripts. loginscr may be used for user authentication by application.

authscr ( ? auth args )

User authentication screen for login scripts under web server authentication. Contains CGI::Bus userauth call, which calls auth. Not authenticated users will be authenticated and redirected back. Authenticated users will get authentication information page with URL to return back. This method is created partially due to possible browser redirection problems.

authurl -> login script call URL

authurl ( return to URL )

authurl ( login script URL, return to URL )

Form and return URL to call login script. Default login script URL is -login. If there is no login script URL, empty string will be returned. If login script URL ends with '/' sign, it is treated as authenticated location, and current script name will to be appended. Default return URL is current script's URL. auth call can redirect to login script, but authurl may be used to place URL to lead user to login script directly and decrease browser redirections.

loginscr ( ?'-lri' ) -> redirect

Login screen operation for user authentication by application. Options: 'l'ogin, 'r'egister user function, user 'i'nfo function, default '-lri'. Use auth instead of loginscr for web server authentication with cookie. See issue about authentication by application.

logout (?redirect) -> exit

Clear user authentication cookie and redirect to URL given or $ENV{HTTP_REFERER}

signchk () -> success

Check authentication cookie. Dies on corrupted. Returns empty if no cookie. Uses Digest

signget () -> [cookie data]

Get authentication cookie data, undef if not exists. May be used to detect authentication cookie existence

signset (?redirect) -> redirect

Set authentication cookie, redirect, exit Uses $ENV{REMOTE_USER} and $ENV{REMOTE_ADDR} for cookie data. Uses Digest

uglist (?-ug) -> [user and groups list]

uglist (?-ug<>, {}) -> {name=>label,...}

List (array ref) of user and group names. Options are: 'u'sers only, 'g'roups only, '<>' force comment notation, default is '-ug'. Form with hash ref may be used to get names and labels of them. Labels begin with user name, comma, and blank sign.

ugroups (?user name) -> [groups of user]

Groups array ref user belongs to. Default is current user.

usdomain () -> User names Server's Domain name

User names Server's Domain name - Windows NT or DNS domain name. See also userver.

user () -> user name

Current user name. Result of web server or script authentication: $ENV{REMOTE_USER} ||$ENV{AUTH_USER}... ||signchk

userver () -> User names Server name

User names Server name - Windows NT or DNS host name. See also usdomain.

VERSION

19/11/2004

ugroups extended with new 'user name' parameter.

03/11/2004

ugroups fixed to return [guest] instead of empty list.

14/09/2004

Evolution to Windows ADSI using Win32::OLE, other Windows interfaces used at last only.

-adsi slot ignored and removed.

Win32::OLE->Option("Warn"=>0) used anywere.

ADSI data buffered in CGI::Bus::dpath for faster access and Apache usage.

05/06/2004

New: Deimpersonation for Microsoft IIS using 'RevertToSelf' via Win32::API. Tried when finished with '/' sign -login URL.

13/06/2002

Changed

ugroups on Win32 returns global group names prefixed with domain name for users from foreign domains.

16/05/2002

Changed

Filtered rows with space chars only 'findgrp.exe' may return.

28/04/2002

New:

-adsi switch, attempting to use a Windows 2000 ADSI, see issues in the source code

15/10/2001 - 23/03/2002

New:

Implemented and Documented

ToDo:

 ? AuthDBMUserFile('user'=>), AuthDBMGroupFile('user'=>'groups')
 ? AuthDBUserFile, AuthDBGroupFile

Issues:

 - All platform and authentication method specifics could not
   be implemented in a one module. Another authentication support
   modules may be needed.
 - Application (password, not web server) authentication interferes
   with web server access control to a files. So, if application
   publishes files via URLs, this URLs should operate via scripts,
   or only web server authentication should be used.

AUTHOR

Andrew V Makarow <makarow at mail.com>

cpanm CGI::Bus

perl -MCPAN -e shell
install CGI::Bus