.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Catalyst::ActionRole::ACL 3pm"
.TH Catalyst::ActionRole::ACL 3pm "2012-07-13" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Catalyst::ActionRole::ACL \- User role\-based authorization action class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& package MyApp::Controller::Foo;
\& use Moose;
\& use namespace::autoclean;
\&
\& BEGIN { extends \*(AqCatalyst::Controller\*(Aq }
\&
\& sub foo
\& :Local
\& :Does(ACL)
\& :RequiresRole(admin)
\& :ACLDetachTo(denied)
\& {
\&     my ($self, $c) = @_;
\&     ...
\& }
\&
\& sub denied :Private {
\&     my ($self, $c) = @_;
\&
\&     $c\->res\->status(\*(Aq403\*(Aq);
\&     $c\->res\->body(\*(AqDenied!\*(Aq);
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides a reusable action role
for user role-based authorization.
ACLs are applied via the assignment of attributes to
application action subroutines.
.SH "REQUIRED ATTRIBUTES"
.IX Header "REQUIRED ATTRIBUTES"
Failure to include the following required attributes will result in an exception
when the ACL::Role action's constructor is called.
.SS "ACLDetachTo"
.IX Subsection "ACLDetachTo"
The name of an action to which the request should be detached if it is
determined that ACLs are not satisfied for this user and the resource he
is attempting to access.
.SS "RequiresRole and AllowedRole"
.IX Subsection "RequiresRole and AllowedRole"
The action must include at least one of these attributes, otherwise the Role::ACL
constructor will throw an exception.
.SH "Processing of ACLs"
.IX Header "Processing of ACLs"
One or more roles may be associated with an action.
.PP
User roles are fetched via the invocation of the context \*(L"user\*(R" object's \*(L"roles\*(R"
method.
.PP
Roles specified with the RequiresRole attribute are checked before roles
specified with the AllowedRole attribute.
.PP
The mandatory ACLDetachTo attribute specifies the name of the action to which
execution will detach on access violation.
.PP
ACLs may be applied to chained actions so that different roles are required or
allowed for each link in the chain (or no roles at all).
.PP
ACLDetachTo allows us to short-circuit traversal of an action chain as soon as
access is denied to one of the actions in the chain by its \s-1ACL\s0.
.SS "Examples"
.IX Subsection "Examples"
.Vb 8
\& # this is an invalid action
\& sub broken
\& :Local
\& :Does(ACL)
\& {
\&     my ($self, $c) = @_;
\&     ...
\& }
\&
\& This action will cause an exception because it\*(Aqs missing the ACLDetachTo attribute
\& and has neither a RequiresRole nor an AllowedRole attribute. A Role::ACL action
\& must include at least one RequiresRole or AllowedRole attribute.
\&
\& sub foo
\& :Local
\& :Does(ACL)
\& :RequiresRole(admin)
\& :ACLDetachTo(denied)
\& {
\&     my ($self, $c) = @_;
\&     ...
\& }
.Ve
.PP
This action may only be executed by users with the 'admin' role.
.PP
.Vb 10
\& sub bar :Local
\& :Does(ACL)
\& :RequiresRole(admin)
\& :AllowedRole(editor)
\& :AllowedRole(writer)
\& :ACLDetachTo(denied)
\& {
\&     my ($self, $c) = @_;
\&     ...
\& }
.Ve
.PP
This action requires that the user has the 'admin' role and
either the 'editor' or 'writer' role (or both).
.PP
.Vb 9
\& sub easy :Local
\& :Does(ACL)
\& :AllowedRole(admin)
\& :AllowedRole(user)
\& :ACLDetachTo(denied)
\& {
\&     my ($self, $c) = @_;
\&     ...
\& }
.Ve
.PP
Any user with either the 'admin' or 'user' role may execute this action.
.SH "WRAPPED METHODS"
.IX Header "WRAPPED METHODS"
.ie n .SS """BUILD( $args )"""
.el .SS "\f(CWBUILD( $args )\fP"
.IX Subsection "BUILD( $args )"
Throws an exception if parameters are missing or invalid.
.ie n .SS """execute( $controller, $c )"""
.el .SS "\f(CWexecute( $controller, $c )\fP"
.IX Subsection "execute( $controller, $c )"
Overrides &Catalyst::Action::execute.
.PP
In order for delegation to occur, the context 'user' object must exist (authenticated user) and
the \f(CW\*(C`can_visit\*(C'\fR method must return a true value.
.PP
See Catalyst::Action
.ie n .SS """can_visit( $c )"""
.el .SS "\f(CWcan_visit( $c )\fP"
.IX Subsection "can_visit( $c )"
Return true if the authenticated user can visit this action.
.PP
This method is useful for determining in advance if a user can execute
a given action.
.SH "AUTHOR"
.IX Header "AUTHOR"
David P.C. Wollmann <converter42@gmail.com>
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Converted from an action class to an action role by Tomas Doran (t0m)
.SH "BUGS"
.IX Header "BUGS"
This is new code. Find the bugs and report them, please.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2009 by David P.C. Wollmann
.PP
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.