احراز هویت و نگهداری کلید

کلید API چیست، کجا باید بماند و کجا نه؛ کلید را از محیط بخوان، برای هر کار کلید جدا با کمترین اختیار بگیر و بدان وقتی نشت کرد چه کنی.

بعد از این درس می‌توانی

  • تفاوت کلید API، توکن Bearer و ورود با OAuth را در یک جمله برای هرکدام توضیح بدهد.
  • جاهای درست (Credential ابزار، مدیر راز، متغیر محیطی) و نادرست (کد، Git، نشانی، لاگ، سند مشترک، گفتگو با هوش مصنوعی) نگهداری کلید را تشخیص بدهد.
  • برای چند ورک‌فلو کلیدهای جدا با کمترین اختیار طراحی کند.
  • پس از نشت کلید، گام‌های درست (باطل‌کردن و ساختن کلید تازه، پیدا کردن محل‌های استفاده، بررسی سوءاستفاده) را به ترتیب بنویسد.

چرا این درس مهم است

کارمند فنی برگ سبز برای راحتی، کلید مدیر سامانه سفارش را در سند مشترک تیم نوشت و همان را در سه ورک‌فلو گذاشت. شش ماه بعد او رفته بود، کلید هنوز کار می‌کرد، و هیچ‌کس نمی‌دانست در چند جا استفاده شده و چه کسانی آن سند را دیده‌اند. کلیدی که می‌توانست سفارش‌ها را بخواند، تغییر بدهد و حذف کند، عملاً در اختیار هر کسی بود که روزی به آن سند دسترسی داشت.

هر ورک‌فلوی واقعی دست‌کم یک کلید دارد. کلید یعنی اجازه: هر کس آن را داشته باشد، از نظر سرویس، تو است. این درس درباره این است که کلید کجا بماند، چقدر اختیار داشته باشد، و وقتی نشت کرد (که دیر یا زود پیش می‌آید) چه کنی.

مفاهیم کلیدی

یادآوری: «حداقل دسترسی» و «شعاع اثر» را در دوره پایه دیدی؛ اینجا آن‌ها را روی کلید API پیاده می‌کنی.

  • API Key (کلید API): رشته‌ای که سرویس به تو می‌دهد تا درخواست‌هایت را به حساب تو بشناسد؛ معمولاً تا وقتی باطل نشود معتبر است.
  • Bearer Token (توکن Bearer): کلیدی که در هدر Authorization: Bearer ... فرستاده می‌شود؛ هر کس آن را «حمل» کند، پذیرفته می‌شود.
  • OAuth (اوآث): روشی که کاربر بدون دادن رمزش به تو، در صفحه خود سرویس اجازه محدودی به برنامه تو می‌دهد.
  • Secret (راز): هر مقداری که با داشتنش می‌شود به جای تو کاری کرد: کلید، توکن، رمز، کلید امضای Webhook.
  • Key Rotation (چرخش کلید): جایگزین‌کردن منظم کلید با کلید تازه و باطل‌کردن کلید قبلی.
  • Environment Variable (متغیر محیطی): مقداری که بیرون از کد در محیط اجرای برنامه تنظیم می‌شود و برنامه هنگام اجرا آن را می‌خواند.

مدل ذهنی

کلید API را مثل کلید فیزیکی یک انبار ببین. هر کس کلید را داشته باشد در را باز می‌کند؛ قفل نمی‌پرسد کیستی. پس: کلید را روی در یا در دفترچه عمومی نمی‌گذاری؛ برای کسی که فقط باید موجودی را ببیند، کلید اتاق مدیر نمی‌سازی؛ و وقتی کسی کلید را گم کرد، قفل را عوض می‌کنی، نه اینکه فقط دنبال کلید بگردی.

جای درست و نادرست نگهداری کلید: کلید در Credential ابزار یا مدیر راز نگهداری می‌شود، هنگام اجرا به ورک‌فلو داده می‌شود و فقط در هدر درخواست به API می‌رود؛ کد، Git، نشانی درخواست، لاگ، سند مشترک و گفتگو با هوش مصنوعی جای کلید نیستند.

