[docs] Přidána dokumentace systému přihlašování pro použití v jiných projektech
This commit is contained in:
stepan
@@ -0,0 +1,146 @@
|
|||||||
|
# Systém přihlašování MSPPPPaM – dokumentace pro implementaci
|
||||||
|
|
||||||
|
Tento dokument popisuje hotový systém přihlašování v PHP a MySQL,
|
||||||
|
který chci použít v novém projektu. Systém je připravený, neupravuj
|
||||||
|
jeho soubory – pouze ho používej.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Umístění souborů
|
||||||
|
|
||||||
|
Všechny soubory systému jsou ve složce `auth/` v kořenovém adresáři projektu.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Seznam souborů a jejich funkce
|
||||||
|
|
||||||
|
| Soubor | Popis |
|
||||||
|
|---|---|
|
||||||
|
| `auth/config.php` | Veškerá konfigurace systému (DB přihlašovací údaje, URL, limity, přepínače). Upravuje se při nasazení. |
|
||||||
|
| `auth/db.php` | Připojení k MySQL přes PDO. Výsledkem je proměnná `$pdo`. |
|
||||||
|
| `auth/auth.php` | Hlavní soubor – vkládá se na začátek chráněných stránek. Ověří přihlášení a nastaví proměnné (viz níže). |
|
||||||
|
| `auth/login.php` | Přihlašovací stránka s formulářem. Obsahuje ochranu proti brute force a CSRF. |
|
||||||
|
| `auth/logout.php` | Odhlášení – zruší session i remember me cookie. Přesměruje na login. |
|
||||||
|
| `auth/registrace.php` | Registrace nového uživatele (pokud je povolena v config.php). |
|
||||||
|
| `auth/reset_hesla.php` | Formulář pro zaslání odkazu na obnovu hesla emailem. |
|
||||||
|
| `auth/nove_heslo.php` | Stránka z odkazu v emailu – umožní zadat nové heslo. |
|
||||||
|
| `auth/admin.php` | Administrační rozhraní – správa uživatelů, zobrazení konfigurace, test emailu. Přístupné pouze adminům. |
|
||||||
|
| `auth/mail.php` | Pomocná funkce `odesli_mail()` pro odesílání emailů přes PHP `mail()`. |
|
||||||
|
| `auth/install.php` | Jednorázový instalační skript – vytvoří tabulky v DB a prvního admina. Po instalaci zablokován souborem `install.lock`. |
|
||||||
|
| `auth/js/heslo-sila.js` | JavaScript pro kontrolu síly hesla pomocí knihovny zxcvbn (Dropbox). Používají ho stránky s formuláři pro zadání hesla. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Jak použít systém na chráněné stránce
|
||||||
|
|
||||||
|
Na začátek každého PHP souboru, jehož obsah chci chránit, vložím:
|
||||||
|
|
||||||
|
```php
|
||||||
|
require_once 'auth/auth.php';
|
||||||
|
```
|
||||||
|
|
||||||
|
Po načtení jsou k dispozici tyto proměnné:
|
||||||
|
|
||||||
|
| Proměnná | Typ | Popis |
|
||||||
|
|---|---|---|
|
||||||
|
| `$auth_prihlasen` | `bool` | `true` pokud je uživatel přihlášen, jinak `false`. Nastaveno vždy. |
|
||||||
|
| `$auth_uzivatel['id']` | `int\|null` | ID přihlášeného uživatele, nebo `null` pokud není přihlášen. |
|
||||||
|
| `$auth_uzivatel['email']` | `string\|null` | Email přihlášeného uživatele, nebo `null`. |
|
||||||
|
| `$auth_uzivatel['admin']` | `bool` | `true` pokud je přihlášený uživatel admin, jinak `false`. Nastaveno vždy. |
|
||||||
|
| `$auth_logout_html` | `string` | Připravený HTML kód s emailem uživatele, tlačítkem odhlášení a (pro adminy) odkazem na administraci. Neprázdný pouze pokud je uživatel přihlášen. Použití: `echo $auth_logout_html;` |
|
||||||
|
| `$auth_login_html` | `string` | Připravený HTML formulář pro přihlášení (email, heslo, zapamatovat si mě, CSRF token). Neprázdný pouze pokud uživatel NENÍ přihlášen. Odesílá data na `login.php`, které po přihlášení přesměruje zpět na aktuální stránku. Použití: `echo $auth_login_html;` |
|
||||||
|
|
||||||
|
### Dva režimy fungování (nastavení v `auth/config.php`)
|
||||||
|
|
||||||
|
**`VYZADOVAT_PRIHLASENI = true`** (výchozí):
|
||||||
|
Nepřihlášený uživatel je automaticky přesměrován na přihlašovací stránku.
|
||||||
|
Na chráněnou stránku se dostane až po přihlášení.
|
||||||
|
|
||||||
|
**`VYZADOVAT_PRIHLASENI = false`**:
|
||||||
|
Stránka se zobrazí všem. Pomocí `$auth_prihlasen` si stránka sama
|
||||||
|
rozhodne, co nepřihlášenému uživateli ukáže.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Databázové tabulky
|
||||||
|
|
||||||
|
Systém přihlašování vytváří a spravuje tyto tabulky:
|
||||||
|
|
||||||
|
### `auth_users` – uživatelé přihlašovacího systému
|
||||||
|
|
||||||
|
| Sloupec | Typ | Popis |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | `INT UNSIGNED` | Primární klíč, auto increment |
|
||||||
|
| `email` | `VARCHAR(255)` | Email uživatele, unikátní |
|
||||||
|
| `heslo` | `VARCHAR(255)` | Bcrypt hash hesla |
|
||||||
|
| `admin` | `TINYINT(1)` | 0 = běžný uživatel, 1 = admin |
|
||||||
|
| `vytvoreno` | `DATETIME` | Datum a čas registrace |
|
||||||
|
|
||||||
|
### `auth_remember_tokens` – tokeny pro "zapamatovat si mě"
|
||||||
|
|
||||||
|
Spravuje systém přihlašování automaticky. Není potřeba upravovat.
|
||||||
|
|
||||||
|
### `auth_brute_force` – záznamy neúspěšných přihlášení
|
||||||
|
|
||||||
|
Spravuje systém přihlašování automaticky. Není potřeba upravovat.
|
||||||
|
|
||||||
|
### `auth_password_resets` – tokeny pro obnovu hesla
|
||||||
|
|
||||||
|
Spravuje systém přihlašování automaticky. Není potřeba upravovat.
|
||||||
|
|
||||||
|
### `users` – uživatelé konkrétní služby
|
||||||
|
|
||||||
|
Tato tabulka propojuje systém přihlašování s tvým projektem.
|
||||||
|
Systém přihlašování ji vytvoří při instalaci se základní strukturou:
|
||||||
|
|
||||||
|
| Sloupec | Typ | Popis |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | `INT UNSIGNED` | Primární klíč, auto increment |
|
||||||
|
| `uzivatel_id` | `INT UNSIGNED` | Cizí klíč na `auth_users.id` (ON DELETE CASCADE) |
|
||||||
|
|
||||||
|
**Tuto tabulku rozšíříš o vlastní sloupce** podle potřeb projektu
|
||||||
|
(jméno, telefon, nastavení, apod.). Systém přihlašování ji nebude
|
||||||
|
nijak měnit – pouze při registraci nového uživatele do ní vloží
|
||||||
|
prázdný řádek s `uzivatel_id`.
|
||||||
|
|
||||||
|
Propojení s uživatelem přihlašovacího systému:
|
||||||
|
```sql
|
||||||
|
SELECT u.*, au.email
|
||||||
|
FROM users u
|
||||||
|
JOIN auth_users au ON au.id = u.uzivatel_id
|
||||||
|
WHERE u.uzivatel_id = :id
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Konfigurace (auth/config.php)
|
||||||
|
|
||||||
|
Při nasazení do projektu je potřeba vyplnit:
|
||||||
|
|
||||||
|
- `DB_HOST`, `DB_NAME`, `DB_USER`, `DB_PASS` – přihlašovací údaje k MySQL
|
||||||
|
- `PROJEKT_NAZEV` – název projektu (zobrazuje se na přihlašovací stránce)
|
||||||
|
- `PROJEKT_URL` – základní URL webu (používá se v odkazech v emailech)
|
||||||
|
- `MAIL_ODESILATEL` – emailová adresa odesílatele (musí být autorizována SPF záznamem domény)
|
||||||
|
- `MAIL_TEST_ADRESA` – adresa pro testovací email v admin rozhraní
|
||||||
|
- `REGISTRACE_OTEVRENA` – `true` = veřejná registrace, `false` = pouze admin zakládá uživatele
|
||||||
|
- `VYZADOVAT_PRIHLASENI` – `true` = přesměrovat nepřihlášené, `false` = stránka rozhoduje sama
|
||||||
|
|
||||||
|
Cesty ke stránkám auth systému (pokud je složka `auth/` jinde než v kořeni webu):
|
||||||
|
- `AUTH_LOGIN_URL`, `AUTH_LOGOUT_URL`, `AUTH_ADMIN_URL`
|
||||||
|
- `AUTH_REGISTRACE_URL`, `AUTH_RESET_URL`
|
||||||
|
- `AUTH_REDIRECT_PO_PRIHLASENI` – kam přesměrovat po přihlášení
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Bezpečnostní vlastnosti systému
|
||||||
|
|
||||||
|
Pro přehled – systém řeší:
|
||||||
|
- Hesla hashována bcryptem (`password_hash` s `PASSWORD_DEFAULT`)
|
||||||
|
- Ochrana před SQL injection – výhradně PDO prepared statements
|
||||||
|
- Ochrana před CSRF – každý formulář obsahuje token ověřovaný na serveru
|
||||||
|
- Ochrana před brute force – blokování po opakovaných neúspěšných pokusech
|
||||||
|
- Ochrana před session fixation – `session_regenerate_id()` při přihlášení
|
||||||
|
- Ochrana před XSS – `htmlspecialchars()` na všech výstupech
|
||||||
|
- Remember me – bezpečný selector+token mechanismus (heslo ani ID není v cookie)
|
||||||
|
- Síla hesla – kontrola přes zxcvbn (JavaScript) + minimální délka (PHP)
|
||||||
|
- Celá DB v `utf8mb4` – plná podpora diakritiky a emoji
|
||||||
Reference in New Issue
Block a user