NAME

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

VERSION

version 1.027

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.

METHODS

Returns the currently logged-in user, if any.

Returns the list of configured auth plugins.

login_form

Render the login form template for inclusion in Yancy::Plugin::Auth.

require_user

    my $subref = $c->yancy->auth->require_user( \%match );

Build a callback to validate there is a logged-in user, and optionally that the current user has certain fields set. \%match is optional and is a SQL::Abstract where clause matched with "match" in Yancy::Util.

    # Ensure the user is logged-in
    my $user_cb = $app->yancy->auth->require_user;
    my $user_only = $app->routes->under( $user_cb );

    # Ensure the user's "is_admin" field is set to 1
    my $admin_cb = $app->yancy->auth->require_user( { is_admin => 1 } );
    my $admin_only = $app->routes->under( $admin_cb );

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 );

TEMPLATES

yancy/auth/login.html.ep

This displays all of the login forms for all of the configured plugins (if the plugin has a login form).

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

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