view release on metacpan or  search on metacpan

lib/Dancer2/Plugin/Auth/YARBAC.pm  view on Meta::CPAN

This means when deciding if a user is authorised we could require they be logged in, or have 
a specifc role, or specific group, or a specific group with a specific permission and so on. 
To put it another way, this design moves the access control down to the role-group 
relationship thus allowing one to quickly and easily see, assign or revoke permissions to a 
user even when dealing with a fairly complex authorisation environment. 

The logical flow of this design looks like so:

                                               +------------+
                                            -->| PERMISSION |
                                +-------+   |  +------------+
                             -->| GROUP |---- 
                 +------+    |  +-------+      +------------+
              -->| ROLE |----               -->| PERMISSION |
              |  +------+    |  +-------+   |  +------------+
              |              -->| GROUP |----
              |                 +-------+   |  +------------+
              |                             -->| PERMISSION |
  +------+    |                                +------------+
  | USER |----|                              
  +------+    |                                +------------+
              |                             -->| PERMISSION |
              |                 +-------+   |  +------------+
              |              -->| GROUP |---- 
              |  +------+    |  +-------+   |  +------------+
              -->| ROLE |----               -->| PERMISSION |
                 +------+    |  +-------+      +------------+
                             -->| GROUP |----
                                +-------+   |  +------------+
                                            -->| PERMISSION |
                                               +------------+

Of course just because there are users, roles, groups and permissions doesn't mean 
you have to use them. This module will happily function even if you just care 
about user authentication. Or perhaps you're just interested in users and roles,
this is also fine.

=head1 AUTHENTICATION BACKEND PROVIDERS

This framework allows the use of different backend providers.
At time of writing only the Database backend is available.

=over 4

=item L<Dancer2::Plugin::Auth::YARBAC::Provider::Database>

Authentication and authorisation using a database backend.

=back

Want to create your own provider backend? No problem, 
just write a Moo based module (or similar oo) and use it to extend
L<Dancer2::Plugin::Auth::YARBAC::Provider::Base> 
then implement the required methods and you're done.

=head1 CONTROLLING AUTHENTICATION ACCESS

There are three ways you can control authentication access to your app. 
One is using the keyword 'hook_before_require_login' which is a global 
check for all routes. 
This is handy if your app is mostly locked down with only a few exceptions. 
The exceptions can be specified in your apps config using the option 
'no_login_required' and putting in exempt routes here as a regex. 
The second option is to use the keyword 'require_login' which must be 
set on each route you wish authentication to be a requirement. 
This is handy when most of your app is open to the big wide 
world but you've got a few routes that need protecting. 
The third option is the keyword 'logged_in_user' which is
more manual but handy if the default behavour of URL
redirecting is getting in your way. 

=over

=item hook_before_require_login - Add on 'hook before', requires user to be logged in

  hook before => hook_before_require_login sub {
    
  };

If the user attempts to access a route that's not exempt via the config 
option regex 'no_login_require' then they will be redirected 
to whatever URL was specified in the apps config using the option 
'login_denied'.

=item require_login - Add to any route, requires user to be logged in

    get '/auth/is/required' => require_login sub {
        
    };

If the user attempts to access this route and they are not logged 
in they'll be redirected to whatever URL was specified 
in the apps config using the option 'login_denied'.

=item logged_in_user - Checks if user is logged in.

  get '/' => sub {
    unless ( logged_in_user ) {
        # user isn't logged in.
    }

    template 'index', {};
  };

If the user is logged in, the keyword 'logged_in_user' 
will return the logged in user as a hashref.
If the user is not logged in, it returns false.

=back

=head1 GRANTING AUTHENTICATION ACCESS

There are two ways one can authenticate a user.
The first is using the built in 'login' keyword.
This option will take care of the session management 
for you and redirect the user. Please note,
YARBAC requires you to use a Dancer2 session module
in your app but it doesn't care which one you choose.
The second is using the keyword 'authenticate_user'
which will only check if the username and password
was correct and then report back with a hashref.