Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Dancer::Plugin::Auth::UsernContributed PerlDancer::Plugin::Auth::Extensible(3)

NAME
       Dancer::Plugin::Auth::Extensible	- extensible authentication framework
       for Dancer apps

DESCRIPTION
       A user authentication and authorisation framework plugin	for Dancer
       apps.

       Makes it	easy to	require	a user to be logged in to access certain
       routes, provides	role-based access control, and supports	various
       authentication methods/sources (config file, database, Unix system
       users, etc).

       Designed	to support multiple authentication realms and to be as
       extensible as possible, and to make secure password handling easy.  The
       base class for auth providers makes handling "RFC2307"-style hashed
       passwords really	simple,	so you have no excuse for storing plain-text
       passwords.  A simple script to generate RFC2307-style hashed passwords
       is included, or you can use Crypt::SaltedHash yourself to do so,	or use
       the "slappasswd"	utility	if you have it installed.

SYNOPSIS
       Configure the plugin to use the authentication provider class you wish
       to use:

	 plugins:
	       Auth::Extensible:
		   realms:
		       users:
			   provider: Example
			   ....

       The configuration you provide will depend on the	authentication
       provider	module in use.	For a simple example, see
       Dancer::Plugin::Auth::Extensible::Provider::Config.

       Define that a user must be logged in and	have the proper	permissions to
       access a	route:

	   get '/secret' => require_role Confidant => sub { tell_secrets(); };

       Define that a user must be logged in to access a	route -	and find out
       who is logged in	with the "logged_in_user" keyword:

	   get '/users'	=> require_login sub {
	       my $user	= logged_in_user;
	       return "Hi there, $user->{username}";
	   };

AUTHENTICATION PROVIDERS
       For flexibility,	this authentication framework uses simple
       authentication provider classes,	which implement	a simple interface and
       do whatever is required to authenticate a user against the chosen
       source of authentication.

       For an example of how simple provider classes are, so you can build
       your own	if required or just try	out this authentication	framework
       plugin easily, see Dancer::Plugin::Auth::Extensible::Provider::Example.

       This framework supplies the following providers out-of-the-box:

       Dancer::Plugin::Auth::Extensible::Provider::Unix
	   Authenticates users using system accounts on	Linux/Unix type	boxes

       Dancer::Plugin::Auth::Extensible::Provider::Database
	   Authenticates users stored in a database table

       Dancer::Plugin::Auth::Extensible::Provider::Config
	   Authenticates users stored in the app's config

       Need to write your own?	Just subclass
       Dancer::Plugin::Auth::Extensible::Provider::Base	and implement the
       required	methods, and you're good to go!

