Autentifikazioa (Auth) — Errezetak eta Praktika Onenak

Osumi Framework-en autentifikazioa normalean honako hauek erabiliz ezartzen da:

• Erabiltzailearen kredentzialak balioztatzen dituen eta token bat jaulkitzen duen Saioa hasteko amaiera-puntu bat
• Babestutako ibilbide guztietan tokena balioztatzen duen iragazki bat (adibidez, LoginFilter)
• Sarrerako autentifikazio-datuak modu seguruan prozesatzeko DTOak
• Autentifikazio-logika berrerabilgarria eta garbia mantentzeko Zerbitzuak
• Osagaiak exekutatu aurretik autentifikazio-iragazkiak aplikatzeko konfiguratutako Ibilbideak

Dokumentu honek autentifikazio-fluxu oso bat ezartzeko errezeta praktikoak eskaintzen ditu.

1. Ibilbideak Iragazkiak Erabiliz Babestea

Amaiera-puntuak babesteko metodo ohikoena ibilbidearen definizioari iragazki bat gehitzea da.

Zure bideratze-sistemaren arabera, iragazkiak honela zehaztu daitezke:

ORoute::post('/profile', ProfileComponent::class, [LoginFilter::class]);

Ibilbidea atzitzen denean:

1. Bideratzaileak amaiera-puntua identifikatzen du
2. Osagaia exekutatu aurretik, iragazki-katea exekutatzen da
3. Iragazkiren batek "status" !== "ok" itzultzen badu, eskaerak ez du inoiz osagaira iristen, 403 Debekatuta itzuliz edo "return" ezarrita badago birbideratuz

Horrek ziurtatzen du autentifikatutako erabiltzaileek bakarrik iristen direla babestutako logikara.

2. Saioa Hasteko Iragazkia Sortzea

Iragazki batek honelako itxura du:

class LoginFilter {
  public static function handle(array $params, array $headers): array {
    global $core;
    $ret = ['status' => 'error', 'id' => null];

    $tk = new OToken($core->config->getExtra('secret'));

    if ($tk->checkToken($headers['Authorization'])) {
        $ret['status'] = 'ok';
        $ret['id'] = intval($tk->getParam('id'));
    }

    return $ret;
  }
}

Iragazki honek:

• Authorization goiburua irakurtzen du
• Token bat balioztatzen du
• Baliozkoa bada → "status" => "ok" eta autentifikatutako erabiltzaile IDa itzultzen ditu
• Baliogabezkoa bada → "error" itzultzen du eta eskaera gelditzen du

Tokenetik eratorritako balioak (id bezala) geroago osagaiek edo DTOek kontsumi ditzakete.

3. Saioa Hasteko Amaierako Puntua Sortzea (Tokenak Jaulkitzea):

1. Kredentzialak DTO baten bidez jasotzen ditu
2. Zerbitzu bat erabiliz baliozkotzen ditu
3. Token bat sortzen du
4. Tokena bezeroari itzultzen dio
5. Bezeroak tokena gordetzen du eta Authorization goiburuan erabiltzen du

Egitura Adibidea

Saioa Hasteko DTO:

class LoginDTO extends ODTO {
  #[ODTOField(required: true)]
  public ?string $email = null;

  #[ODTOField(required: true)]
  public ?string $password = null;
}

AuthService logika kudeatzen du:

class AuthService extends OService {
  public function login(string $email, string $password): ?array {
    $user = User::findOne(['email' => $email]);
    if (!$user || !password_verify($password, $user->password)) {
      return null;
    }
    $token = new OToken($this->getConfig()->getExtra('secret'));
    $token->addParam('id', $user->id);
    return ['token' => $token->getToken()];
  }
}

LoginComponent:

class LoginComponent extends OComponent {
  private ?AuthService $auth = null;
  public ?string $token = null;
  public string $status = 'error';

  public function __construct() {
    parent::__construct();
    $this->auth = inject(AuthService::class);
  }

  public function run(LoginDTO $dto): void {
    if (!$dto->isValid()) {
      return;
    }

    $data = $this->auth->login($dto->email, $dto->password);

    if ($data) {
      $this->status = 'ok';
      $this->token = $data['token'];
    }
  }
}

