NAME

AxKit::XSP::Auth - Authorization tag library for AxKit eXtensible Server Pages.

SYNOPSIS

Add the auth: namespace to your XSP <xsp:page> tag:

    <xsp:page
         language="Perl"
         xmlns:xsp="http://apache.org/xsp/core/v1"
         xmlns:auth="http://www.creITve.de/2002/XSP/Auth"
    >

Add this taglib to AxKit (via httpd.conf or .htaccess):

    AxAddXSPTaglib AxKit::XSP::Auth

You must add the Session taglib as well, and if you plan to use <login>, then also the Globals taglib.

DESCRIPTION

The XSP session taglib provides authorization management to XSP pages. It allows you to view, check and modify access permissions for users (logging in and out) and the effective permissions of an object (file, directory or subtarget). Moreover, it provides utilities for password handling.

This taglib works in conjunction with Apache::AxKit::Plugin::Session, which does all the hard work. There are several configuration variants available, see the man page for details.

Authorization Scheme

Users are authorized via their associated session object. The session object may contain varying authorization information. This is in contrast to most other schemes where a user has a fixed, static set of access permissions. You can easily create pages which need extra confirmation to access with this mechanism. Another consequence is that a user may be logged in multiple times at the same time. This is checked and prevented when using <auth:login>, though.

Each user has a set of access permissions, or accesses. Each access consists of a type and a value or a list of values which grant that access. Each target file has a set of permissions, which may be inherited. Each permission consists of a type and a value or list of values. How the user's access is compared to the value of the permission depends on the type: user and group grant if any member of the access value matches a member of the permission's value. level grants if the user's level is greater than or equal the permission level. Moreover, using 'not', 'combined' and 'alternate', you can create more complex requirements. Overall access is granted if any permission grants access.

Each page can have subtargets which can be given different permissions from the page itself. This can be used for example to give anyone access to a guestbook but let the admin see the recorded ip addresses. Subtargets are referenced as <page>#<subtarget>.

Storing permissions

The default implementation (see Apache::AxKit::Plugin::Session) uses the Apache configuration directive 'require' to store permissions. This unfortunately means that modifying permissions is usually impossible and unusually dangerous. You have to subclass the default implementation in order to store them somewhere else.

Tag Reference

User access privileges

These tags work on the user privileges.

<auth:get-access>, <auth:get-single-access>

This tag retrieves the access permissions for the current session. It returns an XML fragment that could theoretically be passed back into auth:set-access. This is not possible though within one xsp run.

<auth:get-single-access> is just a convenience tag for retrieving exactly one type of access information suitable for processing in perl code. For this tag, a 'type' attribute is mandatory.

<auth:set-access>, <auth:add-access>

These tags modify the user's access privileges. They take a set of <auth:access type="some-type" value="some-value"/> nodes. set-access works absolute, it replaces all accesses with the input set, while add-access merges the existing accesses with the input set. Do not even think of trying to add more than one user or level - You will be denied any permission of that type afterwards. To modify the level, remove it, then add a new value.

<auth:rem-access>

This tag removes entries from the users access set. It takes input like set-access. If you leave out the value, any access of that type is removed, else only exact matches are revoked.

<auth:has-access>

Takes attributes/children 'type' and 'value'. Returns true if the user currently has access privilege type 'type' equal to / containing 'value'.

<login>

This tag logs in a user name. It works just like set-access, but additionally the user name is checked and any existing session of that user is invalidated, so that users can be logged in only once. Moreover, an external redirect is triggered. You can provide a 'destination' attribute or child tag to set the destination location, otherwise, the HTTP request parameter 'destination' is used. If you set 'destination' to "none", no redirect is performed.

You can add the parameter <exclusive="no"> to allow a user to be logged in multiple times. Note that you need globals enabled to have the exclusive-login mechanism to work.

<logout>

This tag invalidates the current session, thus logging the user out. If you supply a 'destination' tag or attribute, or if the server config specifies one, a redirect is triggered.

Object permission tags

These tags work on permissions of objects. Targets are generally specified as an attribute or child element called 'target'. An empty target denotes the current page. Permissions are nested <permission> tags with a 'type' attribute (or child) and either other permission tags or a text value inside.

<get-permission>

This tag returns a node set of all permissions the given target has.

<set-permission>, <add-permission>

These tags attempts to modify a target's permission set. In the default implementation this is only possible if you find out how to enable it yourself, since it is dangerous.

<rem-permission>

ditto. Note that only exact matching permissions are removed.

Misc tags

These tags perform miscellaneous useful stuff.

<is-logged-in>

This tag checks if the current user has logged in. It returns 1 or 0.

<deny-permission>

This tag aborts the page with a 'access denied' error code. It takes an attribute or child tag 'reason' which contains a symbolic reason to be examined later, and a list of <text lang=".."> tags which specify human readable messages.

<has-permission>

This tag checks if the current user is allowed to access a resource. It takes a target specification like get-permission. It returns 1 or 0.

<check-permission>

This tag checks if the current user is allowed to access a resource and aborts the current page if not. It takes a target specification like get-permission and a reason code and message list like deny-permission.

<random-password>

This tag returns a random password suitable for sending it to users. It consists of 6 letters or digits, both upper and lower case. There are some checks made to make sure it doesn't contain an offensive word.

<encrypt-password>

This tag encrypts its contents as a password and inserts the result.

<password-matches>

This tag checks if a password matches an encrypted password. Pass the passes in child tags or attributes named 'clear' and 'encrypted'. Returns 1 or 0.

<get-reason>

This tag returns a symbolic value which describes the last auth error. This can be used to explain a foreced logout to the user (session expired, IP address mismatch, or others). There is currently no list of possible error codes. An empty value means "no error". An unknown error most likely results in 'bad_session_provided'.

<get-location>

This tag returns the URI associated with the reason returned by <auth:get-reason>.

<clear-reason>

This tag clears the reason.

<set-reason>

This tag sets the symbolic value described above.

BUGS

This software has beta quality. Use with care and contact the author if any problems occur.

AUTHOR

Jörg Walter <jwalt@cpan.org>

COPYRIGHT

Copyright (c) 2002 Jörg Waltr All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

AxKit, Apache::Session, Apache::AxKit::Plugin::Session, AxKit::XSP::Session, AxKit::XSP::Global

cpanm Apache::AxKit::Plugin::Session

perl -MCPAN -e shell
install Apache::AxKit::Plugin::Session