Laravel Sanctum: autentificare API securizată pentru SPA și mobile

Autentificarea API este o cerință fundamentală pentru aplicațiile moderne care expun endpoint-uri pentru SPA-uri (Single Page Applications) sau aplicații mobile. Laravel Sanctum oferă o soluție elegantă și ușor de implementat pentru ambele scenarii, eliminând complexitatea OAuth complet atunci când nu este necesar.

Acest ghid acoperă implementarea completă a autentificării cu Sanctum.

Ce este Laravel Sanctum și când îl folosești

Laravel Sanctum este un pachet de autentificare lightweight care suportă două mecanisme: token-uri API pentru aplicații mobile și SPA-uri externe, și autentificarea bazată pe sesiuni pentru SPA-uri first-party (care rulează pe același domeniu). Spre deosebire de Passport (care implementează OAuth 2.0 complet), Sanctum este simplu de configurat și suficient pentru majoritatea cazurilor de utilizare.

Dacă ești la început cu Laravel, citește mai întâi introducerea în Laravel și ghidul despre autentificarea în aplicații Laravel.

Token-uri API vs. autentificare bazată pe cookie

Pentru aplicații mobile sau SPA-uri care rulează pe domenii diferite, Sanctum generează token-uri opace stocate în baza de date. Utilizatorul se autentifică cu credențiale, primește un token și îl include în header-ul Authorization la fiecare request ulterior.

Pentru SPA-uri first-party (React, Vue etc. pe același domeniu), Sanctum folosește cookie-urile de sesiune Laravel standard. SPA-ul face un request la /sanctum/csrf-cookie pentru a obține cookie-ul CSRF, apoi se autentifică cu credențiale.

Toate request-urile ulterioare includ automat cookie-urile de sesiune și CSRF token-ul. Securizarea acestor mecanisme este esențială. Citește ghidul despre securizarea aplicațiilor PHP.

Instalarea și configurarea Sanctum

Sanctum este inclus implicit în Laravel 11+. Pentru versiunile mai vechi: composer require laravel/sanctum, urmat de publicarea configurației și migrarea tabelei personal_access_tokens.

În config/sanctum.php se configurează durata de expirare a token-urilor și domeniile de stat (stateful_domains) pentru autentificarea pe bază de cookie. Middleware-ul EnsureFrontendRequestsAreStateful trebuie adăugat în grupul api al route-urilor pentru autentificarea SPA.

Managementul dependențelor Laravel este simplificat de Composer. Citește ghidul nostru despre Composer.

Implementarea autentificării cu token-uri API

Token-urile API Sanctum sunt potrivite pentru aplicații mobile, CLI tools și integrări third-party care nu pot folosi cookie-uri de sesiune.

Generarea și gestionarea token-urilor

Modelul User trebuie să folosească trait-ul HasApiTokens. Generarea unui token se face cu $user->createToken('token-name'), care returnează un obiect NewAccessToken cu proprietatea plainTextToken pentru token-ul în text clar (afișat o singură dată utilizatorului).

Token-urile pot primi abilități (scopes) pentru controlul granular al accesului: $user->createToken('token-name', ['read', 'write']). Middleware-ul ability:read poate proteja endpoint-uri la nivel de abilitate.

Listarea, revocarea și expirarea token-urilor oferă control complet asupra sesiunilor active. Implementarea corectă a Eloquent facilitează gestionarea token-urilor. Citește ghidul nostru despre Eloquent ORM în Laravel.

Protejarea rutelor cu Sanctum

Rutele protejate folosesc middleware-ul auth:sanctum. Request-urile trebuie să includă header-ul Authorization: Bearer {token}.

Accesul la utilizatorul autentificat se face prin $request->user() sau helper-ul auth(). Structurarea rutelor API în grupuri cu prefix și middleware common este o practică recomandată pentru organizarea codului.

Rate limiting prin ThrottleRequests middleware previne abuzul API-ului. Logarea request-urilor la endpoint-urile sensibile adaugă un strat de audit de securitate.

Autentificarea SPA first-party

Pentru SPA-uri pe același domeniu, autentificarea bazată pe cookie Sanctum oferă securitate superioară token-urilor fără complexitate adăugată.

Configurarea CORS și domeniilor stateful

config/cors.php trebuie configurat pentru a permite request-uri de pe domeniul SPA-ului cu credențiale (credentials: true). Domeniile SPA trebuie adăugate în stateful_domains din config/sanctum.php.

SESSION_DOMAIN în .env trebuie setat pentru cookie-sharing între subdomenii dacă e cazul. Ordinea configurărilor este importantă: CORS trebuie configurat corect înainte ca orice alt lucru să funcționeze.

Testarea cu Postman sau curl ajută la diagnosticarea problemelor de CORS.

Implementarea în Vue.js/React

Fluxul de autentificare pentru SPA: 1) GET /sanctum/csrf-cookie (setează cookie-ul XSRF-TOKEN), 2) POST /login cu credențiale, 3) Toate request-urile ulterioare includ automat cookie-urile. Axios configurează automat CSRF token-ul din cookie pentru request-urile POST dacă este setat withCredentials: true.

Biblioteca @vueuse/integrations sau react-query pot gestiona starea autentificării și refresh-ul automat. Logout-ul trebuie să invalideze sesiunea pe server, nu doar să șteargă date locale.

Integrarea cu Vue este acoperită în ghidul nostru despre Vue.js.

Sanctum pentru aplicații mobile

Aplicațiile mobile (iOS, Android, React Native, Flutter) folosesc token-urile API Sanctum fără sesiuni cookie.

Managementul token-urilor pe dispozitive mobile

Token-urile trebuie stocate securizat pe dispozitiv: Keychain pe iOS, Keystore pe Android. Expirarea token-urilor și mecanismul de refresh (sau re-autentificare) trebuie gândit din start.

Sanctum nu are un mecanism built-in de refresh tokens ca OAuth, deci expirarea necesită re-autentificarea utilizatorului sau implementarea unui endpoint custom de refresh. Token-uri separate per dispozitiv permit revocarea accesului pentru un dispozitiv specific fără a afecta altele.

Testarea autentificării API

Laravel oferă helpers de testare pentru autentificarea Sanctum: Sanctum::actingAs($user, [‘read’]) simulează un utilizator autentificat cu abilități specifice în teste. Aceasta elimină dependența de token-uri reale în teste și simplifică testarea endpoint-urilor protejate.

Feature tests pentru fluxurile de autentificare (login, logout, acces cu token invalid, token expirat) sunt esențiale pentru robustețea API-ului. Backup-ul bazei de date cu token-urile active este important. Citește ghidul despre backup-ul site-ului.

Laravel Sanctum oferă echilibrul perfect între simplitate și funcționalitate pentru autentificarea API în aplicațiile moderne. Alegând între autentificarea pe bază de token sau pe bază de cookie în funcție de arhitectura aplicației și implementând corect mecanismele de securitate, poți construi API-uri sigure fără complexitatea unui server OAuth complet.