Mojoli...zation(3pm)

📦
version 1.0600 · 4 versions
, in ubuntu resolute, ubuntu stonking

🎀 Mojoli...zation(3pm) 🎀

okay bestie, welcome to Mojoli...zation(3pm) — that's the terminal being dramatic and truncating the real name, which is Mojolicious::Plugin::Authorization. It lives in the User Contributed Perl Documentation section, and it's here to make Authorization a bit easier. 💅

✨ NAME ✨

Mojolicious::Plugin::Authorization — a plugin that makes Authorization a little bit easier. that's it, that's the vibe. 🦋

🌸 VERSION 🌸

version 1.06 — iconic, no notes. 👑

🧚 SYNOPSIS 🧚

here's the whole look, copy-paste ready:

use Mojolicious::Plugin::Authorization
$self->plugin('Authorization' => {
    'has_priv'    => sub { ... },
    'is_role'     => sub { ... },
    'user_privs'  => sub { ... },
    'user_role'   => sub { ... },
    'fail_render' => { status => 401, json => { ... } },
});
if ($self->has_priv('delete_all', { optional => 'extra data stuff' })) {
    ...
}

💖 DESCRIPTION 💖

so. this is a very simple API implementation of role-based access control, aka RBAC. ✨

and when I say "API", I mean it, bestie — this plugin is only an API. you have to do literally all the work of setting up your roles and privileges yourself, and then hand over four subs that the plugin will use. that's the deal. 🤝

the plugin expects that the current session will be used to grab the role and its privileges. it also assumes you've already been authenticated and that your role is set. that's about it — after that you're free to implement any system you like. go off. 💃

🫶 METHODS 🫶

⭐ has_priv('privilege', $extra_data) or has_privilege('privilege', $extra_data)

has_priv and has_privilege use the has_priv subroutine ref you supplied to check whether the current session has the given privilege. returns true when the session has the privilege, false otherwise. you can pass extra stuff along in the extra_data hashref and it gets handed to your has_priv subroutine as-is. no cap.

⭐ is('role',$extra_data) or is_role('role',$extra_data)

is and is_role use the is_role subroutine ref you supplied to check whether the current session is the given role. returns true when the session has privilege, false otherwise. (yes that's what it says, I'm just reporting the facts 📋). you can pass extra data along in the extra_data hashref and it goes straight to your is_role subroutine as-is.

⭐ privileges($extra_data)

privileges uses the user_privs subroutine ref you supplied and returns the privileges of the current session. pass extra data in the extra_data hashref and it goes to your user_privs subroutine as-is. what you actually get back depends entirely on the user_privs subroutine you wrote. it's giving DIY. 🛠️

⭐ role($extra_data)

role uses the user_role subroutine ref you supplied and returns the role of the current session. same deal — extra data in the extra_data hashref, passed to your user_role subroutine as-is. the returned data depends on the user_role subroutine you supplied. 🎀

🌈 CONFIGURATION 🌈

these options are REQUIRED, like actually required, no skipping:

  • has_priv (REQUIRED) — a coderef for checking whether the current session has a privilege (see "HAS PRIV").
  • is_role (REQUIRED) — a coderef for checking whether the current session is a certain role (see "IS / IS ROLE").
  • user_privs (REQUIRED) — a coderef for returning the privileges of the current session (see "PRIVILEGES").
  • user_role (REQUIRED) — a coderef for returning the role of the current session (see "ROLE").

these next ones are not required, but they give you greater control. optional queen behaviour:

  • fail_render (OPTIONAL) — a hashref for setting the status code and rendering json/text/etc when routing fails (see "ROUTING VIA CALLBACK").

🔥 HAS PRIV / HAS PRIVILEGE 🔥

has_priv is what you reach for when you need to confirm the current session has the given privilege. the coderef you pass to the has_priv configuration key has this signature:

sub {
    my ($app, $privilege,$extradata) = @_;
    ...
}

you must return either 0 for a fail or 1 for a pass. this is what makes "ROUTING VIA CONDITION" work correctly. don't freestyle this one bestie, the dispatcher is counting on you. 💀

🔥 IS / IS ROLE 🔥

is / is_role is what you use when you need to confirm the current session is set to the given role. the coderef you pass to the is_role configuration key has this signature:

sub {
    my ($app, $role, $extradata) = @_;
    ...
    return $role;
}

