Sawyer X > Authorize-Rule-0.002 > Authorize::Rule

Download:
Authorize-Rule-0.002.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.002   Source   Latest Release: Authorize-Rule-0.005

NAME ^

Authorize::Rule - Rule-based authorization mechanism

VERSION ^

version 0.002

SYNOPSIS ^

A simple example:

    my $auth = Authorize::Rule->new(
        rules => {
            # Marge can do everything
            Marge => [ allow => '*' ],

            # Homer can do everything except use the oven
            Homer => [
                deny  => ['oven'],
                allow => '*',
            ],

            # kids can clean and eat at the kitchen
            # but nothing else
            # and they can do whatever they want in their bedroom
            kids => [
                allow => {
                    kitchen => {
                        action => ['eat', 'clean'],
                    },

                    bedroom => '*',
                },

                deny => ['kitchen'],
            ],
        },
    );

    $auth->check( Marge => 'kitchen' ); # 1
    $auth->check( Marge => 'garage'  ); # 1
    $auth->check( Marge => 'bedroom' ); # 1
    $auth->check( Homer => 'oven'    ); # 0
    $auth->check( Homer => 'kitchen' ); # 1

    $auth->check( kids => 'kitchen', { action => 'eat'     } ); # 1
    $auth->check( kids => 'kitchen', { action => 'destroy' } ); # 0

DESCRIPTION ^

Authorize::Rule allows you to provide a set of rules for authorizing access of entities to resources. This does not cover authentication. While authentication asks "who are you?", authorization asks "what are you allowed to do?"

The system is based on decisions per resources and their parameters.

The following two authorization decisions are available:

The following levels of authorization are available:

More complicated structures (other than hashref of keys to string values) are currently not supported, though there are plans to add callbacks in order to allow the user to specify their own checks of conditions.

ATTRIBUTES ^

default

In case there is no matching rule for the entity/resource/conditions, what would you like to do. The default is to deny (0), but you can change it to allow by default if there is no match.

    Authorize::Rule->new(
        default => 1, # allow by default
        rules   => {...},
    );

rules

A hash reference of your permissions.

Top level keys are the entities. This can be groups, users, whichever way you choose to view it.

    {
        ENTITY => RULES,
    }

For each entity you provide an arrayref of the rules. The will be read and matched in sequential order. It's good practice to have an explicit last one as the catch-all for that entity. However, take into account that there is also the default. By default it will deny unless you change the default to allow.

    {
        ENTITY => [
            RULE1,
            RULE2,
        ],
    }

Each rule contains a key of the action, either to allow or deny, followed by a resource definition.

    {
        ENTITY => [
            ACTION => RESOURCE
        ]
    }

You can provide a value of star (*) to say 'this entity can do everything' or 'this entity cannot do anyting'. You can provide an arrayref of the resources you want to allow/deny.

    {
        Bender => [
            deny  => [ 'fly ship', 'command team' ],
            allow => '*', # allow everything else
        ],

        Leila => [
            deny  => ['goof off'],
            allow => [ 'fly ship', 'command team' ],
            # if none are matched, it will take the default
        ]
    }

You can also provide conditions as a hashref for each resource. The value should be either a star (*) to match key existence, or an arrayref to try and match the value.

    {
        Bender => [
            allow => {
                # must have booze to function
                functioning => { booze => '*' }
            },

            # allow friendship to these people
            allow => {
                friendship => { person => [ 'Leila', 'Fry', 'Amy' ]
            },

            # deny friendship to everyone else
            deny => ['friendship'],
        ]
    }

METHODS ^

check

    $auth->check( ENTITY, RESOURCE );
    $auth->check( ENTITY, RESOURCE, { CONDITIONS } );

You decide what entities and resources you have according to how you define the rules.

You can think of resources as possible actions on an interface:

    my $auth = Authorize::Rule->new(
        rules => {
            Sawyer => [ allow => [ 'view', 'edit' ] ]
        }
    );

    $auth->check( Sawyer => 'edit' )
        or die 'Sawyer is not allowed to edit';

However, if you have multiple interfaces (which you usually do in more complicated environments), your resources are those interfaces:

    my $auth = Authorize::Rule->new(
        rules => {
            Sawyer => [ allow => [ 'Dashboard', 'Forum' ] ],
        }
    );

    # can I access the dashboard?
    $auth->check( Sawyer => 'Dashboard' );

That's better. However, it doesn't describe what Sawyer can do in each resource. This is why you have conditions.

    my $auth = Authorize::Rule->new(
        rules => {
            Sawyer => [
                allow => {
                    Dashboard => { action => ['edit', 'view'] }
                }
            ]
        }
    );

    $auth->check( Sawyer => 'Dashboard', { action => 'delete' } )
        or die 'Stop trying to delete the Dashboard, Sawyer!';

AUTHOR ^

Sawyer X <xsawyerx@cpan.org>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2013 by Sawyer X.

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

syntax highlighting: