امنیت API؛ راهنمای اتصال ایمن، توکن و کنترل دسترسی

امنیت API چیست و چرا HTTPS به‌تنهایی کافی نیست؟

API قراردادی برای تبادل داده و اجرای عملیات میان برنامه‌هاست. امنیت آن یعنی محرمانگی ارتباط، تشخیص هویت، کنترل دسترسی، اعتبارسنجی داده و مدیریت سوءاستفاده در کنار هم کار کنند. ممکن است پاسخ از یک نشانی HTTPS دریافت شود، اما همان API اطلاعات کاربر دیگری را به درخواست‌کننده بدهد؛ مسیر رمزگذاری شده است، ولی مجوز دسترسی اشتباه است.

فهرست OWASP API Security Top 10، نسخهٔ ۲۰۲۳ ریسک‌هایی مانند مجوز شکسته در سطح شیء، احراز هویت ضعیف، مصرف نامحدود منابع، SSRF و اعتماد نادرست به APIهای دیگر را برجسته می‌کند. شمارهٔ نسخه را با سال جاری اشتباه نگیرید؛ عنوان «۲۰۲۶» به‌تنهایی یک استاندارد امنیتی تازه ایجاد نمی‌کند.

برای اتصال امن، ابتدا معماری را درست انتخاب کنید

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

1. مرورگردرخواست کاربر
2. بک‌اند سایتهویت، مجوز، سهمیه
3. سرویس مقصدکلید محدود و HTTPS

بک‌اند نباید به یک پراکسی عمومی تبدیل شود که هر URL، مدل، هزینه یا عملیاتی را از کاربر بپذیرد. مقصدها و عملیات مجاز را از قبل تعیین کنید؛ هزینه و دادهٔ خروجی را نیز محدود کنید. جداسازی کد عمومی و رازهای سرور در راهنمای امنیت فرانت‌اند OWASP نیز مطرح است.

HTTPS، TLS و تأیید گواهی را جدی بگیرید

نشانی رسمی HTTPS را از ابتدا استفاده کنید؛ کلید را ابتدا به HTTP نفرستید تا بعداً به HTTPS هدایت شود. اعتبار زنجیرهٔ گواهی و تطابق نام میزبان باید بررسی شود. خاموش‌کردن اعتبارسنجی TLS برای رفع خطای اتصال، هویت مقصد را بی‌اعتبار می‌کند و راه‌حل قابل‌قبول محیط واقعی نیست.

• TLS 1.3 را ترجیح دهید؛ TLS 1.2 می‌تواند برای سازگاریِ امن پشتیبانی شود. نسخه‌های قدیمی و SSL را کنار بگذارید.
• کتابخانهٔ HTTP، مخزن گواهی‌های مورداعتماد و وابستگی‌های رمزنگاری را به‌روز نگه دارید.
• برای بعضی ارتباط‌های حساس میان سرویس‌ها، mTLS هویت کلاینت را هم با گواهی بررسی می‌کند؛ صدور، تمدید و ابطال آن نیاز به برنامه دارد.
• mTLS جای کنترل مجوز کاربر، رکورد و عملیات را نمی‌گیرد.

منبع: راهنمای TLS در OWASP.

API Key، OAuth، JWT یا mTLS؛ کدام روش مناسب است؟

این اصطلاح‌ها هم‌معنی نیستند: OAuth چارچوب واگذاری دسترسی است، JWT قالب توکن است و mTLS به هویت طرف اتصال مربوط می‌شود. گاهی چند روش در یک معماری کنار هم استفاده می‌شوند. جدول زیر نقطهٔ شروع تصمیم است، نه نسخه‌ای یکسان برای همهٔ پروژه‌ها.

OAuth را با توصیه‌های جدیدتر پیاده کنید

RFC 9700، منتشرشده در ژانویهٔ ۲۰۲۵ مرجع بهترین رویه‌های امنیت OAuth 2.0 است. برای کلاینت عمومی، Authorization Code همراه PKCE ضروری است؛ برای کلاینت محرمانه هم PKCE توصیه می‌شود. از روش S256 و کتابخانهٔ نگهداری‌شده استفاده کنید، redirect URI را دقیق تطبیق دهید و از جریان Password Grant استفاده نکنید. برای کلاینت عمومی، refresh token باید چرخش یا اتصال به فرستنده داشته باشد. OAuth به‌تنهایی پروتکل ورود نیست؛ برای هویت ورود معمولاً OpenID Connect مطرح می‌شود.