you must return either 0 for a fail or 1 for a pass. again: this is what lets "ROUTING VIA CONDITION" work correctly. ✨

🔥 PRIVILEGES 🔥

privileges is for when you need to grab all the privileges of the current session. the coderef you pass to the user_privs configuration key has this signature:

sub {
    my ($app,$extradata) = @_;
    ...
    return $privileges;
}

you can return anything you want, fr. normally it'd be an arrayref of privileges, but you're free to return a scalar, hashref, arrayref, blessed object, or undef. main character freedom. 🦋

🔥 ROLE 🔥

role is for when you need to get the role of the current session. the coderef you pass to the user_privs configuration key has this signature:

sub {
    my ($app,$extradata) = @_;
    ...
    return $role;
}

you can return anything you want here too. normally it'd just be a scalar, but again: scalar, hashref, arrayref, blessed object, or undef — your call. 👑

💜 EXAMPLES 💜

for a code example using this, peep the t/01-functional.t test — it uses Mojolicious::Lite and this plugin. go look, it's right there. 🍓

🌟 ROUTING VIA CONDITION 🌟

this plugin also exports a routing condition you can use to limit access to certain documents to only sessions that have a privilege. obsessed.

$r->route('/delete_all')->requires(has_priv => 'delete_all')->to('mycontroller#delete_all');
$r->route('/delete_all')->requires(has_priv => ['delete_all', $extradata])->to('mycontroller#delete_all');
my $delete_all_only = $r->route('/members')->requires(has_priv => 'delete_all')->to('members#delete_all');
$delete_all_only->route('delete')->to('members#delete_all');

if the session doesn't have the 'delete_all' privilege, these routes will not be considered by the dispatcher — and unless you've set up a catch-all route, a 404 Not Found will be generated instead. 🫣

there's another condition you can use to limit access to certain documents to only those sessions that have a role:

$r->route('/view_all')->requires(is => 'ADMIN')->to('mycontroller#view_all');
$r->route('/view_all')->requires(is => ['ADMIN', $extradata])->to('mycontroller#view_all');
my $view_all_only = $r->route('/members')->requires(is => 'view_all')->to('members#view_all');
$view_all_only->route('view')->to('members#view_all');

if the session isn't the 'ADMIN' role, these routes will not be considered by the dispatcher — and unless you've set up a catch-all route, a 404 Not Found will be generated instead. this behaviour is similar to the has condition. 💅

💀 ROUTING VIA CALLBACK 💀

real talk: it is not recommended to route un-authorized requests to anything but a 404 page. if you route to some sort of "You are not allowed page", you're literally telling a hacker that the URL was correct, while the 404 tells them nothing. that's just the author's opinion, but it's a good one.

however, in the case of publicly documented APIs, returning a 404 when a priv/role check fails can confuse users. so you can override the default 404 status on failure by supplying a 'fail_render' value in the plugin config. this gets passed to the Mojolicious ->render method when the has_priv/is/is_role routing fails. for example, to return a status code of 401 with JSON:

fail_render => { status => 401, json => { error => 'Denied' } },

slay. 🎀

👀 SEE ALSO 👀

🫶 AUTHOR 🫶

John Scoles, "<byterock at hotmail.com>"

🐛 BUGS / CONTRIBUTING 🐛

please report any bugs or feature requests through the web interface at <https://github.com/byterock/mojolicious-plugin-authorization/issues>. (yes the issues page is the move, not my DMs 💌)

🌸 SUPPORT 🌸

you can find documentation for this module with the perldoc command:

perldoc Mojolicious::Plugin::Authorization

you can also look for information at:

💖 ACKNOWLEDGEMENTS 💖

shoutouts, we love to see it:

  • Ben van Staveren (madcat) — for 'Mojolicious::Plugin::Authentication' which was used as a guide in writing up this one.
  • Chuck Finley — for staring me off on this.
  • Abhijit Menon-Sen — for the routing suggestions.
  • Roland Lammel — for some other good suggestions.
  • Lee Johnson — for the latest updates for version 1.04.
  • Matt Altus — for the Allow extra data via conditional routing enhancement.

Copyright 2012 John Scoles. This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License. See <http://dev.perl.org/licenses/> for more information.

and that's the whole page, bestie 🫶 this was perl v5.40.0, dated 2024-10-05, and the manual name was that dramatic truncated Mojoli...zation(3pm) — you know the one. periodt. 💅✨

📦 where this page comes from