view release on metacpan or  search on metacpan

lib/AxKit/XSP/Auth.pm  view on Meta::CPAN

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>.

=head2 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.

=head1 Tag Reference

=head2 User access privileges

These tags work on the user privileges.

=head3 C<<auth:get-access>>, C<<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.

=head3 C<<auth:set-access>>, C<<auth:add-access>>

These tags modify the user's access privileges. They take a set of
C<<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.

=head3 C<<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.

=head3 C<<auth:has-access>>

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

=head3 C<<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 C<<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.


=head3 C<<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.

=head2 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 C<<permission>> tags with a 'type' attribute (or child) and either other permission
tags or a text value inside.

=head3 C<<get-permission>>

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

=head3 C<<set-permission>>, C<<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.

=head3 C<<rem-permission>>

ditto. Note that only exact matching permissions are removed.

=head2 Misc tags

These tags perform miscellaneous useful stuff.

=head3 C<<is-logged-in>>

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

=head3 C<<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
C<<text lang="..">> tags which specify human readable messages.

=head3 C<<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.

=head3 C<<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.

=head3 C<<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.

=head3 C<<encrypt-password>>

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

=head3 C<<password-matches>>