Download the PHP package zennit/abac without Composer

ABAC (Attribute-Based Access Control) for Laravel

A flexible and powerful ABAC implementation for Laravel applications.

Table of Contents

1. Introduction
2. Prerequisites
3. Installation
4. Quick Start
5. Basic Usage
6. API Routes
7. Commands
8. Configuration
9. Database Schema
10. Performance Monitoring
11. License
12. Contributing
13. Reporting Issues & Questions

Introduction

ABAC provides fine-grained access control by evaluating attributes of users, resources, and the context of a request.

This package integrates seamlessly with Laravel to offer powerful access control mechanisms.

Prerequisites

• Laravel 11.0 or higher
• LaravelSanctum 4.0 or higher
• PHP 8.2 or higher

Installation

Install the package via Composer:

Add the service provider to your bootstrap/providers.php:

Quick Start

Migrate

Setup initial data using the provided JSON files. You can use the following example JSON structure to seed your database

This example creates a policy that determines who can view posts. It allows viewing when either:

• The post ID equals 1, OR
• The user ID equals 1

This JSON structure follows the database schema:

• object_attributes: Maps to abac_object_additional_attributes table
• subject_attributes: Maps to abac_subject_additional_attributes table
• policies: Maps to abac_policies table
• chains: Maps to abac_chains table (supports nested chains via chain_id)
• checks: Maps to abac_checks table

Note: The chains array supports nested structures where a chain can reference another chain using the chain_id field. Either chain_id or checks must be provided in a chain, but not both.

Before running the seeder

• Make sure you have published the configuration file and set the correct paths for the JSON files in your environment.

This will add the required environment variables to your .env file and create the configuration file at config/abac.php.

• Also include the DatabaseSeeder into your DatabaseSeeder class

Run the seeder command

After seeding the database

The final step to complete the setup is to add the trait to all the classes you have defined in path_patterns in the configuration file.

• Check the Configuration section for more details.

Basic Usage

Here's an example of how to perform access control checks:

The can() method evaluates the access request and returns a boolean indicating whether access is granted.

The evaluate() method can be used to get detailed information about the evaluation process, look at AccessResult for more details.

The evaluation result is automatically cached using the subject ID, resource, and operation as the cache key.

Available Operators

All operators are defined in the src/Enums/Operators directory

Logical Operators

• and
• or

Arithmetic Operators

• equals
• not_equals
• greater_than
• less_than
• greater_than_equals
• less_than_equals

String Operators

• contains
• not_contains
• starts_with
• ends_with
• not_starts_with
• not_ends_with

Note: Make sure when creating new objects in the database, you make use of these operators, not doing so is going to make the conditions invalid. If you want us to support other operators make a PR or raise an issue

Middleware

The ABAC package uses the EnsureAccess Middleware to check whether the requesting user has the necessary permissions to access a specific resource and method.

How It Works

The middleware is automatically registered when you add the service provider to your bootstrap/providers.php file. It evaluates access requests based on the following parameters:

• Resource: The resource being accessed (e.g., App\Models\Post, App\Models\User, etc.).
• Method: The HTTP method of the request (e.g., GET, POST, etc.).
• Subject: The user making the request (e.g., $request->user()).

For more details, refer to the AccessContext class.

Accessing the Evaluation Result

After processing the request, the middleware adds the evaluation result to the request object. You can access it using $request->abac().

Usage Example

To use the middleware, simply apply it to your routes. For example:

Important Notes

• Ensure that the abac middleware is applied to the routes you want to protect.
• The middleware evaluates access dynamically based on the defined policies and attributes.

API Routes

The following API routes are available for managing ABAC-related data. These routes must be protected by the abac middleware (look at Configuration for more details) and can be prefixed using the ABAC_ROUTE_PREFIX environment variable:

For Update and Create Operations

When creating or updating ABAC resources, you have flexibility in how you structure your requests, as long as they comply with the validation rules defined in the FormRequests classes. These rules ensure data integrity and proper relationships between policies, chains, and checks.

You can create complex policy structures in a single request or build them incrementally through separate API calls. The validation system will ensure that your data maintains proper hierarchical relationships and contains all required fields.

For detailed validation rules and request structure examples, refer to the FormRequest classes:

• AbacPolicyRequest
• AbacChainRequest
• AbacCheckRequest
• AbacObjectAttributeRequest
• AbacSubjectAttributeRequest

