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/