• NAME
• SYNOPSIS
• DESCRIPTION
• FUNCTIONS
• identify_user
• process_logout
• process_login
• auth_from_cookie
• set_auth_cookies
• clear_invalid_cookies
• check_password
• allow_read
• allow_write
• need_read_auth
• allow_page
• ontology_access
• is_developer
• request_strong_auth
• cmwuser

---

NAME

Communiware::Auth - Provides means to authenticate communiware users

---

SYNOPSIS

        identify_user($gctx, $agent);

        if (need_read_auth($item,$site) && ! allow_read($item,user)) {
                Communiware::Exception::HTTP->throw(code=>403);
        }

        if (allow_write($item, $user)) {
                ...
        }

---

DESCRIPTION

Functions concerned with checking of user access rights.

---

FUNCTIONS

identify_user

        $user_context = identify_user($global_context);

Makes authentication checks, login and logout. Receives Communiware global (request) context object. Checks for login or logout info and if they are provided makes login or logout (and sets authentication cookies appropriately), otherwise checks authentication cookies. In any case sets up request authentication parameters and magic attributes.

identify_user() should be called at start of request handling. In the current scheme it is called from init_context.

process_logout

        process_logout($gctx);

Processes logout, i.e. clears authentication information and cookies.

process_login

        ($user, $real_user) = process_login($gctx, $user);

Handles login parameters (PASSWORD and AUTHOR_ID). If they match, sets up authentication cookies.

Weak authentication cookie AUTHOR_ID is set from AUTHOR_ID and possible WA_EXPIRES parameter defining expiration time in Communiware date format or [+-]\d+[smhdMy] CGI cookie format.

Strong authentication cookie CMWAUTH is set from AUTHOR_ID and current time and cryptographically signed.

auth_from_cookie

        $hash_ref = auth_from_cookie($global_context, $cookie_name);

Makes Communiware request authentication element from authentication cookie $cookie_name. If the cookie is invalid, returns element with true INVALID parameter that leads to resetting the cookie, else returns element with at least AUTHOR_ID parameter set to one derived from cookie.

set_auth_cookies

        set_auth_cookies($gctx, @users);

Sets authentication cookies according to Communiware request authentication information (set by process_login or process_logout functions). Strong authentication cookie CMWAUTH is cryptographically signed.

clear_invalid_cookies

        clear_invalid_cookies($gctx, $user, $real_user);

Resets authentication cookies corresponding to invalid Communiware request authentication elements. Called from identify_user (see identify_user).

check_password

        ($user_name, $status) = check_password($ctx, $user_name, $password);

Checks user's password and return his name and status on match and empty list on non-match or for locked user. For anonymous access returns list of two empty strings.

allow_read

        if (allow_read($user, $item [, $server])) { ... }

Checks if current user is allowed to view current item. If $server is specified, it must be a server of $item. Used for optimization.

Returns true is user allowed to read and false if not.

You should call need_read_auth first and use allow_read only if it returned true. allow_read returns false for item which need no authorization at all.

allow_write

        if (allow_write($user, $item)) { ... }

Returns true if $user is allowed to write to $item. Both $user and $item may be represented by contexts (preferrably) or by IDs (backward compatibility).

need_read_auth

Recieves item and server returns true if item need authorization for read access at all.

allow_page

        if (allow_page($item,$user)) { ... }
        if (allow_page($site,$item,$user)) { ... }

Called from Communiware::HTTP::handler to check whether current user is allowed to see the current page. Expects info in global variables $Communiware::item, $Communiware::CGI-param('AUTHOR_ID')>. If $server is specified, it must be the server of $Communiware::item. This parameter is for optimization only.

ontology_access

        if (ontology_access($user, $site)) {...}

Arguments can be user and site ids as well as ther contextes. Function returns user status if this user has SUPERUSER status or is developer (this means - linked by DEVELOPER link) of this site. Otherwise it returns false (undef).

is_developer

        if (is_developer($user, $site)) { ... }

Returns true iff user $user is a developer of site $site.

request_strong_auth

        request_strong_auth($global_context);

Throws Communiware::Exception::HTTP(code=>401) unless user have strong authentication.

cmwuser

Syntax:

setuser()

Determines Communiware login name of current Unix user. Should be called after Communiware::Init;

This function checks file ~~CONFDIR~~/aliases and if unix-name of the user is listed in the first column of this file, uses name from second column, otherwise tries to find Communiware user with same login name as current unix user.

If user with unix-name found in database or in user-aliases returns id or pair of id and status. Otherwise dies with error.