Bezeroak orain tokena sartzen du ondorengo eskaera guztietan:

Baimena: <token>

4. Iragazki Irteera Erabiltzea Osagaienetan

Iragazkiak gainditu ondoren, eskaera objektuak iragazki emaitzak ditu:

$filter = $req->getFilter('Login');

Normalean hau egingo zenuke:

$userId = $filter['id']; // autentifikatutako erabiltzailea

Ondoren, IDa zerbitzuei pasa diezaiekezu, ereduak kargatu eta negozio logika modu seguruan egin.

5. Iragazki Datuak Erabiltzea DTOen Barruan

DTOek automatikoki jaso ditzakete balioak iragazkietatik:

#[ODTOField(filter: 'Login', filterProperty: 'id')]
public ?int $idUser = null;

Horrek esan nahi du:

• Erabiltzaileek ezin dute beren identitatea faltsutu
• DTOek autentifikatutako erabiltzaile IDa modu seguruan jasotzen dute
• Osagaiek ez dute iragazki datuak eskuz irakurri beharrik

Honek asko errazten ditu autentifikazioaren menpeko amaiera-puntuak.

6. Errezeta: Babestutako amaiera-puntu bat sortzea

Adibidea: “Lortu nire zinemak”

Ibilbidea

ORoute::get('/nire-zinemak', GetCinemasComponent::class, [LoginFilter::class]);

Osagaia

class GetCinemasComponent extends OComponent {
  private ?CinemaService $cs = null;
  public string $status = 'ok';
  public ?CinemaListComponent $list = null;

  public function __construct() {
    parent::__construct();
    $this->cs = inject(CinemaService::class);
    $this->list = new CinemaListComponent();
  }

  public function run(ORequest $req): void {
    $filter = $req->getFilter('Login');

    if (!$filter || !array_key_exists('id', $filter)) {
      $this->status = 'error';
      return;
    }

    $this->list->list = $this->cs->getCinemas($filter['id']);
  }
}

7. Errezeta: Baimenak Betearaztea

Zure iragazkia zabaldu dezakezu tokenetik rol/baimen informazioa sartzeko:

$ret['role'] = $tk->getParam('role');

Ondoren, osagaietan:

$filter = $req->getFilter('Login');
if ($filter['role'] !== 'admin') {
  $this->status = 'forbidden';
  return;
}

8. Errezeta: Saioa ixtea

Zure autentifikazio sistema tokenetan oinarrituta eta egoerarik gabekoa denez:

• "Saioa ixtea" bezero aldeko tokena ezabatzea besterik ez da
• Aukeran, token zerrenda beltza inplementa dezakezu cachea erabiliz:
  • Markatu tokena baliogabetzat getCacheContainer()-n
  • Iragazki bidez egiaztatu zerrenda beltzean dauden tokenak

9. Praktika onenak

• Erabili DTOak saioa hasteko eskaeretarako
• Ez fidatu inoiz bezeroak emandako erabiltzaile IDetan — lortu beti IDak iragazkietatik
• Mantendu iragazkiak txikiak (balioztatzeko soilik)
• Jarri negozio logika zerbitzuetan
• Erabili sekretu sendoak tokenetarako (gorde konfigurazioan)
• Zatitu logika garbi:
  • Iragazkiak → autentifikazioa / egiaztapena
  • DTOak → sarreraren balidazioa
  • Zerbitzuak → logika
  • Osagaiak → orkestrazioa eta erantzuna

10. Laburpena

Osumi Framework-en autentifikazio lan-fluxu oso bat normalean Honako hauek barne hartzen ditu:

1. Saioa hasteko amaierako puntua tokenak jaulkitzea
2. LoginFilter tokenak balioztatzea bide babestuetarako
3. DTOak sarrera jasotzea eta balioztatzea
4. Zerbitzuak autentifikazio logika burutzea
5. Bideratzea iragazkiak osagaien aurretik aplikatzea
6. Autentifikatutako erabiltzaileen informazioaren hedapen segurua iragazkien eta DTOen bidez

Arkitektura honek honako hau bermatzen du:

• Ardurak garbi bereiztea
• Amaiera-puntuen artean berrerabiltzea erraza
• Segurtasun berme sendoak
• Eskaera-hodi sinple eta aurreikusgarria