Download the PHP package nimblephp/authorization without Composer

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

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

Zmienne środowiskowe

Konfiguracja PHP

Instalacja

Bezpieczeństwo

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

Obsługiwanie excepcji Rate Limiting

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

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

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

Konfiguracja niestandardowego hashera

Lub użyj jednej z gotowych implementacji:

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:

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

Zarejestruj dostawców 2FA w Twojej aplikacji:

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:

Wyświetlanie QR kodu dla użytkownika:

Weryfikacja kodu TOTP podczas logowania:

Email 2FA

Email provider wysyła kody weryfikacyjne na adres email użytkownika.

Konfiguracja:

Wysłanie kodu weryfikacyjnego:

Wyłączenie 2FA

Kody odzyskania (Recovery Codes)

TOTP provider generuje kody odzyskania, które użytkownik może użyć jeśli utraci dostęp do swojego authenticatora:

Funkcjonalności

Atrybuty autoryzacji

Biblioteka oferuje elastyczny system kontroli dostępu za pomocą atrybutów PHP 8+.

Dostępne atrybuty

• #[RequireAuth] - wymaga autoryzacji dla danego kontrolera/metody
• #[NoAuth] - wyłącza autoryzację dla danego kontrolera/metody

Konfiguracja domyślnej polityki autoryzacji

Możesz skonfigurować domyślną politykę autoryzacji dla całej aplikacji:

Przykłady użycia atrybutów

Opcja 1: Domyślnie autoryzacja NIE wymagana

Opcja 2: Domyślnie autoryzacja WYMAGANA

Middleware autoryzacji

Biblioteka dostarcza AuthorizationMiddleware który automatycznie sprawdza autoryzację na podstawie atrybutów i konfiguracji. Middleware należy zarejestrować w aplikacji NimblePHP.

Logika działania middleware:

1. Jeśli jest atrybut #[NoAuth] → autoryzacja NIE jest wymagana
2. Jeśli jest atrybut #[RequireAuth] → autoryzacja JEST wymagana
3. Jeśli nie ma żadnego atrybutu → sprawdza konfigurację $requireAuthByDefault

Klasa Authorization

Główna klasa odpowiedzialna za zarządzanie sesjami użytkowników i proces autoryzacji.

Metody klasy Authorization

• isAuthorized(): bool - sprawdza czy użytkownik jest zalogowany
• getAuthorizedId(): int - zwraca ID zalogowanego użytkownika
• getCurrentUser(): ?array - zwraca dane aktualnie zalogowanego użytkownika
• register(string $username, string $password): bool - rejestruje nowego użytkownika
• login(string $username, string $password): bool - loguje użytkownika (z automatycznym rehash hasła jeśli potrzebne)
• logout(): void - wylogowuje użytkownika

Klasa Account

Klasa odpowiedzialna za operacje bazodanowe na kontach użytkowników.

Metody klasy Account

• getId(): ?int - zwraca ID konta
• setId(int $id): void - ustawia ID konta
• getTableInstance(): Table - zwraca instancję tabeli bazy danych
• getAccount(): ?array - zwraca dane konta bieżącego użytkownika
• find(array $conditions): ?array - wyszukuje konto na podstawie warunków
• insert(array $data): bool - dodaje nowe konto do bazy danych
• update(array $data): bool - aktualizuje dane konta
• usernameExists(string $username): bool - sprawdza czy nazwa użytkownika już istnieje
• emailExists(string $email): bool - sprawdza czy email już istnieje
• changePassword(string $password): bool - zmienia hasło konta
• isActive(?int $accountId = null): bool - sprawdza czy konto jest aktywne
• activate(?int $accountId = null): bool - aktywuje konto
• deactivate(?int $accountId = null): bool - dezaktywuje konto

Role-Based Access Control (RBAC)

Biblioteka oferuje kompletny system RBAC (Role-Based Access Control) umożliwiający precyzyjną kontrolę dostępu na podstawie ról i uprawnień.

Konfiguracja RBAC

Tabele bazy danych

Przed rozpoczęciem korzystania z RBAC należy użyć komendy CLI uruchamiającą migracje modułów:

Zmienne środowiskowe dla RBAC

Atrybuty RBAC

Dostępne atrybuty

Podstawowe atrybuty:

• #[HasRole('admin')] - sprawdza czy użytkownik ma określoną rolę
• #[HasPermission('users.edit')] - sprawdza czy użytkownik ma określone uprawnienie

Zaawansowane atrybuty dla wielu sprawdzeń:

