#NAME

Yancy::Plugin::Auth::Token - A simple token-based auth

#VERSION

version 1.081

#SYNOPSIS

use Mojolicious::Lite;
plugin Yancy => {
    backend => 'sqlite://myapp.db',
    schema => {
        tokens => {
            properties => {
                id => { type => 'integer', readOnly => 1 },
                username => { type => 'string' },
                token => { type => 'string' },
            },
        },
    },
};
app->yancy->plugin( 'Auth::Token' => {
    schema => 'tokens',
    username_field => 'username',
    token_field => 'token',
    token_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 token-based authentication scheme for a site. Tokens are provided in the HTTP Authorization header:

Authorization: Token

#METHODS

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

#token_field

The name of the field to use for the token. Defaults to token. The token itself is meaningless except to authenticate a user. It must be unique, and it should be treated like a password.

#token_digest

This is the hashing mechanism that should be used for creating new tokens via the add_token helper. The default type is SHA-1.

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)

Additional fields are given as configuration to the Digest module. Not all Digest types require additional configuration.

#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 used to keep track of who owns the token.

This field is optional. If not specified, no user name will be stored.

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

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

$ perl myapp.pl eval 'app->yancy->auth->add_token( "username" )'

Generate a new token and add it to the database. "username" is the username for the token. The token will be generated as a base-64 encoded hash of the following input:

The username
The site's secret
The current time
A random number

#SEE ALSO

Yancy::Plugin::Auth

#AUTHOR

Doug Bell <preaction@cpan.org>

#COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.