NAME
   Mojolicious::Plugin::Authorization - A plugin to make Authorization a
   bit easier

VERSION
   version 1.03

SYNOPSIS
       use Mojolicious::Plugin::Authorization
       $self->plugin('Authorization' => {
           'has_priv'   => sub { ... },
           'is_role'    => sub { ... },
           'user_privs' => sub { ... },
           'user_role'  => sub { ... },
       });
       if ($self->has_priv('delete_all', { optional => 'extra data stuff' })) {
           ...
       }

DESCRIPTION
   A very simple API implementation of role-based access control (RBAC).
   This plugin is only an API 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.

METHODS
 has_priv('privilege', $extra_data) or has_privilege('privilege', $extra_data)
   'has_priv' and 'has_privilege' will use the supplied `has_priv'
   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 `has_priv' subroutine as-is.

 is('role',$extra_data) / is_role('role,$extra_data)
   'is' / 'is_role' will use the supplied `is_role' 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 `is_role'
   subroutine as-is.

 privileges($extra_data)
   'privileges' will use the supplied `user_privs' 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
   `user_privs' subroutine as-is. The returned data is dependant on the
   supplied `user_privs' subroutine.

 role($extra_data)
   'role' will use the supplied `user_role' 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 `user_role' subroutine
   as-is. The returned data is dependant on the supplied `user_role'
   subroutine.

CONFIGURATION
   The following options must be set for the plugin:

   has_priv (REQUIRED) A coderef for checking to see if the current session
   has a privilege (see "HAS PRIV").
   is_role (REQUIRED) A coderef for checking to see if the current session
   is a certain role (see "IS ROLE").
   user_privs (REQUIRED) A coderef for returning the privileges of the
   current session (see "PRIVILEGES").
   user_role (REQUIRED) A coderef for retiring the role of the current
   session (see "ROLE").

 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 `has_priv'
   configuration key has the following signature:

       sub {
           my ($app, $privilege,$extradata) = @_;
           ...
       }

   You must return either 0 for a fail and 1 for a pass. This allows
   `ROUTING VIA CONDITION' to work correctly.

 IS / IS ROLE
   'is' / 'is_role' is used when you need to confirm that the current
   session is set to the given role. The coderef you pass to the `is_role'
   configuration key has the following signature:

       sub {
           my ($app, $role, $extradata) = @_;
           ...
           return $role;
       }

   You must return either 0 for a fail and 1 for a pass. This allows
   `ROUTING VIA CONDITION' to work correctly.

 PRIVILEGES
   'privileges' is used when you need to get all the privileges of the
   current session. The coderef you pass to the `user_privs' configuration
   key has the following signature:

       sub {
           my ($app,$extradata) = @_;
           ...
           return $privileges;
       }

   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.

 ROLE
   'role' is used when you need to get the role of the current session. The
   coderef you pass to the `user_privs' configuration key has the following
   signature:

       sub {
           my ($app,$extradata) = @_;
           ...
           return $role;
       }

   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.

EXAMPLES
   For a code example using this, see the t/01-functional.t test, it uses
   Mojolicious::Lite and this plugin.

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.

       $r->route('/delete_all')->over(has_priv => 'delete_all')->to('mycontroller#delete_all');
       my $delete_all_only = $r->route('/members')->over(has_priv => 'delete_all')->to('members#delete_all');
       $delete_all_only->route('delete')->to('members#delete_all');

   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.

   Another condition you can use to limit access to certain documents to
   only those sessions that have a role.

       $r->route('/view_all')->over(is => 'ADMIN')->to('mycontroller#view_all');
       my $view_all_only = $r->route('/members')->over(is => 'view_all')->to('members#view_all');
       $view_all_only->route('view')->to('members#view_all');

   If the session is not the 'ADMIN' 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 "has" condition.

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 URL was correct while the 404 tells them
   nothing. This is just my opinion.

SEE ALSO
   Mojolicious::Sessions, Mojocast 3: Authorization

AUTHOR
   John Scoles, `<byterock at hotmail.com>'

BUGS / CONTRIBUTING
   Please report any bugs or feature requests through the web interface at
   https://github.com/byterock/mojolicious-plugin-authorization/issues.

SUPPORT
   You can find documentation for this module with the perldoc command.
   perldoc Mojolicious::Plugin::Authorization You can also look for
   information at:

   * AnnoCPAN: Annotated CPAN documentation
   http://annocpan.org/dist/Mojolicious-Plugin-Authorization
   * CPAN Ratings
   http://cpanratings.perl.org/d/Mojolicious-Plugin-Authorization
   * Search CPAN
   http://search.cpan.org/dist/Mojolicious-Plugin-Authorization/

ACKNOWLEDGEMENTS
   Ben van Staveren (madcat)

       -   For 'Mojolicious::Plugin::Authentication' which I used as a guide in writing up this one.

   Chuck Finley

       -   For staring me off on this.

   Abhijit Menon-Sen

       -   For the routing suggestions

   Roland Lammel

       -   For some other good suggestions

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 GNU
   General Public License as published by the Free Software Foundation; or
   the Artistic License. See http://dev.perl.org/licenses/ for more
   information.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.