• #[HasAnyRole('admin', 'moderator')] - sprawdza czy użytkownik ma którąkolwiek z wymienionych ról
• #[HasAllRoles('admin', 'editor')] - sprawdza czy użytkownik ma wszystkie wymienione role
• #[HasAnyPermission('users.edit', 'users.delete')] - sprawdza czy użytkownik ma którekolwiek z wymienionych uprawnień

Przykład użycia atrybutów RBAC

Klasa Role

Zarządza rolami w systemie.

Metody klasy Role

• create(string $name, ?string $description = null): bool - tworzy nową rolę
• findByName(string $name): ?array - wyszukuje rolę po nazwie
• assignToUser(int $userId): bool - przypisuje rolę użytkownikowi
• removeFromUser(int $userId): bool - usuwa rolę od użytkownika
• addPermission(int $permissionId): bool - dodaje uprawnienie do roli
• removePermission(int $permissionId): bool - usuwa uprawnienie z roli
• getPermissions(): array - zwraca wszystkie uprawnienia roli
• getUsersWithRole(): array - zwraca wszystkich użytkowników z daną rolą

Klasa Permission

Zarządza uprawnieniami w systemie.

Metody klasy Permission

• create(string $name, ?string $description = null, ?string $group = null): bool - tworzy nowe uprawnienie
• findByName(string $name): ?array - wyszukuje uprawnienie po nazwie
• assignToRole(int $roleId): bool - przypisuje uprawnienie do roli
• getRolesWithPermission(): array - zwraca wszystkie role mające dane uprawnienie
• getPermissionGroups(): array - zwraca wszystkie grupy uprawnień

Rozszerzone metody klasy Authorization

Metody sprawdzania ról i uprawnień

• hasRole(string $roleName): bool - sprawdza czy użytkownik ma rolę
• hasPermission(string $permissionName): bool - sprawdza czy użytkownik ma uprawnienie
• hasAnyRole(array $roleNames): bool - sprawdza czy użytkownik ma którąkolwiek z ról
• hasAllRoles(array $roleNames): bool - sprawdza czy użytkownik ma wszystkie role
• hasAnyPermission(array $permissionNames): bool - sprawdza czy użytkownik ma którekolwiek uprawnienie
• hasAllPermissions(array $permissionNames): bool - sprawdza czy użytkownik ma wszystkie uprawnienia

Metody zarządzania rolami

• getUserRoles(): array - zwraca wszystkie role użytkownika
• getUserPermissions(): array - zwraca wszystkie uprawnienia użytkownika
• assignRole(string $roleName): bool - przypisuje rolę użytkownikowi
• removeRole(string $roleName): bool - usuwa rolę od użytkownika

Rozszerzone metody klasy Account

Metody zarządzania rolami konta

• assignRole(string $roleName, ?int $accountId = null): bool - przypisuje rolę do konta
• removeRole(string $roleName, ?int $accountId = null): bool - usuwa rolę z konta
• hasRole(string $roleName, ?int $accountId = null): bool - sprawdza czy konto ma rolę
• hasPermission(string $permissionName, ?int $accountId = null): bool - sprawdza czy konto ma uprawnienie
• getRoles(?int $accountId = null): array - zwraca wszystkie role konta
• getPermissions(?int $accountId = null): array - zwraca wszystkie uprawnienia konta
• setRoles(array $roleNames, ?int $accountId = null): bool - ustawia role dla konta (zastępuje istniejące)
• clearRoles(?int $accountId = null): bool - usuwa wszystkie role z konta

Przykład użycia

Podstawowa konfiguracja

Rejestracja użytkownika

Autoryzacja przez username

Autoryzacja przez email

Logowanie użytkownika

Logowanie przez username lub email

Metoda login() automatycznie rozpoznaje typ autoryzacji na podstawie konfiguracji:

HTTP Basic Authentication

Biblioteka wspiera HTTP Basic Auth (RFC 7617) dla API i dostępu programistycznego:

Wysyłanie HTTP Basic Auth (z przeglądarki/curl):

W JavaScript/Fetch API:

Sprawdzanie statusu autoryzacji

Wylogowanie

Operacje na koncie

Konfigurowalne nazwy kolumn

Biblioteka pozwala na dostosowanie nazw kolumn w bazie danych:

Zarządzanie kontem

Aktywacja kont

Biblioteka obsługuje opcjonalną aktywację kont użytkowników. Gdy aktywacja jest włączona, nowo zarejestrowani użytkownicy nie mogą się zalogować dopóki ich konta nie zostaną aktywowane.

Konfiguracja aktywacji

Rejestracja z aktywacją

Gdy aktywacja jest włączona, nowo utworzone konta mają status active = 0:

Zarządzanie aktywacją kont