جای درست و نادرست نگهداری کلید

این تشبیه کجا غلط است؟ کلید فیزیکی را اگر کسی کپی کند، معمولاً می‌فهمی که گم شده است. کلید دیجیتال بی‌صدا کپی می‌شود: نسخه اصلی سر جایش است و هیچ نشانه‌ای از کپی نیست. برای همین فرض درست این است که هر کلیدی که جای نادرست دیده شده، نشت کرده است، حتی اگر بعداً پاکش کرده باشی.

گام‌به‌گام

گام ۱: سه شکل رایج احراز هویت

شکلچطور کار می‌کندکجا می‌بینی
کلید APIسرویس یک رشته ثابت می‌دهد؛ آن را در هر درخواست می‌فرستی (معمولاً در هدر)API مدل‌ها، سرویس‌های پیامک و ایمیل
توکن Bearerهمان کلید یا توکنی موقت در هدر Authorization: Bearer ...بیشتر API‌های امروزی، API آزمایشی برگ سبز
OAuthکاربر در صفحه خود سرویس (مثلاً حساب ایمیل) اجازه محدود می‌دهد؛ ابزار توکنی موقت می‌گیرد و خودش تازه‌اش می‌کنداتصال n8n به ایمیل، تقویم و صفحه‌گسترده حساب‌های کاربری

یادت باشد HTTP بی‌حالت است و سرور میان درخواست‌ها چیزی از تو به خاطر نمی‌سپاردsrc-mdn-http؛ پس کلید در هر درخواست می‌رود و هر جا که درخواست ثبت شود، کلید هم ممکن است ثبت شود.

گام ۲: جای کلید

راهنمای مدیریت راز OWASP یکی از مشکلات اصلی سازمان‌ها را نگه‌داشتن راز به‌صورت متن ساده در کد و فایل‌های پیکربندی می‌داند و توصیه می‌کند راز هرگز به‌صورت متن ساده در لاگ نوشته نشودsrc-owasp-secrets-cheatsheet.

جادرست؟چرا
Credential داخلی ابزار (مثل n8n)بلهرمزگذاری‌شده نگه داشته می‌شود و در خروجی ورک‌فلو نمی‌آید
مدیر راز (Secret Manager)بله، برای تیم و سروردسترسی، ثبت دسترسی و چرخش مدیریت می‌شود
متغیر محیطیقابل قبول برای کار کوچکOWASP آن را آخرین گزینه می‌داند، چون برای همه پردازه‌ها قابل دسترسی است و ممکن است در لاگ یا گزارش خرابی برودsrc-owasp-secrets-cheatsheet
کد و Gitخیرتاریخچه Git کلید را حتی پس از حذف نگه می‌دارد
نشانی درخواست (?api_key=)خیرنشانی‌ها در لاگ سرورها و تاریخچه ثبت می‌شوند
لاگخیرلاگ‌ها دسترسی گسترده‌تر و نگهداری طولانی‌تر دارند
سند مشترک، پیام، گفتگو با هوش مصنوعیخیراز کنترل تو خارج می‌شود

گام ۳: یک کلید برای هر کار، با کمترین اختیار

به‌جای یک کلید مدیر برای همه:

ورک‌فلوکلیداختیار
پاسخ «سفارشم کجاست؟»کلید ۱فقط خواندن سفارش
ثبت تیکتکلید ۲فقط ساختن تیکت
گزارش هفتگیکلید ۳فقط خواندن سفارش و تیکت

اگر سرویس اختیار جزئی نمی‌دهد، دست‌کم کلید جدا برای هر ورک‌فلو بگیر تا وقتی یکی نشت کرد، بقیه کار کنند و بدانی کدام را عوض کنی. OWASP هم دسترسی به هر راز را به حداقل لازم برای هر سرویس محدود می‌کندsrc-owasp-secrets-cheatsheet.

