.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" 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" '' . ds C` . ds C' '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. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" 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 "Mojolicious::Plugin::Authorization 3pm" .TH Mojolicious::Plugin::Authorization 3pm "2014-03-03" "perl v5.18.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" Mojolicious::Plugin::Authorization \- A plugin to make Authorization a bit easier .SH "VERSION" .IX Header "VERSION" version 1.03 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 10 \& use Mojolicious::Plugin::Authorization \& $self\->plugin(\*(AqAuthorization\*(Aq => { \& \*(Aqhas_priv\*(Aq => sub { ... }, \& \*(Aqis_role\*(Aq => sub { ... }, \& \*(Aquser_privs\*(Aq => sub { ... }, \& \*(Aquser_role\*(Aq => sub { ... }, \& }); \& if ($self\->has_priv(\*(Aqdelete_all\*(Aq, { optional => \*(Aqextra data stuff\*(Aq })) { \& ... \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" A very simple \s-1API\s0 implementation of role-based access control (\s-1RBAC\s0). This plugin is only an \s-1API\s0 you will have to do all the work of setting up your roles and privileges and then provide four subs that are used by the plugin. The plugin expects that the current session will be used to get the role its privileges. It also assumes that you have already been authenticated and your role set. That is about it you are free to implement any system you like. .SH "METHODS" .IX Header "METHODS" .ie n .SS "has_priv('privilege', $extra_data) or has_privilege('privilege', $extra_data)" .el .SS "has_priv('privilege', \f(CW$extra_data\fP) or has_privilege('privilege', \f(CW$extra_data\fP)" .IX Subsection "has_priv('privilege', $extra_data) or has_privilege('privilege', $extra_data)" \&'has_priv' and 'has_privilege' will use the supplied \f(CW\*(C`has_priv\*(C'\fR subroutine ref to check if the current session has the given privilege. Returns true when the session has the privilege or false otherwise. You can pass additional data along in the extra_data hashref and it will be passed to your \f(CW\*(C`has_priv\*(C'\fR subroutine as-is. .SS "is('role',$extra_data)" .IX Subsection "is('role',$extra_data)" \&'is' will use the supplied \f(CW\*(C`is_role\*(C'\fR subroutine ref to check if the current session is the given role. Returns true when the session has privilege or false otherwise. You can pass additional data along in the extra_data hashref and it will be passed to your \f(CW\*(C`is_role\*(C'\fR subroutine as-is. .SS "privileges($extra_data)" .IX Subsection "privileges($extra_data)" \&'privileges' will use the supplied \f(CW\*(C`user_privs\*(C'\fR subroutine ref and return the privileges of the current session. You can pass additional data along in the extra_data hashref and it will be passed to your \f(CW\*(C`user_privs\*(C'\fR subroutine as-is. The returned data is dependent on the supplied \f(CW\*(C`user_privs\*(C'\fR subroutine. .SS "role($extra_data)" .IX Subsection "role($extra_data)" \&'role' will use the supplied \f(CW\*(C`user_role\*(C'\fR subroutine ref and return the role of the current session. You can pass additional data along in the extra_data hashref and it will be passed to your \f(CW\*(C`user_role\*(C'\fR subroutine as-is. The returned data is dependent on the supplied \f(CW\*(C`user_role\*(C'\fR subroutine. .SH "CONFIGURATION" .IX Header "CONFIGURATION" The following options must be set for the plugin: .ie n .IP "has_priv (\s-1REQUIRED\s0) A coderef for checking to see if the current session has a privilege (see ""\s-1HAS PRIV""\s0)." 4 .el .IP "has_priv (\s-1REQUIRED\s0) A coderef for checking to see if the current session has a privilege (see ``\s-1HAS PRIV''\s0)." 4 .IX Item "has_priv (REQUIRED) A coderef for checking to see if the current session has a privilege (see HAS PRIV)." .PD 0 .ie n .IP "is_role (\s-1REQUIRED\s0) A coderef for checking to see if the current session is a certain role (see ""\s-1IS ROLE""\s0)." 4 .el .IP "is_role (\s-1REQUIRED\s0) A coderef for checking to see if the current session is a certain role (see ``\s-1IS ROLE''\s0)." 4 .IX Item "is_role (REQUIRED) A coderef for checking to see if the current session is a certain role (see IS ROLE)." .ie n .IP "user_privs (\s-1REQUIRED\s0) A coderef for returning the privileges of the current session (see ""\s-1PRIVILEGES""\s0)." 4 .el .IP "user_privs (\s-1REQUIRED\s0) A coderef for returning the privileges of the current session (see ``\s-1PRIVILEGES''\s0)." 4 .IX Item "user_privs (REQUIRED) A coderef for returning the privileges of the current session (see PRIVILEGES)." .ie n .IP "user_role (\s-1REQUIRED\s0) A coderef for retiring the role of the current session (see ""\s-1ROLE""\s0)." 4 .el .IP "user_role (\s-1REQUIRED\s0) A coderef for retiring the role of the current session (see ``\s-1ROLE''\s0)." 4 .IX Item "user_role (REQUIRED) A coderef for retiring the role of the current session (see ROLE)." .PD .SS "\s-1HAS PRIV\s0" .IX Subsection "HAS PRIV" \&'has_priv' is used when you need to confirm that the current session has the given privilege. The coderef you pass to the \f(CW\*(C`has_priv\*(C'\fR configuration key has the following signature: .PP .Vb 4 \& sub { \& my ($app, $privilege,$extradata) = @_; \& ... \& } .Ve .PP You must return either 0 for a fail and 1 for a pass. This allows \f(CW\*(C`ROUTING VIA CONDITION\*(C'\fR to work correctly. .SS "\s-1IS\s0" .IX Subsection "IS" \&'is' is used when you need to confirm that the current session is set to the given role. The coderef you pass to the \f(CW\*(C`is_role\*(C'\fR configuration key has the following signature: .PP .Vb 5 \& sub { \& my ($app, $role, $extradata) = @_; \& ... \& return $role; \& } .Ve .PP You must return either 0 for a fail and 1 for a pass. This allows \f(CW\*(C`ROUTING VIA CONDITION\*(C'\fR to work correctly. .SS "\s-1PRIVILEGES\s0" .IX Subsection "PRIVILEGES" \&'privileges' is used when you need to get all the privileges of the current session. The coderef you pass to the \f(CW\*(C`user_privs\*(C'\fR configuration key has the following signature: .PP .Vb 5 \& sub { \& my ($app,$extradata) = @_; \& ... \& return $privileges; \& } .Ve .PP You can return anything you want. It would normally be an arrayref of privileges but you are free to return a scalar, hashref, arrayref, blessed object, or undef. .SS "\s-1ROLE\s0" .IX Subsection "ROLE" \&'role' is used when you need to get the role of the current session. The coderef you pass to the \f(CW\*(C`user_privs\*(C'\fR configuration key has the following signature: .PP .Vb 5 \& sub { \& my ($app,$extradata) = @_; \& ... \& return $role; \& } .Ve .PP You can return anything you want. It would normally be just a scalar but you are free to return a scalar, hashref, arrayref, blessed object, or undef. .SH "EXAMPLES" .IX Header "EXAMPLES" For a code example using this, see the \fIt/01\-functional.t\fR test, it uses Mojolicious::Lite and this plugin. .SH "ROUTING VIA CONDITION" .IX Header "ROUTING VIA CONDITION" This plugin also exports a routing condition you can use in order to limit access to certain documents to only sessions that have a privilege. .PP .Vb 3 \& $r\->route(\*(Aq/delete_all\*(Aq)\->over(has_priv => \*(Aqdelete_all\*(Aq)\->to(\*(Aqmycontroller#delete_all\*(Aq); \& my $delete_all_only = $r\->route(\*(Aq/members\*(Aq)\->over(has_priv => \*(Aqdelete_all\*(Aq)\->to(\*(Aqmembers#delete_all\*(Aq); \& $delete_all_only\->route(\*(Aqdelete\*(Aq)\->to(\*(Aqmembers#delete_all\*(Aq); .Ve .PP If the session does not have the 'delete_all' privilege, these routes will not be considered by the dispatcher and unless you have set up a catch-all route, a 404 Not Found will be generated instead. .PP Another condition you can use to limit access to certain documents to only those sessions that have a role. .PP .Vb 3 \& $r\->route(\*(Aq/view_all\*(Aq)\->over(is => \*(AqADMIN\*(Aq)\->to(\*(Aqmycontroller#view_all\*(Aq); \& my $view_all_only = $r\->route(\*(Aq/members\*(Aq)\->over(is => \*(Aqview_all\*(Aq)\->to(\*(Aqmembers#view_all\*(Aq); \& $view_all_only\->route(\*(Aqview\*(Aq)\->to(\*(Aqmembers#view_all\*(Aq); .Ve .PP If the session is not the '\s-1ADMIN\s0' role, these routes will not be considered by the dispatcher and unless you have set up a catch-all route, a 404 Not Found will be generated instead. This behavior is similar to the \*(L"has\*(R" condition. .SH "ROUTING VIA CALLBACK" .IX Header "ROUTING VIA CALLBACK" It is not recommended to route un-authorized requests to anything but a 404 page. If you do route to some sort of 'You are not allowed page' you are telling a hacker that the \s-1URL\s0 was correct while the 404 tells them nothing. This is just my opinion. .SH "SEE ALSO" .IX Header "SEE ALSO" Mojolicious::Sessions, Mojocast 3: Authorization .SH "AUTHOR" .IX Header "AUTHOR" John Scoles, \f(CW\*(C`\*(C'\fR .SH "BUGS / CONTRIBUTING" .IX Header "BUGS / CONTRIBUTING" Please report any bugs or feature requests through the web interface at . .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. perldoc Mojolicious::Plugin::Authorization You can also look for information at: .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .IP "\(bu" 4 Search \s-1CPAN \s0 .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Ben van Staveren (madcat) .PP .Vb 1 \& \- For \*(AqMojolicious::Plugin::Authentication\*(Aq which I used as a guide in writing up this one. .Ve .PP Chuck Finley .PP .Vb 1 \& \- For staring me off on this. .Ve .PP Abhijit Menon-Sen .PP .Vb 1 \& \- For the routing suggestions .Ve .PP Roland Lammel .PP .Vb 1 \& \- For some other good suggestions .Ve .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2012 John Scoles. This program is free software; you can redistribute it and/or modify it under the terms of either: the \s-1GNU\s0 General Public License as published by the Free Software Foundation; or the Artistic License. See http://dev.perl.org/licenses/ for more information.