Pagination

All index responses are paginated and support the following query parameters:

• page: The page number to retrieve (default: 1)
• per_page: The number of items per page (default: 10)

The pagination response format includes both the data items and pagination metadata:

Object Attributes

• Get Object Attributes

  • Endpoint: /{prefix}/object-attributes
  • Method: GET
  • Description: Retrieve a list of object attributes.
  • Request Body: None
  • Response:
• Delete Object Attribute
  • Endpoint: /{prefix}/object-attributes/{id}
  • Method: DELETE
  • Description: Delete a specific object attribute by ID.
  • Request Body: None
  • Response:

Subject Attributes

• Get Subject Attributes
  • Endpoint: /{prefix}/subject-attributes
  • Method: GET
  • Description: Retrieve a list of subject attributes.
  • Request Body: None

• Response:

• Delete Subject Attribute
  • Endpoint: /{prefix}/subject-attributes/{id}
  • Method: DELETE
  • Description: Delete a specific subject attribute by ID.
  • Request Body: None
  • Response:

Policies

• Get Policies

  • Endpoint: /{prefix}/policies
  • Method: GET
  • Description: Retrieve a list of policies.
  • Request Body: None
  • Response:
• Delete Policy
  • Endpoint: /{prefix}/policies/{id}
  • Method: DELETE
  • Description: Delete a specific policy by ID.
  • Request Body: None
  • Response:

Chains

• Get Chains

  • Endpoint: /{prefix}/policies/{policy}/chains
  • Method: GET
  • Description: Retrieve a list of chains for a given policy.
  • Request Body: None
  • Response:
• Delete Chain
  • Endpoint: /{prefix}/policies/{policy}/chains/{id}
  • Method: DELETE
  • Description: Delete a specific chain from a policy.
  • Request Body: None
  • Response:

Checks

• Get Checks

  • Endpoint: /{prefix}/policies/{policy}/chains/{chain}/checks
  • Method: GET
  • Description: Retrieve a list of checks for a given chain.
  • Request Body: None
  • Response:
• Delete Check
  • Endpoint: /{prefix}/policies/{policy}/chains/{chain}/checks/{id}
  • Method: DELETE
  • Description: Delete a specific check from a chain.
  • Request Body: None
  • Response:

To register the ABAC routes in your application, create a new service provider:

Then update the provider to register the routes:

Register your new service provider in config/app.php:

Commands

Publishing Commands

Force Options

All commands support the --force option to skip confirmations:

Cache Management

Configuration

Environment Variables

Full Configuration Options

Database Schema

Performance Monitoring

The ABAC package includes built-in performance monitoring capabilities:

Caching System

• Automatic Result Caching: Access control evaluations are automatically cached to improve performance
• Configurable Cache Store: Supports multiple cache backends (database, Redis, file, etc.) via the ABAC_CACHE_STORE setting
• Custom Cache Prefix: All cache keys use the configured prefix (ABAC_CACHE_PREFIX) for easy identification
• Cache Registry: The system maintains a registry of all cache keys for efficient invalidation
• Serialization Strategy: Evaluation results are serialized efficiently, storing SQL queries and bindings rather than full objects

Cache Management

• All evaluation results are cached by default to improve performance
• Cache storage uses the store defined in your configuration (ABAC_CACHE_STORE)
• Cache warm-up can be scheduled with ABAC_CACHE_WARMING_SCHEDULE option
• If caching is disabled (ABAC_CACHE_ENABLED=false), evaluations will be performed for each request

Performance Metrics

• The package monitors the performance of all access control evaluations
• Any evaluation that takes longer than the configured threshold (ABAC_SLOW_EVALUATION_THRESHOLD, default 100ms) will log a warning
• Performance metrics can be viewed in your configured log channel (ABAC_LOG_CHANNEL)

These monitoring tools help identify and resolve performance bottlenecks in your access control policies.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please read the CONTRIBUTING file for details on how to contribute to this project.

Reporting Issues & Questions

If you encounter any issues, have questions, or need assistance with the ABAC package, please feel free to open an issue on our GitHub repository:

https://github.com/zennit-dev/abac/issues

Our team monitors the issues board regularly and will respond as soon as possible. When reporting issues, please include:

• Laravel and PHP versions
• Package version
• Steps to reproduce the issue
• Expected and actual behavior
• Any relevant error messages or logs

This helps us address your concerns more efficiently.