گام ۴: صاحب، فهرست و چرخش

برای هر کلید ثبت کن: صاحب (یک نقش)، کجا استفاده شده، چه اختیاری دارد، کی ساخته شده و کی باید عوض شود. OWASP چرخش منظم را توصیه می‌کند تا کلید دزدیده‌شده عمر کوتاهی داشته باشد، و یادآوری می‌کند که راه‌اندازی دوباره برنامه، کلید دزدیده‌شده را باطل نمی‌کندsrc-owasp-secrets-cheatsheet.

گام ۵: وقتی کلید نشت کرد

ترتیب مهم است:

  1. باطل کن و کلید تازه بساز در پنل سرویس. این اول است؛ پاک‌کردن کلید از سند یا Git کافی نیست.
  2. همه محل‌های استفاده را با کلید تازه به‌روز کن (فهرست گام ۴ اینجا به کار می‌آید).
  3. بررسی سوءاستفاده: گزارش مصرف یا لاگ دسترسی سرویس را برای بازه نشت ببین.
  4. علت را ببند: چرا کلید آنجا بود؟ (مثلاً .env در .gitignore نبود.)

مثال‌ها

پیاده‌سازی عملی

شکار نشت و طرح کلیدها. حدود ۲۰ دقیقه.

  1. assets/leak-hunt.md را بخوان. برای شش مورد، ایراد، خطر و اصلاح را بنویس؛ بعد پاسخ‌های پایین فایل را ببین.
  2. برای سه ورک‌فلوی برگ سبز (پاسخ سفارش، ثبت تیکت، گزارش هفتگی) جدول کلیدها را با اختیار، صاحب و محل نگهداری بنویس.
  3. assets/env.example را ببین: چرا فقط جای خالی دارد و چرا .env واقعی نباید وارد Git شود؟
اجرای محلی

API آزمایشی (shared/barg-sabz-mock-api.py) کلیدش را از متغیر محیطی MOCK_API_TOKEN می‌خواند. یک مقدار دلخواه بساز و هم سرور و هم کلاینت را با آن اجرا کن تا ببینی کلید هیچ‌جای کد نیست:

export MOCK_API_TOKEN=my-local-test-value
python barg-sabz-mock-api.py

در پنجره دیگر:

export ORDERS_API_TOKEN=my-local-test-value
python call_with_env_token.py BS-1001

در PowerShell به‌جای export بنویس $env:MOCK_API_TOKEN = "my-local-test-value". حالا مقدار سمت کلاینت را عوض کن و دوباره اجرا کن: 401. اسکریپت assets/call_with_env_token.py در خطا فقط کد وضعیت و کد خطا را چاپ می‌کند، نه هدرها.

بدون اجرا / شبیه‌ساز

بدون اجرا: کد assets/call_with_env_token.py را بخوان و سه جا را نشان بده که از نشت کلید جلوگیری می‌کند (خواندن از محیط، فرستادن در هدر نه نشانی، چاپ‌نکردن هدرها در خطا).

اشتباه‌های رایج

اشتباهنتیجهکار درست
یک کلید مدیر برای همه ورک‌فلوهانشت یکی، نشت همهکلید جدا با کمترین اختیار
حذف کلید از کد به‌جای باطل‌کردنکلید در تاریخچه و نسخه‌های دیگران زنده استاول باطل کن، بعد پاک
کلید در نشانی درخواستدر لاگ‌ها و تاریخچه ثبت می‌شودفقط در هدر
لاگ‌کردن کل درخواست برای اشکال‌زداییکلید و داده شخصی در لاگفقط روش، مسیر، کد و شناسه
چسباندن خطای کامل در گفتگو با هوش مصنوعیکلید به سرویس بیرونی می‌رودپیش از چسباندن *** بگذار
کلید بی‌صاحب و بی‌تاریخهیچ‌کس نمی‌داند کجا استفاده شدهفهرست کلیدها با صاحب و محل