CONTROLLING ACCESS TO ROUTES
       Keywords	are provided to	check if a user	is logged in / has appropriate
       roles.

       require_login - require the user	to be logged in
	       get '/dashboard'	=> require_login sub { .... };

	   If the user is not logged in, they will be redirected to the	login
	   page	URL to log in.	The default URL	is "/login" - this may be
	   changed with	the "login_page" option.

       require_role - require the user to have a specified role
	       get '/beer' => require_role BeerDrinker => sub {	... };

	   Requires that the user be logged in as a user who has the specified
	   role.  If the user is not logged in,	they will be redirected	to the
	   login page URL.  If they are	logged in, but do not have the
	   required role, they will be redirected to the access	denied URL.

       require_any_roles - require the user to have one	of a list of roles
	       get '/drink' => require_any_role	[qw(BeerDrinker	VodaDrinker)] => sub {
		   ...
	       };

	   Requires that the user be logged in as a user who has any one (or
	   more) of the	roles listed.  If the user is not logged in, they will
	   be redirected to the	login page URL.	 If they are logged in,	but do
	   not have any	of the specified roles,	they will be redirected	to the
	   access denied URL.

       require_all_roles - require the user to have all	roles listed
	       get '/foo' => require_all_roles [qw(Foo Bar)] =>	sub { ... };

	   Requires that the user be logged in as a user who has all of	the
	   roles listed.  If the user is not logged in,	they will be
	   redirected to the login page	URL.  If they are logged in but	do not
	   have	all of the specified roles, they will be redirected to the
	   access denied URL.

   Replacing the Default " /login " and	" /login/denied	" Routes
       By default, the plugin adds a route to present a	simple login form at
       that URL.  If you would rather add your own, set	the "no_default_pages"
       setting to a true value,	and define your	own route which	responds to
       "/login"	with a login page.  Alternatively you can let DPAE add the
       routes and handle the status codes, etc.	 and simply define the setting
       "login_page_handler" and/or "permission_denied_page_handler" with the
       name of a subroutine to be called to handle the route. Note that	it
       must be a fully qualified sub. E.g.

	   plugins:
	     Auth::Extensible:
	       login_page_handler: 'My::App:login_page_handler'
	       permission_denied_page_handler: 'My::App:permission_denied_page_handler'

       Then in your code you might simply use a	template:

	   sub permission_denied_page_handler {
	       template	'account/login';
	   }

       If the user is logged in, but tries to access a route which requires a
       specific	role they don't	have, they will	be redirected to the
       "permission denied" page	URL, which defaults to "/login/denied" but may
       be changed using	the "denied_page" option.

       Again, by default a route is added to respond to	that URL with a
       default page; again, you	can disable this by setting "no_default_pages"
       and creating your own.

       This would still	leave the routes "post '/login'" and "any '/logout'"
       routes in place.	To disable them	too, set the option "no_login_handler"
       to a true value.	In this	case, these routes should be defined by	the
       user, and should	do at least the	following:

	   post	'/login' => sub	{
	       my ($success, $realm) = authenticate_user(
		   params->{username}, params->{password}
	       );
	       if ($success) {
		   session logged_in_user => params->{username};
		   session logged_in_user_realm	=> $realm;
		   # other code	here
	       } else {
		   # authentication failed
	       }
	   };

	   any '/logout' => sub	{
	       session->destroy;
	   };

       If you want to use the default "post '/login'" and "any '/logout'"
       routes you can configure	them. See below.

   Keywords
       require_login
	   Used	to wrap	a route	which requires a user to be logged in order to
	   access it.

	       get '/secret' =>	require_login sub { .... };

       require_role
	   Used	to wrap	a route	which requires a user to be logged in as a
	   user	with the specified role	in order to access it.

	       get '/beer' => require_role BeerDrinker => sub {	... };

	   You can also	provide	a regular expression, if you need to match the
	   role	using a	regex -	for example:

	       get '/beer' => require_role qr/Drinker$/	=> sub { ... };

       require_any_role
	   Used	to wrap	a route	which requires a user to be logged in as a
	   user	with any one (or more) of the specified	roles in order to
	   access it.

	       get '/foo' => require_any_role [qw(Foo Bar)] => sub { ... };

       require_all_roles
	   Used	to wrap	a route	which requires a user to be logged in as a
	   user	with all of the	roles listed in	order to access	it.

	       get '/foo' => require_all_roles [qw(Foo Bar)] =>	sub { ... };

       logged_in_user
	   Returns a hashref of	details	of the currently logged-in user, if
	   there is one.

	   The details you get back will depend	upon the authentication
	   provider in use.

       user_has_role
	   Check if a user has the role	named.

	   By default, the currently-logged-in user will be checked, so	you
	   need	only name the role you're looking for:

	       if (user_has_role('BeerDrinker')) { pour_beer();	}

	   You can also	provide	the username to	check;

	       if (user_has_role($user,	$role))	{ .... }

       user_roles
	   Returns a list of the roles of a user.

	   By default, roles for the currently-logged-in user will be checked;
	   alternatively, you may supply a username to check.

	   Returns a list or arrayref depending	on context.

       authenticate_user
	   Usually you'll want to let the built-in login handling code deal
	   with	authenticating users, but in case you need to do it yourself,
	   this	keyword	accepts	a username and password, and optionally	a
	   specific realm, and checks whether the username and password	are
	   valid.

	   For example:

	       if (authenticate_user($username,	$password)) {
		   ...
	       }

	   If you are using multiple authentication realms, by default each
	   realm will be consulted in turn.  If	you only wish to check one of
	   them	(for instance, you're authenticating an	admin user, and
	   there's only	one realm which	applies	to them), you can supply the
	   realm as an optional	third parameter.

	   In boolean context, returns simply true or false; in	list context,
	   returns "($success, $realm)".

   SAMPLE CONFIGURATION
       In your application's configuation file:

	   session: simple
	   plugins:
	       Auth::Extensible:
		   # Set to 1 if you want to disable the use of	roles (0 is default)
		   disable_roles: 0
		   # After /login: If no return_url is given: land here	('/' is	default)
		   user_home_page: '/user'
		   # After /logout: If no return_url is	given: land here (no default)
		   exit_page: '/'

		   # List each authentication realm, with the provider to use and the
		   # provider-specific settings	(see the documentation for the provider
		   # you wish to use)
		   realms:
		       realm_one:
			   provider: Database
			       db_connection_name: 'foo'

       Please note that	you must have a	session	provider configured.  The
       authentication framework	requires sessions in order to track
       information about the currently logged in user.	Please see
       Dancer::Session for information on how to configure session management
       within your application.

AUTHOR
       David Precious, "<davidp	at preshweb.co.uk>"

BUGS / FEATURE REQUESTS
       This is an early	version; there may still be bugs present or features
       missing.

       This is developed on GitHub - please feel free to raise issues or pull
       requests	against	the repo at:
       <https://github.com/bigpresh/Dancer-Plugin-Auth-Extensible>

ACKNOWLEDGEMENTS
       Valuable	feedback on the	early design of	this module came from many
       people, including Matt S	Trout (mst), David Golden (xdg), Damien
       Krotkine	(dams),	Daniel Perrett,	and others.

       Configurable login/logout URLs added by Rene (hertell)

       Regex support for require_role by chenryn

       Support for user_roles looking in other realms by Colin Ewen (casao)

       Config options for default login/logout handlers	by Henk	van Oers
       (hvoers)

LICENSE	AND COPYRIGHT
       Copyright 2012-16 David Precious.

       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.

perl v5.24.1			  2016-09-0Dancer::Plugin::Auth::Extensible(3)

NAME | DESCRIPTION | SYNOPSIS | AUTHENTICATION PROVIDERS | CONTROLLING ACCESS TO ROUTES | AUTHOR | BUGS / FEATURE REQUESTS | ACKNOWLEDGEMENTS | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Dancer::Plugin::Auth::Extensible&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help