داشتن JWT به معنی معتبر بودن آن نیست

Decode کردن payload فقط خواندن داده است. سرور باید امضا را با الگوریتم‌های مجاز خودش بررسی کند و صادرکننده، مخاطب و انقضای مورد انتظار را بسنجد؛ claimهای لازم به پروفایل توکن بستگی دارند. الگوریتم را کورکورانه از ورودی نپذیرید و توکن یا کلید را در URL قرار ندهید. جزئیات در راهنمای امنیت REST آمده است.

مجوز هر رکورد و عملیات را در سرور کنترل کنید

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

کنترل در سطح فیلد نیز لازم است: کاربر مجاز به ویرایش نام خودش نباید بتواند با افزودن فیلد role، نقش مدیریتی بگیرد. در برنامهٔ چندمستأجری، tenant را از زمینهٔ معتبر هویت استخراج کنید و در پرس‌وجو اعمال کنید؛ به tenantId ارسالی کاربر اعتماد نکنید. درخواست‌های بدون مجوز را در مسیر عادی و مسیرهای جایگزین بررسی کنید.

منبع: راهنمای مجوزدهی OWASP.

کلید API را کجا نگه داریم و هنگام افشا چه کنیم؟

کلید محرمانه را در HTML، کد فرانت‌اند، مخزن Git، فایل دانلودی یا اپلیکیشن قابل‌توزیع قرار ندهید. متغیر محیطیِ سمت سرور یکی از مسیرهای تزریق راز است؛ خودش سامانهٔ کامل مدیریت اسرار نیست. در پروژه‌های بزرگ‌تر از secret manager و دسترسی کنترل‌شدهٔ محیط اجرا استفاده کنید.

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

منبع: چرخهٔ عمر و مدیریت اسرار.

CORS و CSRF چه تفاوتی دارند؟

CORS تعیین می‌کند کدام مبدأ وب بتواند پاسخ را در مرورگر بخواند؛ احراز هویت نیست و درخواست مستقیمِ ابزارها یا سرورهای دیگر را متوقف نمی‌کند. مبدأهای موردنیاز را دقیق مشخص کنید. ترکیب credential با مبدأ wildcard راه‌حل معتبر نیست؛ بازتاب هر Origin هم معادل یک فهرست مجاز واقعی نیست.

وقتی احراز هویت با کوکی انجام می‌شود، مرورگر ممکن است کوکی را همراه درخواست ارسال کند. برای عملیات تغییردهنده از الگوی معتبر CSRF token یا کنترل‌های مناسب چارچوب، بررسی Origin و کوکی‌های Secure، HttpOnly و SameSite متناسب استفاده کنید. SameSite یک لایهٔ دفاعی است، نه جایگزین همیشگی کنترل CSRF؛ GET را برای تغییر داده به کار نبرید.

منابع: مستندات CORS در MDN و پیشگیری از CSRF.

دادهٔ نامعتبر و مصرف بی‌حد منابع را محدود کنید

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

اندازهٔ بدنه، تعداد نتایج، صفحه‌بندی، زمان اجرا و هم‌زمانی را متناسب با عملیات محدود کنید. جست‌وجوی سنگین، تولید تصویر یا درخواست مدل هوش مصنوعی فقط با شمارش تعداد درخواست‌ها کنترل نمی‌شود؛ هزینه و بودجهٔ مصرف هم مهم است. سهمیه را بسته به سناریو برای حساب، توکن، عملیات و IP در نظر بگیرید. برای محدودیت نرخ از پاسخ 429 و سیاست تلاش مجددِ روشن استفاده کنید؛ در کارهای حساس، جلوگیری از اجرای تکراری هم لازم است.

منابع: اعتبارسنجی ورودی و ریسک مصرف منابع در API.

برای SSRF و پاسخ APIهای دیگر مرز بگذارید

اگر سرور URL دلخواه کاربر را دریافت و باز کند، ممکن است ناخواسته به منابع داخلی یا نشانی‌های مدیریتی درخواست بزند. تا حد امکان مقصد را از فهرست ازپیش‌تعیین‌شده انتخاب کنید. اعتبارسنجی رشتهٔ دامنه به‌تنهایی کافی نیست: نتیجهٔ DNS، IPv4 و IPv6، نشانی‌های خصوصی و محلی، تغییرمسیرها و دسترسی خروجی شبکه باید در طراحی لحاظ شوند.

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