اشکال‌زدایی

ورک‌فلویی که دیروز کار می‌کرد، امروز در همه درخواست‌ها 401 می‌گیرد.

کلید باطل، منقضی یا چرخانده شده و ورک‌فلو هنوز کلید قبلی را دارد.

در پنل سرویس وضعیت کلید را ببین؛ فهرست کلیدها را برای تاریخ چرخش بررسی کن.

Credential را با کلید تازه به‌روز کن؛ اگر چرخش برنامه‌ریزی‌شده بود، همه محل‌های استفاده را از فهرست پیدا کن.

درخواست 403 می‌گیرد، نه 401.

کلید معتبر است ولی اختیار آن کار را ندارد؛ مثلاً کلید فقط‌خواندنی برای ساختن تیکت.

اختیار کلید را در پنل سرویس با کار گره مقایسه کن.

کلید درست برای آن کار را بگذار؛ اختیار کلید فقط‌خواندنی را برای «راحتی» بالا نبر.

اسکریپت می‌گوید متغیر محیطی تنظیم نشده، در حالی که تنظیمش کرده‌ای.

متغیر در پنجره دیگری تنظیم شده؛ متغیر محیطی فقط برای همان پنجره و برنامه‌هایی است که از آن اجرا می‌شوند.

در همان پنجره‌ای که اسکریپت را اجرا می‌کنی، وجود متغیر را بررسی کن (بدون چاپ مقدارش).

متغیر را در همان پنجره تنظیم کن یا از فایل .env بارگذاری کن.

نکته‌های امنیتی

تمرین کوتاه

تمرین · 10 دقیقه

هدف: ترتیب درست پس از نشت.

گام‌ها: کلید سرویس پیامک برگ سبز در گروهی با ۴۰ عضو فرستاده شد و ده دقیقه بعد پیام پاک شد. این کارها را به ترتیب درست مرتب کن و یکی را که لازم نیست حذف کن: (الف) به‌روزرسانی Credential ورک‌فلوها با کلید تازه؛ (ب) باطل‌کردن کلید و ساختن کلید تازه؛ (ج) پرسیدن از اعضای گروه که آیا کلید را کپی کرده‌اند؛ (د) بررسی گزارش مصرف سرویس پیامک از زمان ارسال؛ (ه) ثبت علت و قاعده تازه.

معیار پذیرش: ب، الف، د، ه؛ و «ج» به‌عنوان غیرضروری (پاسخ آن هیچ تصمیمی را عوض نمی‌کند).

راه‌حل نمونه

ب ← الف ← د ← ه. «ج» کمکی نمی‌کند: کلید باید در هر حال باطل شود و پاسخ اعضا قابل اثبات نیست. پاک‌شدن پیام هم چیزی را عوض نمی‌کند؛ ده دقیقه برای کپی کافی است.

چالش

تمرین · 30 دقیقه

موقعیت: ابزارها و سرویس‌هایی که در کار خودت (یا در طرح خودکارسازی درس آخر دوره پایه) به هم وصل می‌شوند، کلید دارند. برایشان «دفتر کلید» بساز. مقدار هیچ کلید واقعی را ننویس؛ اگر نام سرویس‌ها حساس است، نام ساختگی یا ناشناس بگذار.

  1. برای هر کلید: سرویس، کار، اختیار فعلی، اختیار لازم، صاحب، محل نگهداری، محل‌های استفاده، تاریخ ساخت و تاریخ چرخش بعدی.
  2. هر کلیدی که اختیارش بیش از لازم است یا در جای نادرست است، علامت بزن و اصلاح بنویس.
  3. یک «برنامه نشت» یک‌صفحه‌ای برای مهم‌ترین کلید بنویس: چه کسی، چه گام‌هایی، به چه ترتیبی.

خروجی مورد انتظار: دفتر کلید با دست‌کم سه ردیف (یا همه کلیدهایت اگر کمترند)، فهرست اصلاح‌ها و برنامه نشت.

