NAME

WWW::Suffit::Plugin::BasicAuth - The Mojolicious Plugin for HTTP basic authentication and authorization

SYNOPSIS

# in your startup
$self->plugin('WWW::Suffit::Plugin::BasicAuth', {
        realm => "Strict Zone",
        authn_fail_render => {
            status => 401,
            json => {
                status => 0,
                message => "Basic authentication required!",
            },
        },
        authz_fail_render => {
            status => 403,
            json => {
                status => 0,
                message => "Forbidden!",
            },
        },
    });

# in your routes
sub index {
    my $self = shift;

    # Basic authentication
    return unless $self->is_basic_authenticated({ render_by_fail => 1 });

    # Basic Authorization
    return unless $self->is_basic_authorized({ render_by_fail => 1 });

    $self->render(...);
}

# or as condition in your startup
$self->routes->get('/info')->requires(basic_authenticated => 1, basic_authorized => 1)
    ->to('alpha#info');

# or bridged in your startup
my $auth = $self->routes->under(sub {
    my $self = shift;

    # Basic authentication
    return unless $self->is_basic_authenticated({ render_by_fail => 1 });

    # Basic Authorization
    return unless $self->is_basic_authorized({ render_by_fail => 1 });

    return 1;
});
$auth->get('/info')->to('alpha#info');

DESCRIPTION

The Mojolicious Plugin for HTTP basic authentication and authorization

This plugin based on NoRFC::Server::Auth

OPTIONS

This plugin supports the following options

authn

Authentication checker callback

$self->plugin('WWW::Suffit::Plugin::BasicAuth', {authn => sub {
    my ($controller, $realm, $username, $password, $params) = @_;

    # ...

    return 1; # or 0 on fail
}});

The $params holds options from "is_basic_authenticated" call directly

authz

Authorization checker callback

$self->plugin('WWW::Suffit::Plugin::BasicAuth', {authz => sub {
    my ($controller, $params) = @_;

    # ...

    return 1; # or 0 on fail
}});

The $params holds options from "is_basic_authorized" call directly

authn_fail_render

Defines what is to be rendered when the authenticated condition is not met

Set to a coderef which will be called with the following signature:

sub {
    my $controller = shift;
    my $realm = shift;
    my $resp = shift; # See authn_fail_render
    ...
    return $hashref;
}

The return value of the subroutine will be ignored if it evaluates to false. If it returns a hash reference, it will be dereferenced and passed as-is to the controller's render function

If set directly to a hash reference, that will be passed to render instead

authz_fail_render

Defines what is to be rendered when the authorized condition is not met

Set to a coderef which will be called with the following signature:

sub {
    my $controller = shift;
    my $resp = shift; # See authz_fail_render
    ...
    return $hashref;
}

See also "authn_fail_render"

realm

$self->plugin('WWW::Suffit::Plugin::BasicAuth', {realm => 'My Castle!'});

HTTP Realm, defaults to 'Strict Zone'

HELPERS

is_basic_authenticated

This helper performs credential validation and checks the authentication status

my $authenticated = $self->is_basic_authenticated;
my $authenticated = $self->is_basic_authenticated({
        render_by_fail => 1,
        authn => sub {
            my ($c, $in_realm, $in_user, $in_pass, $params) = @_;
            return 0 unless $in_user;
            return secure_compare($in_pass, "mypass") ? 1 : 0;
        },
        fail_render => {
            json => {
                message => "Basic authentication required!",
            },
            status => 401,
        },
    });

render_by_fail

It enables rendering the fail response. See "authn_fail_render"

authn

It defines code of authentication

fail_render

It is render parameters as "authn_fail_render"

is_basic_authorized

This helper checks the authorization status

my $authorized = $self->is_basic_authorized;
my $authorized = $self->is_basic_authorized({
        render_by_fail => 1,
        authz => sub {
            my ($c, $params) = @_;
            return 1; # Basic authorization tsatus
        },
        fail_render => {
            json => {
                message => "Forbidden!",
            },
            status => 403,
        },

    });

render_by_fail

It enables rendering the fail response. See "authz_fail_render"

authz

It defines code of authorization

fail_render

It is render parameters as "authz_fail_render"

METHODS

Internal methods

register

This method register the plugin and helpers in Mojolicious application.

EXAMPLES

Examples of using

ROUTING VIA CONDITION

This plugin exports a routing condition you can use in order to limit access to certain documents to only authenticated users.

$self->routes->get('/info')->requires(basic_authenticated => 1, basic_authorized => 1)
    ->to('alpha#info');

Prior to Mojolicious 9, use "over" instead of "requires."

ROUTING VIA CALLBACK

If you want to be able to send people to a login page, you will have to use the following:

sub index {
    my $self = shift;

    $self->redirect_to('/login') and return 0
        unless($self->is_basic_authenticated && $self->is_basic_authorized);

    $self->render(...);
}

ROUTING VIA BRIDGE

my $auth = $self->routes->under(sub {
    my $self = shift;

    # Authentication
    return unless $self->is_basic_authenticated({
        render_by_fail => 1
    });

    # Authorization
    return unless $self->is_basic_authorized({
        render_by_fail => 1
    });

    return 1;
});
$auth->get('/info')->to('alpha#info');

SEE ALSO

Mojolicious, NoRFC::Server::Auth, Mojolicious::Plugin::Authentication, Mojolicious::Plugin::Authorization, Mojolicious::Plugin::BasicAuth, Mojolicious::Plugin::HttpBasicAuth

AUTHOR

Serż Minus (Sergey Lepenkov) https://www.serzik.com <abalama@cpan.org>

COPYRIGHT

Copyright (C) 1998-2023 D&D Corporation. All Rights Reserved

LICENSE

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

See LICENSE file and https://dev.perl.org/licenses/

cpanm WWW::Suffit::Plugin::BasicAuth

perl -MCPAN -e shell
install WWW::Suffit::Plugin::BasicAuth