Logowanie z aktywacją

Gdy aktywacja jest włączona, tylko aktywne konta mogą się zalogować:

Wyłączenie aktywacji

Gdy aktywacja jest wyłączona, wszystkie konta są automatycznie traktowane jako aktywne:

Praca z RBAC

Tworzenie ról i uprawnień

Przypisywanie uprawnień do ról

Zarządzanie użytkownikami i rolami

Zaawansowane sprawdzenia dostępu

Pobieranie ról i uprawnień użytkownika

Użycie atrybutów w kontrolerach

Zarządzanie rolami przez API/admin panel

Walidacja danych

Biblioteka zawiera wbudowaną walidację:

• Nazwa użytkownika: nie może być pusta
• Hasło: minimum 6 znaków
• Unikalność: nazwa użytkownika musi być unikalna w systemie

Bezpieczeństwo

• Hasła są hashowane przy użyciu biblioteki VersionedHasher
• Automatyczne rehash hasła podczas logowania jeśli algorytm się zmienił
• Wszystkie dane wejściowe są walidowane
• Sesje są zarządzane przez framework NimblePHP
• Chroni przed SQL injection poprzez używanie przygotowanych zapytań

Struktura tabeli bazy danych

Biblioteka oczekuje tabel z następującymi kolumnami:

Główna tabela użytkowników:

Uwaga: Kolumna active jest wymagana jeśli chcesz używać funkcji aktywacji kont. Jeśli nie planujesz używać tej funkcji, kolumna może być pominięta lub zawsze ustawiona na 1.

Możesz dostosować nazwy kolumn poprzez konfigurację:

Wyjątki

Biblioteka może rzucać następujące wyjątki:

• InvalidArgumentException - przy nieprawidłowych danych wejściowych
• UnauthorizedException - gdy użytkownik próbuje uzyskać dostęp do chronionego zasobu bez autoryzacji
• RateLimitExceededException - gdy limit nieudanych prób logowania został przekroczony (HTTP 429)
• TwoFactorException - gdy weryfikacja kodu 2FA nie powiodła się (kod nieprawidłowy lub wygasły)
• PendingTwoFactorException - gdy użytkownik zalogował się, ale wymaga weryfikacji 2FA (zawiera ID użytkownika i dostawcę)

OAuth2 - Logowanie społeczne

Biblioteka wspiera logowanie za pośrednictwem OAuth2. Dostarczone są implementacje dla GitHub i przygotowana architektura do łatwego dodawania dodatkowych dostawców (Google, Facebook, itp.).

Konfiguracja GitHub OAuth2

1. Rejestracja aplikacji na GitHub

1. Przejdź na https://github.com/settings/developers
2. Kliknij "New OAuth App"
3. Wypełnij formularz:
   • Application name: Nazwa aplikacji
   • Homepage URL: https://twoja-domena.com
   • Authorization callback URL: https://twoja-domena.com/oauth/github/callback
4. Skopiuj Client ID i Client Secret

2. Konfiguracja w aplikacji

3. Inicjalizacja logowania OAuth

4. Obsługa callback'u

Dane otrzymane z OAuth2

Po pomyślnej autoryzacji otrzymujesz takie dane:

Dla GitHub OAuth2:

Tworzenie niestandardowego providera OAuth2

Aby dodać nowego dostawcę OAuth2, stwórz klasę implementującą OAuthProvider:

Następnie zarejestruj providera:

Bezpieczeństwo OAuth2

• Stan jest generowany losowo i walidowany podczas callbacku (ochrona przed CSRF)
• Dane OAuth są przechowywane w kolumnach account_oauth_id i account_oauth_provider
• Logowanie OAuth obsługuje matching e-maila - jeśli użytkownik z tym e-mailem już istnieje, jego konto jest połączone
• Można wymusić tworzenie nowych kont poprzez parametr createIfNotExists

Token-Based Authentication

Biblioteka wspiera nowoczesne metody autoryzacji API oparte na tokenach.

JWT (JSON Web Tokens)

RFC 7519 standard dla stateless, bezpiecznych tokenów.

Konfiguracja

Generowanie tokenu

Walidacja tokenu

API Keys

Stacjonarne klucze API z loggingiem i rate limitingiem.

Konfiguracja

Generowanie klucza

Walidacja klucza

Zarządzanie kluczami

Rate Limiting

Dokumentacja

• JWT + API Keys Guide - Comprehensive JWT and API Keys documentation
• 2FA Guide - Two-Factor Authentication implementation
• GitHub OAuth Guide - GitHub OAuth2 login setup
• Custom Hasher Guide - Custom password hasher implementation