معیار پذیرش:

  • هیچ مقدار کلید واقعی در دفتر نیست.
  • هر کلید صاحب و محل نگهداری درست دارد، یا اصلاحش نوشته شده است.
  • دست‌کم یک مورد کاهش اختیار یا جداسازی کلید پیشنهاد شده است.
  • برنامه نشت با باطل‌کردن و ساختن کلید تازه شروع می‌شود.

پرسش‌های سنجش

جمع‌بندی

  • کلید یعنی اجازه: هر کس آن را دارد، از نظر سرویس تو است.
  • جای کلید: Credential ابزار یا مدیر راز؛ متغیر محیطی آخرین گزینه. جای کلید نیست: کد، Git، نشانی، لاگ، سند مشترک، گفتگو با هوش مصنوعی.
  • یک کلید برای هر کار با کمترین اختیار؛ 401 یعنی کلید نامعتبر، 403 یعنی اختیار کافی نیست.
  • هر کلید صاحب، فهرست محل استفاده و تاریخ چرخش دارد.
  • پس از نشت: اول باطل و کلید تازه، بعد به‌روزرسانی محل‌ها، بررسی سوءاستفاده و بستن علت.

پرسش‌های سنجش

برگ سبز سه اتصال دارد: (الف) API مدل زبانی برای طبقه‌بندی پیام؛ (ب) دسترسی n8n به صندوق ایمیل یک کارمند؛ (ج) API آزمایشی سفارش. برای هرکدام بگو احتمالاً کدام شکل احراز هویت به کار می‌رود و چرا.

پاسخ نمونه و معیار ارزیابی

(الف) کلید API در هدر (اغلب به‌شکل Bearer)، چون حساب سازمانی سرویس است. (ب) OAuth، چون کاربر باید در صفحه خود سرویس ایمیل اجازه محدود بدهد بی‌آنکه رمزش را به n8n بدهد. (ج) توکن Bearer در هدر Authorization، طبق مستندات API آزمایشی.

  • OAuth را برای حساب کاربری ایمیل می‌داند (1 امتیاز)
  • کلید یا Bearer را برای API سرویس می‌داند (1 امتیاز)
  • دلیل OAuth را ندادن رمز کاربر می‌داند (1 امتیاز)
  • رمز ایمیل کارمند را در n8n بگذار ← رمز کاربر هرگز نباید به ابزار داده شود؛ OAuth برای همین است.

این خط در لاگ یک ورک‌فلو دیده شده است. چند ایراد دارد و هرکدام را چطور اصلاح می‌کنی؟

لاگ ساختگی؛ کلید نمایشی است.

2026-10-14 09:00 GET https://orders.barg-sabz.example.com/orders/BS-1001?api_key=FAKE-ADMIN-7Q2X -> 200 body={"customer_phone":"0912xxxxxxx", ...}
پاسخ نمونه و معیار ارزیابی

سه ایراد: (۱) کلید در نشانی درخواست؛ باید در هدر Authorization برود. (۲) کلید در لاگ؛ لاگ نباید هدر یا نشانی با کلید را ثبت کند؛ و چون دیده شده، کلید باید باطل و عوض شود. (۳) بدنه پاسخ با داده شخصی مشتری در لاگ؛ فقط کد وضعیت و شناسه ثبت شود. همچنین نام کلید (ADMIN) نشان می‌دهد اختیارش بیش از لازم است.

  • کلید در نشانی (1 امتیاز)
  • کلید در لاگ و لزوم عوض‌کردنش (1 امتیاز)
  • داده شخصی در لاگ (1 امتیاز)
  • فقط لاگ را پاک کن ← کلیدی که در لاگ دیده شده، نشت کرده است؛ باید باطل شود.

