PHPackages                             nimblephp/authorization - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. nimblephp/authorization

ActiveLibrary[Authentication & Authorization](/categories/authentication)

nimblephp/authorization
=======================

Authorization for NimblePHP

0.0.2(2mo ago)088↓33.3%MITPHPPHP >=8.2

Since Sep 4Pushed 2mo agoCompare

[ Source](https://github.com/NimbleMVC/Authorization)[ Packagist](https://packagist.org/packages/nimblephp/authorization)[ RSS](/packages/nimblephp-authorization/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (3)Versions (4)Used By (0)

NimblePHP Authorization
=======================

[](#nimblephp-authorization)

Kompletna biblioteka autoryzacyjna dla frameworka NimblePHP z funkcjonalnościami:

- Bezpieczne zarządzanie użytkownikami i hasłami
- System Role-Based Access Control (RBAC)
- Ochrona przed atakami brute-force (Rate Limiting)
- Elastyczne, niestandardowe hasherowanie haseł
- Automatyczne aktualizowanie skrótów haseł
- Dwuetapowa weryfikacja (2FA) - TOTP i Email
- OAuth2 - Logowanie społeczne (GitHub)
- JWT - Bezstanowe tokeny dla API
- API Keys - Stacjonarne klucze dla dostępu programistycznego

Konfiguracja
------------

[](#konfiguracja)

Biblioteka obsługuje podstawową konfigurację poprzez zmienne środowiskowe.

### Zmienne środowiskowe

[](#zmienne-środowiskowe)

```
# Typ autoryzacji: 'username' lub 'email'
AUTHORIZATION_TYPE=username

# Nazwa tabeli użytkowników
AUTHORIZATION_TABLE=accounts

# Wymaganie aktywacji konta przed logowaniem (true/false)
AUTHORIZATION_REQUIRE_ACTIVATION=false

# Domyślna polityka autoryzacji - czy autoryzacja jest wymagana dla wszystkich kontrolerów (true/false)
AUTHORIZATION_REQUIRE_AUTH_BY_DEFAULT=false

# Konfiguracja kolumn
AUTHORIZATION_COLUMN_ID=id
AUTHORIZATION_COLUMN_USERNAME=username
AUTHORIZATION_COLUMN_EMAIL=email
AUTHORIZATION_COLUMN_PASSWORD=password
AUTHORIZATION_COLUMN_ACTIVE=active

# Konfiguracja Rate Limiting (ochrona przed atakami brute-force)
AUTHORIZATION_RATE_LIMIT_ENABLED=true
AUTHORIZATION_RATE_LIMIT_MAX_ATTEMPTS=5
AUTHORIZATION_RATE_LIMIT_LOCKOUT_DURATION=900
```

### Konfiguracja PHP

[](#konfiguracja-php)

```
use NimblePHP\Authorization\Config;

// Ustawienia typu autoryzacji
Config::$authType = 'email'; // lub 'username'

// Wymaganie aktywacji konta
Config::$requireActivation = true; // lub false

// Domyślna polityka autoryzacji
Config::$requireAuthByDefault = true; // lub false

// Konfiguracja kolumn
Config::$columns = [
    'id' => 'user_id',
    'username' => 'login',
    'email' => 'email_address',
    'password' => 'hashed_password',
    'active' => 'is_active'
];
```

Instalacja
----------

[](#instalacja)

```
composer require nimblephp/authorization
```

Bezpieczeństwo
--------------

[](#bezpieczeństwo)

### Rate Limiting (Ochrona przed atakami brute-force)

[](#rate-limiting-ochrona-przed-atakami-brute-force)

Biblioteka zawiera wbudowaną ochronę przed atakami brute-force na logowanie. System Rate Limiting śledzi nieudane próby logowania i tymczasowo blokuje konto.

#### Konfiguracja Rate Limiting

[](#konfiguracja-rate-limiting)

```
use NimblePHP\Authorization\Config;

// Włączenie/wyłączenie rate limitingu (domyślnie: true)
Config::$rateLimitEnabled = true;

// Maksymalna liczba nieudanych prób (domyślnie: 5)
Config::$rateLimitMaxAttempts = 5;

// Czas blokady w sekundach (domyślnie: 900 = 15 minut)
Config::$rateLimitLockoutDuration = 900;
```

#### Obsługiwanie excepcji Rate Limiting

[](#obsługiwanie-excepcji-rate-limiting)

```
use NimblePHP\Authorization\Authorization;
use NimblePHP\Authorization\Exceptions\RateLimitExceededException;

$auth = new Authorization();

try {
    $loggedIn = $auth->login('user@example.com', 'password123');
    if ($loggedIn) {
        echo "Zalogowano pomyślnie!";
    } else {
        echo "Nieprawidłowe dane logowania!";
    }
} catch (RateLimitExceededException $e) {
    echo "Konto tymczasowo zablokowane z powodu zbyt wielu nieudanych prób logowania.";
    echo "Spróbuj ponownie za " . $e->getRemainingLockoutTime() . " sekund.";
    // Zwróć HTTP 429 (Too Many Requests)
    http_response_code(429);
}
```

### Niestandardowe hashowanie haseł

[](#niestandardowe-hashowanie-haseł)

Biblioteka pozwala na implementację własnego systemu hashowania haseł poprzez interfejs `PasswordHasher`. Domyślnie używa bezpiecznego systemu VersionedHasher, ale możesz łatwo zastąpić go swoją implementacją.

#### Dostępne implementacje

[](#dostępne-implementacje)

Biblioteka zawiera kilka gotowych implementacji:

1. **DefaultPasswordHasher** - Domyślna implementacja używająca VersionedHasher (rekomendowana)

    - Automatycznie aktualizuje skróty haseł przy logowaniu
    - Obsługuje wiele wersji algorytmów hashowania
2. **BcryptPasswordHasher** - Użycie PHP's native password\_hash z algorytmem bcrypt

    - Bezpieczne, ale wolniejsze
    - Koszt: 12 (customizable)
3. **ArgonPasswordHasher** - Użycie PHP's password\_hash z algorytmem Argon2id

    - Najbardziej bezpieczne, oporne na ataki GPU
    - Pamięć: 65536 MB, Iteracje: 4
4. **CustomHasherExample** - Szablon do implementacji własnego hashera

#### Implementacja niestandardowego hashera

[](#implementacja-niestandardowego-hashera)

Utwórz klasę implementującą interfejs `PasswordHasher`:

```
use NimblePHP\Authorization\Interfaces\PasswordHasher;

class MyCustomHasher implements PasswordHasher
{
    /**
     * Hashuje hasło
     */
    public function hash(string $password): string
    {
        // Twoja implementacja hashowania
        return hash('sha256', $password . 'moja_sól');
    }

    /**
     * Weryfikuje hasło przeciwko skrótowi
     */
    public function verify(string $hash, string $password): bool
    {
        return hash_equals($hash, $this->hash($password));
    }

    /**
     * Sprawdza czy skrót wymaga rehash'u (dla algorytmów obsługujących aktualizację)
     */
    public function needsRehash(string $hash): bool
    {
        // Zwróć true jeśli hash wymaga aktualizacji
        return false;
    }
}
```

#### Konfiguracja niestandardowego hashera

[](#konfiguracja-niestandardowego-hashera)

```
use NimblePHP\Authorization\Config;
use MyCustomHasher;

// Zarejestruj swój hasher
Config::setPasswordHasher(new MyCustomHasher());
```

Lub użyj jednej z gotowych implementacji:

```
use NimblePHP\Authorization\Config;
use NimblePHP\Authorization\Hashers\BcryptPasswordHasher;
use NimblePHP\Authorization\Hashers\ArgonPasswordHasher;

// Użyj Bcrypt
Config::setPasswordHasher(new BcryptPasswordHasher());

// Lub Argon2id (najbezpieczniejszy)
Config::setPasswordHasher(new ArgonPasswordHasher());
```

#### Automatyczne aktualizowanie haseł

[](#automatyczne-aktualizowanie-haseł)

System domyślnie (z DefaultPasswordHasher) automatycznie aktualizuje hasła podczas logowania jeśli potrzebne. Umożliwia to bezproblemową migrację między algorytmami:

```
// Jeśli zmienisz algorytm hasherowania, wszystkie hasła zostaną automatycznie
// zaktualizowane przy następnym logowaniu użytkownika
try {
    $loggedIn = $auth->login('user@example.com', 'password123');
    // Hasło zostało automatycznie rehash'owane jeśli było potrzebne
} catch (RateLimitExceededException $e) {
    // Obsłuż rate limit
}
```

### Dwuetapowa weryfikacja (2FA)

[](#dwuetapowa-weryfikacja-2fa)

Biblioteka zawiera wbudowaną obsługę uwierzytelniania dwuetapowego (2FA/MFA). Obsługuje wiele metod weryfikacji:

- **TOTP** (Time-based One-Time Password) - zgodne z Google Authenticator i innymi aplikacjami
- **Email** - kody wysyłane na adres email użytkownika

#### Konfiguracja 2FA

[](#konfiguracja-2fa)

Zarejestruj dostawców 2FA w Twojej aplikacji:

```
use NimblePHP\Authorization\Config;
use NimblePHP\Authorization\Providers\TOTPProvider;
use NimblePHP\Authorization\Providers\EmailProvider;

// Zarejestruj TOTP provider (Google Authenticator)
Config::registerTwoFactorProvider('totp', new TOTPProvider('Moja Aplikacja'));

// Zarejestruj Email provider
$emailProvider = new EmailProvider();
$emailProvider->setEmailCallback(function($email, $code) {
    // Wyślij kod na email użytkownika
    mail($email, 'Twój kod weryfikacyjny', "Kod: $code");
});
Config::registerTwoFactorProvider('email', $emailProvider);
```

#### TOTP (Google Authenticator)

[](#totp-google-authenticator)

TOTP jest najbardziej bezpieczną i popularną metodą 2FA. Generuje kody QR, które użytkownik skanuje swoją aplikacją authenticatora.

**Włączenie 2FA dla użytkownika:**

```
use NimblePHP\Authorization\Authorization;

$auth = new Authorization();

// Sprawdź że użytkownik jest zalogowany
if ($auth->isAuthorized()) {
    // Pobierz TOTP provider
    $totp = Config::getTwoFactorProvider('totp');

    // Włącz 2FA i zwróć informacje o QR kodzie
    $result = $auth->enableTwoFactorAuth($totp);

    echo "Secret: " . $result['secret'];
    echo "QR Code URL: " . $result['qr_code'];
    echo "Provider: " . $result['provider'];
}
```

**Wyświetlanie QR kodu dla użytkownika:**

```
// W szablonie HTML