NAME

Yancy::Plugin::Auth::Basic - A simple auth module for a site

VERSION

version 0.018

DESCRIPTION

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.

    # myapp.pl
    use Mojolicious::Lite;
    plugin Yancy => {
        backend => 'pg://localhost/mysite',
        collections => {
            users => {
                required => [ 'username', 'password' ],
                properties => {
                    id => { type => 'integer', readOnly => 1 },
                    username => { type => 'string' },
                    password => { type => 'string', format => 'password' },
                },
            },
        },
    };
    plugin 'Auth::Basic' => {
        collection => 'users',
        username_field => 'username',
        password_field => 'password', # default
        password_digest => {
            type => 'SHA-1',
        },
    };

    # yancy.conf
    {
        backend => 'pg://localhost/mysite',
        collections => {
            users => {
                required => [ 'username', 'password' ],
                properties => {
                    id => { type => 'integer', readOnly => 1 },
                    username => { type => 'string' },
                    password => { type => 'string', format => 'password' },
                },
            },
        },
        plugins => [
            [
                'Auth::Basic', {
                    collection => 'users',
                    username_field => 'username',
                    password_field => 'password', # default
                    password_digest => {
                        type => 'SHA-1',
                    },
                },
            ],
        ],
    }

CONFIGURATION

This plugin has the following configuration options.

collection

The name of the Yancy collection that holds users. Required.

username_field

The name of the field in the collection 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 collection's ID field will be used. For example, if the collection uses the username field for its primary key, we don't need to provide a username_field.

    plugin Yancy => {
        collections => {
            users => {
                'x-id-field' => 'username',
                properties => {
                    username => { type => 'string' },
                    password => { type => 'string' },
                },
            },
        },
    };
    plugin 'Auth::Basic' => {
        collection => '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!
    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.

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 and password, and perform a POST request to url_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.

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;

SUBCLASSING AND CUSTOM AUTH

This class is intended to be extended for custom authentication modules. You can replace any of the templates or helpers (above) that you need after calling this class's register method.

If this API is not enough to implement your authentication module, please let me know and we can add a solution. If all authentication modules have the same API, it will be better for users.

SEE ALSO

Digest

AUTHOR

Doug Bell <preaction@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 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.

cpanm Yancy

perl -MCPAN -e shell
install Yancy