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/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".

/login/facebook

Facebook consent screen redirects to this action. This action is handled by "login_facebook".

/login/google

Google 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 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.

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.

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.

AUTHOR

Красимир Беров (Krasimir Berov)

COPYRIGHT AND LICENSE

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)