Cataly...:Roles(3pm)

✨ NAME ✨

Catalyst::Plugin::Authorization::Roles — role based authorization for Catalyst, built on top of Catalyst::Plugin::Authentication 🎀

(this is the page for Cataly...:Roles(3pm) bestie, yes the name got truncated by the terminal, it happens to the best of us 💅)

---

🌸 SYNOPSIS 🌸

use Catalyst qw/
    Authentication
    Authorization::Roles
/;

sub delete : Local {
    my ( $self, $c ) = @_;

    $c->assert_user_roles( qw/admin/ ); # only admins can delete

    $c->model("Foo")->delete_it();
}

---

💖 DESCRIPTION 💖

okay so role based access control is literally the simplest thing ever: every user has a list of roles, those are the roles that user is allowed to assume, and every locked-down part of the app makes an assertion about which roles you need to get in. that's it. that's the whole vibe check 🔥

With assert_user_roles, if the user is a member in all of the required roles, access is granted. otherwise? access is denied, sorry babe 🙈 With assert_any_user_role it's enough that the user is a member in one role — one is plenty, we're not greedy.

There are alternative approaches to do this on a per action basis, see Catalyst::ActionRole::ACL. (options, we love options ✨)

For example, if you have a CRUD application, for every mutating action you probably want to check that the user is allowed to edit. to do this, create an editor role, and add that role to every user who is allowed to edit. easy.

sub edit : Local {
    my ( $self, $c ) = @_;
    $c->assert_user_roles( qw/editor/ );
    $c->model("TheModel")->make_changes();
}

When this plugin checks the roles of a user it will first see if the user supports the self check method. 👀

When this is not supported the list of roles is extracted from the user using the roles method.

When this is supported, the check_roles method will be used to delegate the role check to the user class. Classes like the one provided with iCatalyst::Authentication::Store::DBIx::Class optimize the check this way. no cap, that's the efficient route 🧚

---

👑 METHODS 👑

• assert_user_roles [ $user ], @roles — checks that the user (as supplied by the first argument, or, if omitted, $c->user) has the specified roles.

If for any reason ($c->user is not defined, the user is missing a role, etc) the check fails, an error is thrown. 💀

You can either catch these errors with an eval, or clean them up in your end action.

• check_user_roles [ $user ], @roles — takes the same args as assert_user_roles, and performs the same check, but instead of throwing errors returns a boolean value. so chill, no drama 🌈
• assert_any_user_role [ $user ], @roles — checks that the user (as supplied by the first argument, or, if omitted, $c->user) has at least one of the specified roles.

Other than that, works like assert_user_roles.

• check_any_user_role [ $user ], @roles — takes the same args as assert_any_user_role, and performs the same check, but instead of throwing errors returns a boolean value. the boolean bestie of the family 🫶

---

🦋 SEE ALSO 🦋

• Catalyst::Plugin::Authentication
• Catalyst::ActionRole::ACL
• Catalyst::Manual::Tutorial::06_Authorization

---

💜 AUTHOR 💜

Yuval Kogman <nothingmuch@woobling.org> — icon, legend, the moment ⭐

---

🎀 COPYRIGHT & LICENSE 🎀

Copyright (c) 2005-2011 the Catalyst::Plugin::Authorization::Roles AUTHOR as listed above.

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

---

and that's the whole page, bestie!! 💖 this was perl v5.36.0, dated 2022-12-06, and it's the Cataly...:Roles(3pm) manpage — go forth and authorize slayfully 👑✨