CONTENTS

• NAME
• VERSION
• SYNOPSIS
• DESCRIPTION
• METHODS
  • current_user
  • plugins
  • login_form
  • logout
• CONFIGURATION
  • schema
  • username_field
  • password_field
  • plugin_field
  • plugins
  • Single User / Multiple Auth
  • Sessions
• HELPERS
  • yancy.auth.current_user
  • yancy.auth.require_user
  • yancy.auth.login_form
  • yancy.auth.logout
• ROUTES
  • yancy.auth.login_form
  • yancy.auth.logout
• TEMPLATES
  • yancy/auth/login_form.html.ep
  • yancy/auth/login_page.html.ep
  • layouts/yancy/auth.html.ep
• SEE ALSO
  • Multiplex Plugins
• AUTHOR
• COPYRIGHT AND LICENSE

#NAME

Yancy::Plugin::Auth - Add one or more authentication plugins to your site

#VERSION

version 1.081

#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_form

Return 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).

• Yancy::Plugin::Auth::Password

• Yancy::Plugin::Auth::Token

• Yancy::Plugin::Auth::OAuth2

• Yancy::Plugin::Auth::Github

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