برای سه ورک‌فلو جدول کلید بنویس: (۱) ربات پیام‌رسان که وضعیت سفارش را می‌گوید؛ (۲) ورک‌فلویی که سفارش‌های لغوشده را بایگانی (حذف از فهرست فعال) می‌کند؛ (۳) گزارش ماهانه فروش. ستون‌ها: کلید، اختیار، صاحب.

پاسخ نمونه و معیار ارزیابی

(۱) کلید جدا، فقط خواندن سفارش، صاحب: مسئول پشتیبانی. (۲) کلید جدا، خواندن و بایگانی فقط سفارش‌های لغوشده (یا حذف، اگر سرویس اختیار جزئی‌تر نمی‌دهد، با تأیید انسانی)، صاحب: مسئول عملیات. (۳) کلید جدا، فقط خواندن سفارش، صاحب: مسئول مالی. هیچ‌کدام کلید مدیر نیست.

  • سه کلید جدا (1 امتیاز)
  • فقط‌خواندن برای ۱ و ۳ (1 امتیاز)
  • اختیار محدود و احتیاط برای ۲ (1 امتیاز)
  • یک کلید برای هر سه ← نشت ربات پیام‌رسان یعنی دسترسی حذف برای مهاجم.

کلید API در کامیتی وارد مخزن Git شد و کامیت بعدی آن را حذف کرد. اولین کار درست کدام است؟

  • بازنویسی تاریخچه Git تا کلید از همه کامیت‌ها پاک شود.
  • باطل‌کردن کلید در پنل سرویس و ساختن کلید تازه.
  • کاری لازم نیست؛ کامیت بعدی آن را حذف کرده است.
  • خصوصی‌کردن مخزن.
پاسخ نمونه و معیار ارزیابی
  • a ← بازنویسی، نسخه‌هایی را که دیگران قبلاً گرفته‌اند پاک نمی‌کند؛ کار دوم است، نه اول.
  • c ← تاریخچه Git کلید را نگه می‌دارد.
  • d ← کسانی که قبلاً دیده‌اند هنوز کلید را دارند.

همکارت می‌گوید: «متغیر محیطی امن است، پس کلید را همان‌جا بگذاریم و تمام.» برای یک ورک‌فلوی تیمی روی سرور مشترک، با این حرف موافقی؟ دلیل و پیشنهادت را بنویس.

پاسخ نمونه و معیار ارزیابی

تا حدی. متغیر محیطی از کد و Git بهتر است، ولی OWASP آن را آخرین گزینه می‌داند: برای پردازه‌های دیگر قابل دسترسی است و ممکن است در لاگ یا گزارش خرابی برود. برای تیم و سرور مشترک، Credential داخلی ابزار یا مدیر راز با کنترل دسترسی، ثبت دسترسی و چرخش بهتر است. برای کار کوچک شخصی، متغیر محیطی قابل قبول است.

  • متغیر محیطی را بهتر از کد ولی نه کامل می‌داند (1 امتیاز)
  • یک خطر مشخص متغیر محیطی را می‌گوید (1 امتیاز)
  • Credential ابزار یا مدیر راز را برای تیم پیشنهاد می‌کند (1 امتیاز)
  • کاملاً امن است ← متغیر محیطی ممکن است در لاگ و گزارش خرابی دیده شود.

فایل‌های درس

API آزمایشی محلی با داده ساختگی

barg-sabz-mock-api.py

شش نمونه نشت کلید با پاسخ

leak-hunt.md

نمونه فایل پیکربندی بدون راز

env.example

فراخوانی API با کلید خوانده‌شده از محیط

call_with_env_token.py

ابزارها و جایگزین‌ها

  • ویرایشگر متن — بررسی نمونه‌ها و نوشتن طرح کلیدها

منابع

HTTP: Hypertext Transfer Protocol MDN Web Docs (Mozilla) living doc, accessed 2026-10-16

Secrets Management Cheat Sheet OWASP Cheat Sheet Series living doc, accessed 2026-10-16

دوره

زبان مشترک نرم‌افزارها: HTTP، JSON و API