Ado::Plugin::Auth - Passwordless user authentication for Ado
#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', }, } }
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.
The following options can be set in etc/plugins/auth.$mode.conf. You can find default options in etc/plugins/auth.conf.
etc/plugins/auth.$mode.conf
etc/plugins/auth.conf
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.
authbar.html.ep
#in etc/plugins/auth.$mode.conf { #methods which will be displayed in the "Sign in" menu auth_methods => ['ado', 'google'], }
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', },
Currently defined routes are described in "ROUTES".
Ado::Plugin::Auth provides the following conditions to be used by routes. To find more about conditions read "Conditions" in Mojolicious::Guides::Routing.
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' } ],
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'});
Ado::Plugin::Auth provides the following helpers for use in Ado::Control methods and templates.
Finds and logs in a user locally. Returns true on success, false otherwise.
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/google
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.
/login/facebook
Ado::Plugin::Auth emits the following hooks.
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.
$c
#example from Ado::Plugin::Admin $app->hook( after_login => sub { push @{shift->session->{adobar_links} //= []}, {icon => 'dashboard', href => '/ado', text => 'Dashboard'}; } );
$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.
$user
Ado::Plugin::Auth provides the following routes (actions):
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/ado
If 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".
GET
POST
ado
Facebook consent screen redirects to this action. This action is handled by "login_facebook".
Google consent screen redirects to this action. This action is handled by "login_google".
Expires the session and redirects to the base URL.
$c->logout();
Ado::Plugin::Auth uses the following templates. The paths are in the /templates folder. Feel free to move them to the site_templates folder and modify them for your needs.
/templates
Renders a menu dropdown for choosing methods for signing in.
Renders a Login form to authenticate locally.
Renders a page containing the login form above.
Ado::Plugin::Auth inherits all methods from Ado::Plugin and implements the following new ones.
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.
$app->plugin
$MOJO_HOME/etc/ado.conf
$MOJO_HOME/etc/plugins/auth.conf
plugins/auth.$mode.conf
plugins/auth.conf
ado.conf
The following authentication methods are in the TODO list: linkedin, github. Others may be added later. Please help by implementing authentication via more providers.
Mojolicious::Plugin::OAuth2, Ado::Plugin, Ado::Manual::Plugins, Mojolicious::Plugins, Mojolicious::Plugin, "Conditions" in Mojolicious::Guides::Routing
Красимир Беров (Krasimir Berov)
Copyright 2014-2016 Красимир Беров (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.
To install Ado, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Ado
CPAN shell
perl -MCPAN -e shell install Ado
For more information on module installation, please visit the detailed CPAN module installation guide.