احراز هویت و چرخهٔ حیات توکن‌ها

SDK آیدین از سازوکار امن مبادلهٔ توکن با اعتماد صفر (Zero-Trust) استفاده می‌کند. برنامه‌نویسان یک‌بار با شناسهٔ کاربری خود در Authentik احراز هویت کرده و SDK این توکن را با یک توکن موقت حساب سرویس Kubernetes که منحصراً به فضای نام پروژه محدود شده است مبادله می‌کند.

معماری احراز هویت

چرخهٔ کامل احراز هویت و اعطای دسترسی در سه مرحله اجرا می‌شود:

[برنامه‌نویس / ابزار خط فرمان]
       |
       |  ۱. توکن هویتی Authentik (تنها در حافظهٔ موقت رم)
       v
[مبدل توکن آیدین] (https://token-exchanger.<AIDIN_BASE_URL>)
       |
       |  ۲. بررسی هویت کاربر و تطبیق دسترسی عضویت در پروژه در RBAC کوبرنتیز
       |  ۳. درخواست صدور TokenRequest از API سرور کوبرنتیز (محدود به فضای نام پروژه)
       v
[سرور API کوبرنتیز]
       |
       |  ۴. بازگرداندن توکن موقت حساب سرویس + برچسب زمانی انقضا به فرمت RFC3339
       v
[مبدل توکن آیدین]
       |
       |  ۵. بازگرداندن دادهٔ ساخت‌یافته JSON شامل { token, namespace, expires_at }
       v
[کلاینت SDK آیدین]
       |
       |  ۶. ذخیره‌سازی امن در کش محلی (~/.aidin/<project>/token.json با سطح دسترسی 0600)
       v
[سرور پایپ‌لاین‌های آیدین] (https://pipeline-server.<AIDIN_BASE_URL>)

شرح گام‌به‌گام

۱. اعتبارسنجی اولیه: کاربر توکن Authentik را از طریق متغیر محیطی AUTHENTIK_TOKEN، ورودی استاندارد (--token-stdin) یا فلگ خط فرمان -t فراهم می‌کند. ۲. مبادلهٔ توکن: SDK توکن را از طریق TLS به آدرس https://token-exchanger.<AIDIN_BASE_URL>/exchange همراه با نام پروژه (project_name) ارسال می‌کند. ۳. تولید توکن درون کلاستر: مبدل توکن عضویت کاربر در گروه‌ها را بررسی کرده و از طریق رابط TokenRequest در Kubernetes، توکن موقت حساب سرویس (ServiceAccount) را برای فضای نام پروژه ایجاد می‌کند. ۴. بسته‌بندی مشخصات نشست: پاسخ دریافتی شامل موارد زیر است:

token: رشتهٔ JWT توکن حساب سرویس Kubernetes.
namespace: فضای نام متناظر با پروژهٔ آیدین.
expires_at: تایم‌استمپ انقضای توکن بر پایهٔ استاندارد دقیق ISO-8601 / RFC3339 UTC. ۵. ذخیره‌سازی ایمن محلی: SDK توکن دریافتی و متادیتای آن را در پوشهٔ کاربری سیستم ذخیره می‌کند.

اعتبارسنجی انقضا و مدیریت انحراف زمانی (Clock Skew)

بررسی اعتبار توکن‌ها در SDK آیدین از اصول امنیتی سخت‌گیرانه‌ای پیروی می‌کند:

حاشیهٔ انحراف زمانی

تأخیرهای شبکه یا ناهماهنگی ساعت سیستم میزبان ممکن است در حین ارسال درخواست باعث انقضای غیرمنتظرهٔ توکن شود. SDK یک حاشیهٔ امنیتی ۶۰ ثانیه‌ای اعمال می‌کند:

effective_expiration = expires_at - 60 seconds

در زمان بررسی توکن ذخیره‌شده، چنانچه رابطهٔ current_time + 60s >= expires_at برقرار باشد، توکن بلافاصله منقضی تلقی شده و از کاربر درخواست احراز هویت مجدد می‌شود.

عدم اتکا به بررسی سلامت (Health Check)

در نسخه‌های اولیه، بررسی اعتبار توکن‌ها گاه با فراخوانی مسیرهای عمومی مانند /health انجام می‌شد. در نسخهٔ 0.4.0:

[!CAUTION] نقاط پایانی بررسی سلامت (GET /health) مسیرهای عمومی بدون نیاز به اعتبارسنجی هستند و صحت دسترسی توکن‌ها را تأیید نمی‌کنند. SDK آیدین هرگز پاسخ موفقیت‌آمیز سلامت را دلیلی بر معتبر بودن توکن تلقی نمی‌کند. بررسی اعتبار صرفاً بر مبنای تایم‌استمپ رمزنگاری‌شدهٔ TokenRequest انجام می‌شود.

اگر توکن کش‌شده فاقد متادیتای معتبر expires_at باشد، بارگذاری نشده و خطای نیاز به احراز هویت مجدد صادر خواهد شد.

ضمانت‌های امنیتی و نحوهٔ ذخیره‌سازی محلی

اطلاعات محلی باید در برابر دسترسی سایر کاربران در سرورهای اشتراکی کاملاً محافظت شوند:

~/.aidin/
  ├── <project-a>/
  │   └── token.json   (سطح دسترسی: 0600 / -rw-------)
  └── <project-b>/
      └── token.json   (سطح دسترسی: 0600 / -rw-------)

۱. عدم نگهداری توکن‌های بالادستی روی دیسک

توکن‌های ورود Authentik هرگز روی دیسک ذخیره نمی‌شوند. این مقادیر فقط در حافظهٔ پروسه (RAM) موقتاً نگهداری شده و پس از اتمام مبادله پاکسازی می‌شوند.

۲. بررسی مجوزهای دسترسی POSIX

مجوز پوشه: پوشه‌های کش با سطح دسترسی 0700 (drwx------) ایجاد می‌شوند.
مجوز فایل: فایل ذخیرهٔ توکن (token.json) با سطح دسترسی 0600 (-rw-------) نوشته می‌شود.
بررسی در زمان خواندن: در صورتی که فایل توکن دارای مجوز خواندن یا نوشتن برای گروه یا سایر کاربران باشد (mode & 0o077 != 0)، SDK از خواندن آن خودداری کرده و خطای CredentialStorageError برمی‌گرداند.

۳. محافظت در برابر پیوندهای نمادین (Symlinks)

سامانهٔ بارگذاری اعتبارات صراحتاً عدم استفاده از پیوند نمادین (Symlink) را برای مسیر فایل بررسی می‌کند تا از حملات خواندن فایل‌های حساس جلوگیری شود.

۴. نوشتن اتمیک فایل‌ها

عملیات ذخیره‌سازی از طریق ایجاد فایل موقت (tempfile.NamedTemporaryFile) در همان پوشه و تغییر نام اتمیک با os.replace انجام می‌شود تا از تداخل پروسه‌ها یا ناقص ماندن محتوا جلوگیری گردد.

۵. نشانهٔ هویت (Identity Hint)

برای جلوگیری از استفادهٔ اشتباهی توکن در زمان تعویض حساب کاربری روی یک پروژهٔ یکسان، یک شناسهٔ هش (identity_hint - ۱۶ نویسهٔ نخست هش SHA-256 توکن بالادستی) در کش ذخیره می‌شود و در صورت عدم تطابق با توکن جدید، کش قبلی باطل خواهد شد.

ساختار دادهٔ فایل کش

فایل JSON ذخیره‌شده در مسیر ~/.aidin/<project>/token.json ساختار زیر را دارد:

{
  "version": 2,
  "token_type": "kubernetes-service-account",
  "project_name": "marketing-analytics",
  "namespace": "marketing-analytics",
  "exchanger_url": "https://token-exchanger.platform.aidin-ai.com",
  "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "expires_at": "2026-11-09T09:45:00+00:00",
  "obtained_at": "2026-11-09T08:45:00+00:00",
  "identity_hint": "9f83c6b12a87c4d5"
}

خروج از حساب کاربری (Logout)

برای پاکسازی اطلاعات نشست محلی مربوط به یک پروژه:

aidin logout -p my-project

نکات ابطال توکن

اجرای دستور aidin logout بلافاصله فایل token.json و کش‌های قدیمی را از سیستم محلی حذف می‌کند.
از آنجا که توکن‌های حساب سرویس Kubernetes به شکل JWT بی‌وضعیت هستند، توکن‌های قبلی صادرشده تا فرا رسیدن زمان انقضای خود (expires_at) درون کلاستر به فعالیت ادامه می‌دهند مگر اینکه از طریق مدیران پلتفرم باطل شوند.
جهت تجدید توکن پیش از انقضا، می‌توانید از فلگ --force-refresh در دستور aidin login استفاده کنید.

گام‌های بعدی

مشاهدهٔ تمام دستورات و پارامترها در مرجع ابزار خط فرمان.
نحوهٔ استفاده از ProjectClient در مرجع API پایتون.