NAME
Yancy::Plugin::Auth - Add one or more authentication plugins to your site
VERSION
version 1.088
SYNOPSIS
use Mojolicious::Lite;
plugin Yancy => {
backend => 'sqlite://myapp.db',
schema => {
users => {
properties => {
id => { type => 'integer', readOnly => 1 },
plugin => {
type => 'string',
enum => [qw( password token )],
},
username => { type => 'string' },
# Optional password for Password auth
password => { type => 'string' },
},
},
},
};
app->yancy->plugin( 'Auth' => {
schema => 'users',
username_field => 'username',
password_field => 'password',
plugin_field => 'plugin',
plugins => [
[
Password => {
password_digest => {
type => 'SHA-1',
},
},
],
'Token',
],
} );DESCRIPTION
Note: This module is EXPERIMENTAL and its API may change before Yancy v2.000 is released.
This plugin adds authentication to your site.
Multiple authentication plugins can be added with this plugin. If you only ever want to have one type of auth, you can use that auth plugin directly if you want.
This module composes the Yancy::Auth::Plugin::Role::RequireUser role to provide the require_user authorization method.
METHODS
current_user
Returns the currently logged-in user, if any.
plugins
Returns the list of configured auth plugins.
login_form
%= $c->yancy->auth->login_formReturn the rendered login form template.
logout
Log out the current user. Will call the logout method on all configured auth plugins.
CONFIGURATION
This plugin has the following configuration options.
schema
The name of the Yancy schema that holds users. Required.
username_field
The name of the field in the schema which is the user's identifier. This can be a user name, ID, or e-mail address, and is provided by the user during login.
password_field
The name of the field to use for the password or secret.
plugin_field
The field to store which plugin the user is using to authenticate. This field is only used if two auth plugins have the same username field.
plugins
An array of auth plugins to configure. Each plugin can be either a name (in the Yancy::Plugin::Auth:: namespace) or an array reference with two elements: The name (in the Yancy::Plugin::Auth:: namespace) and a hash reference of configuration.
Each of this module's configuration keys will be used as the default for all the other auth plugins. Other plugins can override this configuration individually. For example, users and tokens can be stored in different schemas:
app->yancy->plugin( 'Auth' => {
plugins => [
[
'Password',
{
schema => 'users',
username_field => 'username',
password_field => 'password',
password_digest => { type => 'SHA-1' },
},
],
[
'Token',
{
schema => 'tokens',
token_field => 'token',
},
],
],
} );Single User / Multiple Auth
To allow a single user to configure multiple authentication mechanisms, do not configure a plugin_field. Instead, give every authentication plugin its own username_field. Then, once a user has registered with one auth method, they can log in and register with another auth method to link to the same account.
Sessions
This module uses Mojolicious sessions to store the login information in a secure, signed cookie.
To configure the default expiration of a session, use Mojolicious::Sessions default_expiration.
use Mojolicious::Lite;
# Expire a session after 1 day of inactivity
app->sessions->default_expiration( 24 * 60 * 60 );HELPERS
This plugin has the following helpers.
yancy.auth.current_user
Get the current user from one of the configured plugins, if any. Returns undef if no user was found in the session.
my $user = $c->yancy->auth->current_user
|| return $c->render( status => 401, text => 'Unauthorized' );yancy.auth.require_user
Validate there is a logged-in user and optionally that the user data has certain values. See "require_user" in Yancy::Plugin::Auth::Role::RequireUser.
# Display the user dashboard, but only to logged-in users
my $auth_route = $app->routes->under( '/user', $app->yancy->auth->require_user );
$auth_route->get( '' )->to( 'user#dashboard' );yancy.auth.login_form
Return an HTML string containing the rendered login forms for all configured auth plugins, in order.
%# Display a login form to an unauthenticated visitor
% if ( !$c->yancy->auth->current_user ) {
%= $c->yancy->auth->login_form
% }yancy.auth.logout
Log out any current account from any auth plugin. Use this in your own route handlers to perform a logout.
ROUTES
This plugin creates the following named routes. Use named routes with helpers like url_for, link_to, and form_for.
yancy.auth.login_form
Display all of the login forms for the configured auth plugins. This route handles GET requests and can be used with the redirect_to, url_for, and link_to helpers.
%= link_to Login => 'yancy.auth.login_form'
<%= link_to 'yancy.auth.login_form', begin %>Login<% end %>
<p>Login here: <%= url_for 'yancy.auth.login_form' %></p>yancy.auth.logout
Log out of all configured auth plugins. This route handles GET requests and can be used with the redirect_to, url_for, and link_to helpers.
%= link_to Logout => 'yancy.auth.logout'
<%= link_to 'yancy.auth.logout', begin %>Logout<% end %>
<p>Logout here: <%= url_for 'yancy.auth.logout' %></p>TEMPLATES
To override these templates, add your own at the designated path inside your app's templates/ directory.
yancy/auth/login_form.html.ep
This displays all of the login forms for all of the configured plugins (if the plugin has a login form).
yancy/auth/login_page.html.ep
This displays the login form on a page directing the user to log in.
layouts/yancy/auth.html.ep
The layout that Yancy uses when displaying the login page, the unauthorized error message, and other auth-related pages.
SEE ALSO
Multiplex Plugins
These are possible Auth plugins that can be used with this plugin (or as standalone, if desired).
AUTHOR
Doug Bell <preaction@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2021 by Doug Bell.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.