پرش به مطلب اصلی

احراز هویت

Authenticator هسته flowهای احراز هویت در access-hub است. اگر بخواهید جریان ورود، ثبت نام، OTP، انتخاب نقش، شخص حقیقی/حقوقی، یا فیلدهای داینامیک کاربر را کنترل کنید، معمولاً نقطه شروع شما همین کلاس است.

در پروژه های panel، flow پیش فرض احراز هویت از خود package وارد پروژه می‌شود و معمولاً بدون کدنویسی اضافه قابل استفاده است. در پروژه های API هم endpointهای آماده احراز هویت قرار است روی همین abstractionها اضافه شوند. این مستندات برای زمانی است که بخواهید از flow آماده عبور کنید و login، register، OTP یا role selection را خودتان پیاده کنید.

در عمل، این بخش دو لایه دارد:

  • متدهای flow محور روی Authenticator برای runtime
  • helperهای backend برای خواندن definitionها و configهای مرتبط
use Dornica\AccessHub\Authentication\Facades\Authenticator;

$user = Authenticator::user();

از کجا شروع کنیم؟​

اگر اولین بار است که با این بخش کار می‌کنید، این ترتیب معمولاً بهترین نتیجه را می‌دهد:

  1. تنظیمات پایه access-hub را در Access Hub بررسی کنید.
  2. فیلدهای ورود را در فیلدهای احراز هویت تعریف کنید.
  3. اگر فرم ثبت نام یا پروفایل شما فیلد تکمیلی دارد، Meta Fields را تعریف کنید.
  4. اگر پروژه OTP یا verification دارد، OTP و Verification را کامل کنید.
  5. در پایان، Session و Role و لاگ های امنیتی را بررسی کنید.

دو روش استفاده​

استفاده از Facade​

use Dornica\AccessHub\Authentication\Facades\Authenticator;

Authenticator::user();
Authenticator::id();

استفاده از helper​

authenticator()->user();
authenticator()->id();
اطلاع

برای flowهای runtime معمولاً Authenticator خواناتر است. برای definitionها و configهای کمکی، helperها انتخاب بهتری هستند.

نقشه کلی قابلیت ها​

بخشمسئولیت
Auth Fieldsتعریف این که کاربر با چه فیلدهایی وارد شود
Meta Fieldsتعریف فیلدهای تکمیلی داینامیک برای ثبت نام، ویرایش و نمایش کاربر
Authenticated Userدسترسی به کاربر فعلی و بررسی امکان ورود
OTP & Verificationارسال و تایید کدهای یکبار مصرف
Roles & Permissionsانتخاب و تغییر نقش فعال کاربر
Localizationمدیریت زبان و پرتال در سشن کاربر
Login Logsثبت ورود موفق، خروج و تلاش ناموفق

API پیشنهادی​

string|null Authenticator::authField()
string|null Authenticator::resolveAuthField(string $value)
bool        Authenticator::useAuthField(string $authField)
object      Authenticator::user(?object $user = null)
int|null    Authenticator::id()
bool        Authenticator::canLogin(object $user)
bool        Authenticator::isCurrentUserStatusActive()
void        Authenticator::sendLoginOtp()
bool        Authenticator::verifyLoginOtp(string $code)
array       Authenticator::resendLoginOtp()
void        Authenticator::logout()

array       authFieldNames()
array       authFieldDefinitions()
array       authFieldDefinition(string $authField, array $default = [])
array       registrationAuthFieldDefinitions()
array       passwordRecoveryAuthFieldDefinitions()
array       userMetaFieldGroups()
array       userMetaFields(?PersonType $personType = null)
array       authPasswordLength()
string      userActivationModel()

Authenticator::authField(): ?string​

فیلد auth فعال request جاری را برمی‌گرداند. اگر هنوز فیلدی تنظیم نشده باشد، اولین login field تعریف‌شده را به عنوان مقدار پیش فرض انتخاب می‌کند.

پارامتر:

  • ندارد

Authenticator::resolveAuthField(string $value): ?string​

مقدار خام ورودی را می‌گیرد و تشخیص می‌دهد باید با کدام auth field پردازش شود.

پارامترنوعتوضیح
valuestringمقدار خامی مثل 0912...، email@example.com یا 0012345678

Authenticator::useAuthField(string $authField): bool​

فیلد فعال را برای ادامه flow تنظیم می‌کند تا متدهایی مثل findUserByCredential() بدانند با کدام ستون کار کنند.

پارامترنوعتوضیح
authFieldstringنام field مثل mobile، email یا code

چک لیست پروژه جدید​

اگر در یک پروژه تازه می‌خواهید authentication سفارشی را راه بیندازید، این چک لیست معمولاً کافی است:

  1. کانفیگ dornica-access-hub.php را مرور کنید.
  2. userAuthFields() را در Service Provider تعریف کنید.
  3. اگر فرم تکمیلی دارید، userMetaFields() را هم تعریف کنید.
  4. اگر fieldهای option-based دارید، options را در componentAttributes() بگذارید.
  5. اگر field باید در صفحه show badge شود، از showAsBadge() و badgeVariant() استفاده کنید.
  6. اگر OTP دارید، authentication.otp و register_verification را کامل کنید.
  7. اگر custom controller یا endpoint نوشته‌اید، ثبت recordLogin()، recordFailedLogin() و recordLogout() را فراموش نکنید.

خطاهای رایج​

تعریف اشتباه auth field و meta field​

اگر فیلدی برای login لازم است، آن را meta field تعریف نکنید. در این حالت فرم ها ممکن است کار کنند، اما flow احراز هویت ناقص خواهد شد.

نبود options برای فیلدهای option-based​

اگر فیلدی مثل radio یا هر فیلد enum-like دارید ولی options تعریف نشده است، فرم می‌تواند ناقص یا نمایش خروجی انسانی در صفحه show ضعیف شود.

hardcode کردن منطق نمایش داخل Blade​

اگر برای هر فیلد مثل gender مستقیماً در view شرط بنویسید، مستند و توسعه‌پذیر نمی‌ماند. بهتر است نمایش را در خود UserMetaField تعریف کنید.

فراموش کردن person type​

در پروژه هایی که legal person فعال است، هر فیلد جدید را از نظر onlyReal() و onlyLegal() بررسی کنید؛ وگرنه فرم ثبت نام یا ویرایش کاربر ناسازگار می‌شود.

مسیر مطالعه​