NAME
Ado::Plugin::Auth - Passwordless user authentication for Ado
SYNOPSIS
#in etc/ado.$mode.conf
plugins =>[
#...
'auth',
#...
],
#in etc/plugins/auth.$mode.conf
{
#methods which will be displayed in the "Sign in" menu
auth_methods => ['ado', 'facebook', 'google'],
providers => {
google => {
key =>'123456789....apps.googleusercontent.com',
secret =>'YourSECR3T',
scope=>'profile email',
info_url => 'https://www.googleapis.com/userinfo/v2/me',
},
facebook => {
key =>'123456789',
secret =>'123456789abcdef',
scope =>'public_profile,email',
info_url => 'https://graph.facebook.com/v2.2/me',
},
}
}DESCRIPTION
Ado::Plugin::Auth is a plugin that authenticates users to an Ado system. Users can be authenticated via Google, Facebook, locally and in the future other authentication service-providers.
Note that the user's pasword is never sent over the network. When using the local authentication method (ado) a digest is prepared in the browser using JavaScript. The digest is sent and compared on the server side. The digest is different in every POST request. The other authentication methods use the services provided by well known service providers like Google, Facebook etc. To use external authentication providers the module Mojolicious::Plugin::OAuth2 needs to be installed.
CONFIGURATION
The following options can be set in etc/plugins/auth.$mode.conf. You can find default options in etc/plugins/auth.conf.
auth_methods
This option will enable the listed methods (services) which will be used to authenticate a user. The services will be listed in the specified order in the partial template authbar.html.ep that can be included in any other template on your site.
#in etc/plugins/auth.$mode.conf
{
#methods which will be displayed in the "Sign in" menu
auth_methods => ['ado', 'google'],
}providers
A Hash reference with keys representing names of providers (same as auth_methods) and values, containing the configurations for the specific providers. This option will be merged with already defined providers by Mojolicious::Plugin::OAuth2. Add the rest of the needed configuration options to auth.development.conf or auth.production.conf only because this is highly sensitive and application specific information.
#Example for google:
google =>{
#client_id
key =>'123456654321abcd.apps.googleusercontent.com',
secret =>'Y0uRS3cretHEre',
scope=>'profile email',
info_url => 'https://www.googleapis.com/userinfo/v2/me',
},routes
Currently defined routes are described in "ROUTES".
CONDITIONS
Ado::Plugin::Auth provides the following conditions to be used by routes. To find more about conditions read "Conditions" in Mojolicious::Guides::Routing.
authenticated
Condition for routes used to check if a user is authenticated.
# add the condition programatically
$app->routes->route('/ado-users/:action', over => {authenticated=>1});
$app->routes->route('/ado-users/:action',
over => [authenticated => 1, ingroup => 'admin']
);
#in etc/ado.$mode.conf or etc/plugins/foo.$mode.conf
routes => [
#...
{
route => '/ado-users/:action:id',
via => [qw(PUT DELETE)],
# only authenticated users can edit and delete users,
# and only if they are authorized to do so
over => [authenticated => 1, ingroup => 'admin'],
to =>'ado-users#edit'
}
],ingroup
Checks if a user is in the given group. Returns true or false
# in etc/plugins/routes.conf or etc/plugins/foo.conf
{
route => '/vest',
via => ['GET'],
to => 'vest#screen',
over => [authenticated => 1, ingroup => 'foo'],
}
# programatically
$app->routes->route('/ado-users/:action', over => {ingroup => 'foo'});HELPERS
Ado::Plugin::Auth provides the following helpers for use in Ado::Control methods and templates.
login_ado
Finds and logs in a user locally. Returns true on success, false otherwise.
login_google
Called via /login/google. Finds an existing user and logs it in via Google. Creates a new user if it does not exist and logs it in via Google. The new user can login via any supported Oauth2 provider as long as it has the same email. The user can not login using Ado local authentication because he does not know his password, which is randomly generated. Returns true on success, false otherwise.
login_facebook
Called via /login/facebook. Finds an existing user and logs it in via Facebook. Creates a new user if it does not exist and logs it in via Facebook. The new user can login via any supported Oauth2 provider as long as it has the same email. The user can not login using Ado local authentication because he does not know his password, which is randomly generated. Returns true on success, false otherwise.
HOOKS
Ado::Plugin::Auth emits the following hooks.
after_login
In your plugin you can define some functionality to be executed right after a user has logged in. For example add some links to the adobar template, available only to logged-in users. Only the controller $c is passed to this hook.
#example from Ado::Plugin::Admin
$app->hook(
after_login => sub {
push @{shift->session->{adobar_links} //= []},
{icon => 'dashboard', href => '/ado', text => 'Dashboard'};
}
);after_user_add
$app->hook(after_user_add => sub {
my ($c, $user, $raw_data) = @_;
my $group = $user->add_to_group(ingroup=>'vest');
...
});In your plugin you can define some functionality to be executed right after a user is added. For example add a user to a group after registration. Passed the controller, the newly created $user and the $raw_data used to create the user.
ROUTES
Ado::Plugin::Auth provides the following routes (actions):
/authorize/:auth_method
Redirects to an OAuth2 provider consent screen where the user can authorize Ado to use his information or not. Currently Ado supports Facebook and Google.
/login
/login/adoIf accessed using a GET request displays a login form. If accessed via POST performs authentication using ado system database, and emits the hook "after_login" .
/login/facebookFacebook consent screen redirects to this action. This action is handled by "login_facebook".
/login/googleGoogle consent screen redirects to this action. This action is handled by "login_google".
/logout
Expires the session and redirects to the base URL.
$c->logout();TEMPLATES
Ado::Plugin::Auth embeds the following templates. You can run ado inflate and modify the inflated files. Usage examples can be found at http://localhost:3000 after starting ado.
partials/authbar.html.ep
Renders a menu dropdown for choosing methods for signing in.
partials/login_form.html.ep
Renders a Login form to authenticate locally.
login.html.ep
Renders a page containing the login form above.
METHODS
Ado::Plugin::Auth inherits all methods from Ado::Plugin and implements the following new ones.
register
This method is called by $app->plugin. Registers the plugin in Ado application and merges authentication configuration from $MOJO_HOME/etc/ado.conf with settings defined in $MOJO_HOME/etc/plugins/auth.conf. Authentication settings defined in plugins/auth.$mode.conf will override those defined in plugins/auth.conf. Authentication settings defined in ado.conf will override both.
TODO
The following authentication methods are in the TODO list: linkedin, github. Others may be added later. Please help by implementing authentication via more providers.
SEE ALSO
Mojolicious::Plugin::OAuth2, Ado::Plugin, Ado::Manual::Plugins, Mojolicious::Plugins, Mojolicious::Plugin, "Conditions" in Mojolicious::Guides::Routing
AUTHOR
Красимир Беров (Krasimir Berov)
COPYRIGHT AND LICENSE
Copyright 2014 Красимир Беров (Krasimir Berov).
This program is free software, you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License v3 (LGPL-3.0). You may copy, distribute and modify the software provided that modifications are open source. However, software that includes the license may release under a different license.
See http://opensource.org/licenses/lgpl-3.0.html for more information.