NAME

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

VERSION

version 1.038

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 

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 token, if any. Returns undef if no token was passed or the token was not found in the database.

    my $user = $c->yancy->auth->current_user
        || return $c->render( status => 401, text => 'Unauthorized' );

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

cpanm Yancy

perl -MCPAN -e shell
install Yancy