CONTENTS
- NAME
- VERSION
- SYNOPSIS
- DESCRIPTION
- CONFIGURATION
- TEMPLATES
- FILTERS
- HELPERS
- SEE ALSO
- AUTHOR
- COPYRIGHT AND LICENSE
#NAME
Yancy::Plugin::Auth::Basic - (DEPRECATED) A simple auth module for a site
#VERSION
version 1.081
#SYNOPSIS
use Mojolicious::Lite;
plugin Yancy => {
backend => 'pg://localhost/mysite',
schema => {
users => {
required => [ 'username', 'password' ],
properties => {
id => { type => 'integer', readOnly => 1 },
username => { type => 'string' },
password => { type => 'string', format => 'password' },
},
},
},
};
app->yancy->plugin( 'Auth::Basic' => {
schema => 'users',
username_field => 'username',
password_field => 'password',
password_digest => {
type => 'SHA-1',
},
} );
#DESCRIPTION
NOTE: This plugin is deprecated and will be removed in Yancy v2.000. Please switch to the new pluggable auth Yancy::Plugin::Auth or the new password auth Yancy::Plugin::Auth::Password.
This plugin provides a basic authentication and authorization scheme for a Mojolicious site using Yancy. If a user is authenticated, they are then authorized to use the administration application and API.
#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.
This field is optional. If not specified, the schema's ID field will be used. For example, if the schema uses the
username
field as a unique identifier, we don't need to provide ausername_field
.plugin Yancy => { schema => { users => { 'x-id-field' => 'username', properties => { username => { type => 'string' }, password => { type => 'string' }, }, }, }, }; app->yancy->plugin( 'Auth::Basic' => { schema => 'users', password_digest => { type => 'SHA-1' }, } );
- password_field
-
The name of the field to use for the user's password. Defaults to
password
.This field will automatically be set up to use the "auth.digest" filter to properly hash the password when updating it.
- password_digest
-
This is the hashing mechanism that should be used for passwords. There is no default, so you must configure one.
This value should be a hash of digest configuration. The one required field is
type
, and should be a type supported by the Digest module:MD5 (part of core Perl)
SHA-1 (part of core Perl)
SHA-256 (part of core Perl)
SHA-512 (part of core Perl)
Bcrypt (recommended)
Additional fields are given as configuration to the Digest module. Not all Digest types require additional configuration.
# Use Bcrypt for passwords # Install the Digest::Bcrypt module first! app->yancy->plugin( 'Auth::Basic' => { password_digest => { type => 'Bcrypt', cost => 12, salt => 'abcdefgh♥stuff', }, } );
- route
-
The root route that this auth module should protect. Defaults to protecting only the Yancy editor application.
#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 );
#TEMPLATES
To override these templates in your application, provide your own template with the same name.
- yancy/auth/login.html.ep
-
This template displays the login form. The form should have two fields,
username
andpassword
, and perform aPOST
request tourl_for 'yancy.check_login'
- yancy/auth/unauthorized.html.ep
-
This template displays an error message that the user is not authorized to view this page. This most-often appears when the user is not logged in.
- layouts/yancy/auth.html.ep
-
The layout that Yancy uses when displaying the login form, the unauthorized error message, and other auth-related pages.
#FILTERS
This module provides the following filters. See "Extended Field Configuration" in Yancy for how to use filters.
#auth.digest
Run the field value through the configured password Digest object and store the Base64-encoded result instead.
#HELPERS
This plugin adds the following Mojolicious helpers:
#yancy.auth.route
The route object that requires authentication. Add your own routes as children of this route to require authentication for your own routes.
my $auth_route = $app->yancy->auth->route;
$auth_route->get( '/', sub {
my ( $c ) = @_;
return $c->render(
data => 'You are authorized to view this page',
);
} );
#yancy.auth.current_user
Get/set the currently logged-in user. Returns undef
if no user is logged-in.
my $user = $c->yancy->auth->current_user
|| return $c->render( status => 401, text => 'Unauthorized' );
To set the current user, pass in the username.
$c->yancy->auth->current_user( $username );
#yancy.auth.get_user
my $user = $c->yancy->auth->get_user( $username );
Get a user item by its username
.
#yancy.auth.check
Check a username and password to authenticate a user. Returns true if the user is authenticated, or returns false.
NOTE: Does not change the currently logged-in user.
if ( $c->yancy->auth->check( $username, $password ) ) {
# Authentication succeeded
$c->yancy->auth->current_user( $username );
}
#yancy.auth.clear
Clear the currently logged-in user (logout).
$c->yancy->auth->clear;
#SEE ALSO
#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.