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

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>

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