Yancy::Plugin::Auth - Add one or more authentication plugins to your site
version 1.065
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', ], } );
Note: This module is EXPERIMENTAL and its API may change before Yancy v2.000 is released.
EXPERIMENTAL
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.
Returns the currently logged-in user, if any.
Returns the list of configured auth plugins.
%= $c->yancy->auth->login_form
Return the rendered login form template.
Log out the current user. Will call the logout method on all configured auth plugins.
logout
This plugin has the following configuration options.
The name of the Yancy schema that holds users. Required.
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.
The name of the field to use for the password or secret.
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.
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.
Yancy::Plugin::Auth::
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', }, ], ], } );
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.
plugin_field
username_field
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 );
This plugin has the following helpers.
Get the current user from one of the configured plugins, if any. Returns undef if no user was found in the session.
undef
my $user = $c->yancy->auth->current_user || return $c->render( status => 401, text => 'Unauthorized' );
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' );
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 % }
Log out any current account from any auth plugin. Use this in your own route handlers to perform a logout.
This plugin creates the following named routes. Use named routes with helpers like url_for, link_to, and form_for.
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.
GET
%= 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>
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>
To override these templates, add your own at the designated path inside your app's templates/ directory.
templates/
This displays all of the login forms for all of the configured plugins (if the plugin has a login form).
This displays the login form on a page directing the user to log in.
The layout that Yancy uses when displaying the login page, the unauthorized error message, and other auth-related pages.
These are possible Auth plugins that can be used with this plugin (or as standalone, if desired).
Yancy::Plugin::Auth::Password
Yancy::Plugin::Auth::Token
Yancy::Plugin::Auth::OAuth2
Yancy::Plugin::Auth::Github
Doug Bell <preaction@cpan.org>
This software is copyright (c) 2020 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.
To install Yancy, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Yancy
CPAN shell
perl -MCPAN -e shell install Yancy
For more information on module installation, please visit the detailed CPAN module installation guide.