Dancer2::Plugin::Auth::Extensible - extensible authentication framework for Dancer2 apps
A user authentication and authorisation framework plugin for Dancer2 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 the Crypt::SaltedHash manpage
yourself to do so, or use the slappasswd utility if you have it installed.
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 the Dancer2::Plugin::Auth::Extensible::Provider::Config manpage.
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}";
};
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 the Dancer2::Plugin::Auth::Extensible::Provider::Example manpage.
This framework supplies the following providers out-of-the-box:
Authenticates users using system accounts on Linux/Unix type boxes
Authenticates users stored in a database table
Authenticates users stored in a database table using the Dancer2::Plugin::DBIC manpage
Authenticates users stored in the app's config
Need to write your own? Just subclass the Dancer2::Plugin::Auth::Extensible::Provider::Base manpage and implement the required methods, and you're good to go!
Keywords are provided to check if a user is logged in / has appropriate roles.
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.
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.
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.
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.
/login and /login/denied RoutesBy 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.
The default routes also contain functionality for a user to perform password resets. See the PASSWORD RESETS documentation for more details.
Used to wrap a route which requires a user to be logged in order to access it.
get '/secret' => require_login sub { .... };
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 { ... };
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 { ... };
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 { ... };
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.
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)) { .... }
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.
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).
Updates a user's details. If the authentication provider supports it, this keyword allows a user's details to be updated within the backend data store.
In order to update the user's details, the keyword should be called with the username to be updated, followed by a hash of the values to be updated. Note that whilst the password can be updated using this method, any new value will be stored directly into the provider as-is, not encrypted. It is recommended to use user_password instead.
If only one realm is configured then this will be used to search for the user. Otherwise, the realm must be specified with the realm key.
# Update user, only one realm configured
update_user "jsmith", surname => "Smith"
# Update a user's username, more than one realm
update_user "jsmith", realm => "dbic", username => "jjones"
The updated user's details are returned, as per logged_in_user.
Creates a new user, if the authentication provider supports it. Optionally sends a welcome message with a password reset request, in which case an email key must be provided.
This function works in the same manner as update_user, except that the username key is mandatory. As with update_user, it is recommended not to set a password directly using this method, otherwise it will be stored in plain text.
The realm to use must be specified with the key realm if there is more
than one realm configured.
# Create new user
create_user username => "jsmith", realm => "dbic", surname => "Smith"
# Create new user and send welcome email
create_user username => "jsmith", email => "john@you.com", email_welcome => 1
On success, the created user's details are returned, as per logged_in_user.
The text sent in the welcome email can be customised in 2 ways, in the same way as password_reset_send:
This can be used to specify a subroutine that will be called to perform the
entire message construction and email sending. Note that it must be a
fully-qualified sub such as My::App:email_welcome_send. The subroutine will
be passed the dsl as the first parameter, followed by a hash with the keys
code, email and user, which contain the generated reset code, user
email address, and user hashref respectively. For example:
sub reset_send_handler {
my ($dsl, %params) = @_;
my $user_email = $params{email};
my $reset_code = $params{code};
# Send email
return $result;
}
This can be used to generate the text for the welcome email, with this module sending the actual email itself. It must be a fully-qualified sub, as per the previous option. It will be passed the same parameters as welcome_send, and should return a hash with the same keys as password_reset_send_email.
password_reset_send sends a user an email with a password reset link. Along
with user_password, it allows a user to reset their password.
The function must be called with the key username and a value that is the
username. The username specified will be sent an email with a link to reset
their password. Note that the provider being used must return the email address
in the key email, which in the case of a database will normally require that
column to exist in the user's table. The provider must be able to write values
to the user in order for this function to store the generated code.
If the username is not found, a value of 0 is returned. If the username is found and the email is sent successfully, 1 is returned. Otherwise undef is returned. Note: if you are displaying a success message, and you do not want people to be able to check the existance of a user on your system, then you should check for the return value being defined, not true. For example:
say "Success" if defined password_reset_send username => username;
Note that this still leaves the possibility of checking the existance of a user if the email send mechanism is failing.
The realm can also be specified using the key realm:
password_reset_send username => 'jsmith', realm => 'dbic'
Default text for the email is automatically produced and emailed. This can be customized with one of 2 config parameters:
This can be used to specify a subroutine that will be called to perform the
entire message construction and email sending. Note that it must be a
fully-qualified sub such as My::App:reset_send_handler. The subroutine will
be passed the dsl as the first parameter, followed by a hash with the keys
code and email, which contain the generated reset code and user email
address respectively. For example:
sub reset_send_handler {
my ($dsl, %params) = @_;
my $user_email = $params{email};
my $reset_code = $params{code};
# Send email
return $result;
}
This can be used to generate the text for the email, with this module sending the actual email itself. It must be a fully-qualified sub, as per the previous option. It will be passed the same parameters as password_reset_send_email, and should return a hash with the following keys:
The subject of the email message.
The sender of the email message (optional, can also be specified using
mail_from.
Plain text for the email. Either this, or html, or both should be returned.
HTML text for the email (optional, as per plain).
Here is an example subroutine:
sub reset_text_handler {
my ($dsl, %params) = @_;
return (
from => '"My name" <myapp@example.com',
subject => 'the subject',
plain => "reset here: $params{code}",
);
}
# Example configuration
Auth::Extensible:
mailer:
module: Mail::Message # Module to send email with
options: # Module options
via: sendmail
mail_from: '"My app" <myapp@example.com>'
password_reset_text: MyApp::reset_send
This provides various functions to check or reset a user's password, either from a reset code that was previously send by password_reset_send or directly by specifying a username and password. Functions that update a password rely on a provider that has write access to a user's details.
By default, the user to update is the currently logged-in user. A specific user
can be specified with the key username for a certain username, or code
for a previously sent reset code. Using these parameters on their own will
return the username if it is a valid request.
If the above parameters are specified with the additional parameter
new_password, then the password will be set to that value, assuming that it
is a valid request.
The realm can be optionally specified with the keyword realm.
Examples:
Check the logged-in user's password:
user_password password => 'mysecret'
Check a specific user's password:
user_password username => 'jsmith', password => 'bigsecret'
Check a previously sent reset code:
user_password code => 'XXXX'
Reset a password with a previously sent code:
user_password code => 'XXXX', new_password => 'newsecret'
Change a user's password (username optional)
user_password username => 'jbloggs', password => 'old', new_password => 'secret'
Force set a specific user's password, without checking existing password:
user_password username => 'jbloggs', new_password => 'secret'
A variety of functionality is provided to make it easier to manage requests from users to reset their passwords. The keywords password_reset_send and user_password form the core of this functionality - see the documentation of these keywords for full details. This functionality can only be used with a provider that supports write access.
When utilising this functionality, it is wise to only allow passwords to be reset with a POST request. This is because some email scanners "open" links before delivering the email to the end user. With only a single-use GET request, this will result in the link being "used" by the time it reaches the end user, thus rendering it invalid.
Password reset functionality is also built-in to the default route handlers.
To enable this, set the configuration value reset_password_handler to a true
value (having already configured the mail handler, as per the keyword
documentation above). Once this is done, the default login page will contain
additional form controls to allow the user to enter their username and request
a reset password link.
If using login_page_handler to replace the default login page, you can still
use the default password reset handlers. Add 2 controls to your form for
submitting a password reset request: a text input called username_reset for the
username, and submit_reset to submit the request. Your login_page_handler is
then passed the following additional params:
Contains the new automatically-generated password, once the password reset has been performed successfully.
Is true when a password reset has been emailed to the user.
Is true when a valid password reset code has been submitted with a GET request.
In this case, the user should be given the chance to confirm with a POST
request, with a form control called confirm_reset.
For a full example, see the default handler in this module's code.
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: '/'
# Mailer options for reset password and welcome emails
mailer:
module: Mail::Message # Email module to use
options: # Options for module
via: sendmail # Options passed to $msg->send
mail_from: '"App name" <myapp@example.com>' # From email address
# Set to true to enable password reset code in the default handlers
reset_password_handler: 1
# Password reset functionality
password_reset_send_email: My::App::reset_send # Customise sending sub
password_reset_text: My::App::reset_text # Customise reset text
# create_user options
welcome_send: My::App::welcome_send # Customise welcome email sub
welcome_text: My::App::welcome_text # Customise welcome email text
# 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 the Dancer2::Session manpage for information on how to configure session management within your application.
David Precious, <davidp at preshweb.co.uk>
Dancer2 port of Dancer::Plugin::Auth::Extensible by:
Stefan Hornburg (Racke), <racke at linuxia.de>
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/PerlDancer/Dancer2-Plugin-Auth-Extensible
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)
LDAP provider added by Mark Meyer (ofosos)
Config options for default login/logout handlers by Henk van Oers (hvoers)
Documentation fix by Vince Willems.
Support for DBIC provider and warning on missing realms by Andrew Beverley.
Copyright 2012-13 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.