David Golden > Dancer-Plugin-Auth-Tiny-0.002 > Dancer::Plugin::Auth::Tiny

Download:
Dancer-Plugin-Auth-Tiny-0.002.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.002   Source  

NAME ^

Dancer::Plugin::Auth::Tiny - Require logged-in user for specified routes

VERSION ^

version 0.002

SYNOPSIS ^

  use Dancer::Plugin::Auth::Tiny;

  get '/private' => needs login => sub { ... };

  get '/login' => sub {
    # put 'return_url' in a hidden form field
    template 'login' => { return_url => params->{return_url} };
  };

  post '/login' => sub {
    if ( _is_valid( params->{user}, params->{password} ) ) {
      session user => params->{user},
      return redirect params->{return_url} || '/';
    }
    else {
      template 'login' => { error => "invalid username or password" };
    }
  };

  sub _is_valid { ... } # this is up to you

DESCRIPTION ^

This Dancer plugin provides an extremely simple way of requiring that a user be logged in before allowing access to certain routes.

It is not "Tiny" in the usual CPAN sense, but it is "Tiny" with respect to Dancer authentication plugins. It provides very simple sugar to wrap route handlers with an authentication closure.

The plugin provides the needs keyword and a default login wrapper that you can use like this:

  get '/private' => needs login => $coderef;

The code above is roughly equivalent to this:

  get '/private' => sub {
    if ( session 'user' ) {
      goto $coderef;
    }
    else {
      return redirect uri_for( '/login',
        { return_url => uri_for( request->path, request->params ) } );
    }
  };

It is up to you to provide the '/login' route, handle actual authentication, and set user session variable if login is successful.

If the original request contains a parameter in the passthrough list, it will be added to the login query. For example, http://example.com/private?user=dagolden will be redirected as http://example.com/login?user=dagolden&return_url=.... This facilitates pre-populating a login form.

CONFIGURATION ^

You may override any of these settings:

EXTENDING ^

The class method extend may be used to add (or override) authentication criteria. For example, to add a check for the session 'is_admin' key:

  Dancer::Plugin::Auth::Tiny->extend(
    admin => sub {
      my ($coderef) = @_;
      return sub {
        if ( session "is_admin" ) {
          goto $coderef;
        }
        else {
          redirect '/access_denied';
        }
      };
    }
  );

  get '/super_secret' => needs admin => sub { ... };

It takes key/value pairs where the value must be a closure generator that wraps arguments passed to needs.

You could pass additional arguments before the code reference like so:

  # don't conflict with Dancer's any()
  use Syntax::Keyword::Junction 'any' => { -as => 'any_of' };

  Dancer::Plugin::Auth::Tiny->extend(
    any_role => sub {
      my $coderef = pop;
      my @requested_roles = @_;
      return sub {
        my @user_roles = @{ session("roles") || [] };
        if ( any_of(@requested_roles) eq any_of(@user_roles) {
          goto $coderef;
        }
        else {
          redirect '/access_denied';
        }
      };
    }
  );

  get '/parental' => needs any_role => qw/mom dad/ => sub { ... };

SEE ALSO ^

For more complex Dancer authentication, see:

For password authentication algorithms for your own '/login' handler, see:

ACKNOWLEDGMENTS ^

This simplified Auth module was inspired by Dancer::Plugin::Auth::Extensible by David Precious and discussions about its API by member of the Dancer Users mailing list.

SUPPORT ^

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at https://github.com/dagolden/dancer-plugin-auth-tiny/issues. You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

https://github.com/dagolden/dancer-plugin-auth-tiny

  git clone git://github.com/dagolden/dancer-plugin-auth-tiny.git

AUTHOR ^

David Golden <dagolden@cpan.org>

COPYRIGHT AND LICENSE ^

This software is Copyright (c) 2012 by David Golden.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004
syntax highlighting: