NAME
Yancy::Plugin::Auth::Password - A simple password-based auth
VERSION
version 1.037
SYNOPSIS
use Mojolicious::Lite;
plugin Yancy => {
backend => 'sqlite://myapp.db',
schema => {
users => {
properties => {
id => { type => 'integer', readOnly => 1 },
username => { type => 'string' },
password => { type => 'string', format => 'password' },
},
},
},
};
app->yancy->plugin( 'Auth::Password' => {
schema => 'users',
username_field => 'username',
password_field => 'password',
password_digest => {
type => 'SHA-1',
},
} );
DESCRIPTION
Note: This module is EXPERIMENTAL
and its API may change before Yancy v2.000 is released.
This plugin provides a basic password-based authentication scheme for a site.
Migrate from Auth::Basic
To migrate from the deprecated Yancy::Plugin::Auth::Basic module, you should set the migrate_digest
config setting to the password_digest
settings from your Auth::Basic configuration. If they are the same as your current password digest settings, you don't need to do anything at all.
# Migrate from Auth::Basic, which had SHA-1 passwords, to
# Auth::Password using SHA-256 passwords
app->yancy->plugin( 'Auth::Password' => {
schema => 'users',
username_field => 'username',
password_field => 'password',
migrate_digest => {
type => 'SHA-1',
},
password_digest => {
type => 'SHA-256',
},
} );
# Migrate from Auth::Basic, which had SHA-1 passwords, to
# Auth::Password using SHA-1 passwords
app->yancy->plugin( 'Auth::Password' => {
schema => 'users',
username_field => 'username',
password_field => 'password',
password_digest => {
type => 'SHA-1',
},
} );
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 a username_field
.
plugin Yancy => {
schema => {
users => {
'x-id-field' => 'username',
properties => {
username => { type => 'string' },
password => { type => 'string' },
},
},
},
};
app->yancy->plugin( 'Auth::Password' => {
schema => 'users',
password_digest => { type => 'SHA-1' },
} );
password_field
The name of the field to use for the 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 hashing passwords. 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.
There is no default: Perl core provides SHA-1 hashes, but those aren't good enough. We recommend installing Digest::Bcrypt for password hashing.
# Use Bcrypt for passwords
# Install the Digest::Bcrypt module first!
app->yancy->plugin( 'Auth::Basic' => {
password_digest => {
type => 'Bcrypt',
cost => 12,
salt => 'abcdefgh♥stuff',
},
} );
Digest information is stored with the password so that password digests can be updated transparently when necessary. Changing the digest configuration will result in a user's password being upgraded the next time they log in.
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 );
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 has the following helpers.
yancy.auth.current_user
Get the current user from the session, 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' );
ROUTES
This plugin creates the following named routes. Use named routes with helpers like url_for, link_to, and form_for.
yancy.auth.password.login_form
Display the login form. See "TEMPLATES" below.
yancy.auth.password.login
Handle login by checking the user's username and password.
TEMPLATES
To override these templates in your application, provide your own template with the same name.
yancy/auth/password/login_form.html.ep
The form to log in.
yancy/auth/password/login.html.ep
The page containing the form to log in. Uses the login_form.html.ep
template for the form itself.
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.
yancy/auth/unauthorized.json.ep
This template renders a JSON object with an "errors" array explaining the error.
layouts/yancy/auth.html.ep
The layout that Yancy uses when displaying the login form, the unauthorized error message, and other auth-related pages.
SEE ALSO
AUTHOR
Doug Bell <preaction@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2019 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.