منبع: پیشگیری از SSRF در OWASP.

مثال اتصال سمت سرور با مقصد ثابت و مهلت محدود

این نمونهٔ JavaScript برای محیط Node.js دارای fetch و AbortSignal.timeout نوشته شده است. دامنهٔ example.com نمایشی است و باید با مقصد ثابت و تأییدشدهٔ ارائه‌دهنده جایگزین شود. کلید از محیط سرور خوانده می‌شود؛ اعتبارسنجی TLS پیش‌فرض حفظ می‌شود و تغییرمسیر دنبال نمی‌شود.

async function readProviderStatus() {
  const token = process.env.PROVIDER_API_TOKEN;
  if (!token) throw new Error('Missing provider credential');

  const response = await fetch('https://api.example.com/v1/status', {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: 'application/json'
    },
    redirect: 'error',
    signal: AbortSignal.timeout(5000)
  });

  if (!response.ok) throw new Error('Provider request failed');
  const mime = response.headers.get('content-type') || '';
  if (!/^application\/json(?:\s*;|$)/i.test(mime)) {
    throw new Error('Unexpected response type');
  }
  return response.json();
}

برای اعتبارسنجی مستقل مجوزها، یک آزمون دفاعی ساده طراحی کنید: کاربر آزمایشی الف باید فقط رکوردهای خودش را ببیند؛ کاربر ب نباید با تغییر شناسه به آن‌ها دسترسی پیدا کند. این بررسی را فقط روی محیط و داده‌ای انجام دهید که مجوز آن را دارید. مرجع قابلیت‌های نمونه: fetch و AbortSignal در مستندات Node.js.

امنیت وب‌هوک: امضا، زمان و جلوگیری از اجرای دوباره

وجود نام سرویس در JSON، هویت فرستنده را ثابت نمی‌کند. روش تأیید امضای ارائه‌دهنده را دقیق پیاده کنید؛ امضا معمولاً به بایت‌های خام بدنه وابسته است و بازسازی JSON ممکن است آن را تغییر دهد. مقایسهٔ امضای رمزنگاری‌شده را با روش زمان‌ثابتِ کتابخانهٔ معتبر انجام دهید.

بازهٔ زمانی معتبر و شناسهٔ رویداد را بررسی کنید تا replay و پردازش تکراری کنترل شوند. دریافت دوبارهٔ رویداد نباید دوباره موجودی، پرداخت یا پیام را تغییر دهد. پس از تأیید و ثبت پایدار، پردازش طولانی را به صف بسپارید؛ رفتار پاسخ و retry باید با مستندات همان سرویس هماهنگ باشد.

منبع: راهنمای امنیت Webhook.

چه چیزهایی را ثبت و پس از انتشار بررسی کنیم؟

شناسهٔ درخواست، عملیات، نتیجه، زمان پاسخ و شناسهٔ غیرحساس حساب به عیب‌یابی کمک می‌کنند. گذرواژه، کلید، Authorization header، کوکی نشست و دادهٔ شخصی غیرضروری را از گزارش حذف یا پوشانده نگه دارید. دسترسی و مدت نگهداری لاگ هم باید کنترل شود.

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

منبع: ثبت رویداد امن در OWASP.

چک‌لیست اتصال ایمن به API

این فهرست برای مرور تصمیم‌هاست. تیک‌زدن موارد به معنی ممیزی یا تأیید امنیت پروژه نیست؛ وضعیت تیک‌ها فقط تا بازبودن همین صفحه نگه داشته می‌شود.

• مقصد رسمی HTTPS است و اعتبارسنجی گواهی فعال است.
• روش هویت و مجوز برای نوع کلاینت مشخص شده است.
• کلید محرمانه در سرور است و در کد عمومی یا URL نیست.
• مجوز هر رکورد، عملیات و فیلد در سرور بررسی می‌شود.
• توکن‌ها محدودند و برنامهٔ انقضا، چرخش و ابطال دارند.
• schema، حجم، صفحه‌بندی، timeout و سهمیه تعیین شده‌اند.
• CORS و در صورت کاربرد، کنترل CSRF تنظیم شده‌اند.
• مقصد خروجی، تغییرمسیرها و پاسخ سرویس بیرونی محدودند.
• امضای وب‌هوک و جلوگیری از اجرای دوباره بررسی شده‌اند.
• گزارش‌ها فاقد راز هستند و مسیر بررسی رخداد مشخص است.

پرسش‌های متداول دربارهٔ امنیت API