README

Authentication, session management and RBAC | API

Install

composer require rudra/auth

Usage

use Rudra\Auth\AuthFacade as Auth;

Configuration

For the component to work correctly, you need to add the following parameters to the Rudra configuration file:

# Secret key for encrypting cookies and generating session hashes
secret: your_super_secret_key_here

# Roles for Role-Based Access Control (the smaller the number, the higher the privilege)
roles:
    admin: 0
    editor: 1
    moderator: 2
    user: 3

# Environment (in the 'test' environment, cookies are not deleted on logout)
environment: production

User registration

$user = [
    "email"    => "user@email.com",
    "password" => Auth::bcrypt("password")
];

Getting a user from the database

$user = [
    "email"    => "user@email.com",
    "password" => "password_hash",
    "role"     => "admin"
];

Authentication

The second argument is the plain text password entered by the user. The $user['password'] must contain a hash from the database.

Auth::authentication(
    $user, 
    "password", 
    ["admin/dashboard", "login"],
    ["error" => "Wrong access data"]
);

Note: For the "Remember Me" feature to work, the login form must contain a checkbox with the name remember_me.

Login form example

<form method="POST" action="/login">
    <input type="email" name="email" required>
    <input type="password" name="password" required>
    <label>
        <input type="checkbox" name="remember_me"> Remember me / Запомнить меня
    </label>
    <button type="submit">Login</button>
</form>

Restoring session (Remember Me)

Called at the beginning of the application loading (before authorization check). If the user has valid 'Remember Me' cookies, the session will be restored automatically.

Auth::restoreSessionIfSetRememberMe("login");

Authorization check

General authorization check

Check if the user is authorized. If not — redirect to 'login'

if (!Auth::authorization(null, "login")) {
    exit;
}

If you just need to get a boolean value without a redirect (for example, for an API):

$isLoggedIn = Auth::authorization(); 

Access to personal user resources

For access control to a specific user's resources (e.g., profile, personal data), a token is used. The token is generated from the user's password, email, and session hash.

// Generate token for the current user
$token = md5($user['password'] . $user['email'] . Auth::getSessionHash());

// Check if the token matches the session token
if (!Auth::authorization($token, "login")) {
    exit;
}

Role-Based Access Control

Check if the current role ('admin') has privileges not lower than the requested ones ('editor'). If privileges are insufficient — redirect to 'error/403'

use Rudra\Container\Facades\Session;

// Get the role of the current user from the session (for example, after authorization)
if (Session::has("user")) {
   $currentRole = Session::get("user")['role'] ?? 'user';
}

// Check if the permissions are sufficient for access (for example, 'editor' level is required)
if (!Auth::roleBasedAccess($currentRole, "editor", "error/403")) {
    exit;
}

Log out of the authentication session with a redirect to the login page

Auth::logout("login");

License

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0) — a free, open-source license that:

• Requires preservation of copyright and license notices,
• Allows commercial and non-commercial use,
• Requires that any modifications to the original files remain open under MPL-2.0,
• Permits combining with proprietary code in larger works.

📄 Full license text: LICENSE
🌐 Official MPL-2.0 page: https://mozilla.org/MPL/2.0/