احراز هویت API چیست؟ تفاوت API Key، JWT و OAuth2

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

جست‌وجوهایی مثل «احراز هویت API چیست»، «JWT چیست»، «OAuth2 چیست»، «API Key یا JWT» و «امن‌سازی API» نیت آموزشی و فنی دارند. این راهنما انتخاب الگوی مناسب، تفاوت authentication و authorization، چرخه توکن، refresh token و خطاهای رایج را توضیح می‌دهد. برای تعریف خود API، راهنمای API چیست را ببینید؛ این مقاله روی حفاظت از مسیرهای API تمرکز دارد و جای توسعه نرم‌افزار اختصاصی نیست.

OAuth 2.0 is an authorization framework that enables a third-party application to obtain limited access to an HTTP service.

احراز هویت و مجوزدهی چه تفاوتی دارند؟

وقتی کاربر وارد حساب می‌شود، سیستم تلاش می‌کند هویت او را تأیید کند؛ این authentication است. وقتی همان کاربر می‌خواهد سفارش دیگری را ببیند یا گزارش مالی صادر کند، سیستم باید بررسی کند اجازه آن عمل را دارد؛ این authorization است. پیاده‌سازی یکی بدون دیگری می‌تواند API را ظاهراً امن اما در عمل بیش‌ازحد باز بگذارد.

این تفکیک در طراحی endpoint هم دیده می‌شود. پاسخ 401 معمولاً به نبودن یا نامعتبر بودن credential مربوط است؛ 403 یعنی هویت شناخته شده اما مجوز کافی ندارد. پیام خطا نباید secret، وجود کاربر یا جزئیات داخلی را لو بدهد. لاگ سمت سرور باید برای تشخیص رخداد مفید باشد، اما داده حساس را ذخیره نکند.

API Key چیست و چه زمانی کافی است؟

API Key رشته‌ای است که کلاینت برای شناسایی پروژه یا مصرف‌کننده در header می‌فرستد. برای یک job داخلی، سرویس server-to-server یا دسترسی محدود به API عمومی می‌تواند ساده و مناسب باشد. کلید را در URL نگذارید، داخل repository commit نکنید و آن را بین محیط development و production مشترک نکنید.

کلید باید scope، محدودیت نرخ، تاریخ چرخش و امکان revoke داشته باشد. اگر چند کاربر با یک کلید مشترک کار کنند، ردیابی و قطع دسترسی یک نفر ممکن نیست. برای داده حساس کاربرمحور، API Key به‌تنهایی معمولاً مدل کاملی از هویت و مجوز نیست.

JWT چیست و چه اشتباهاتی دارد؟

JWT توکنی امضاشده با claimهایی مثل subject، issuer، audience و expiration است. امضا به گیرنده کمک می‌کند تغییر payload را تشخیص دهد؛ رمزنگاری نیست و نباید اطلاعات حساس را در payload عمومی قرار دهید. سرور باید الگوریتم مورد انتظار، issuer، audience و زمان انقضا را بررسی کند، نه اینکه فقط decode کردن را معادل اعتبار بداند.

Access token بهتر است عمر کوتاهی داشته باشد. Refresh token چرخه دریافت access token جدید را مدیریت می‌کند و باید محافظت بیشتری داشته باشد؛ چرخش، revoke و تشخیص reuse برای سناریوهای حساس مهم‌اند. نگهداری توکن در محل نامناسب، لاگ کردن Authorization header یا استفاده از secret یکسان در همه محیط‌ها، مدل را ضعیف می‌کند.

OAuth2 و OIDC چه زمانی انتخاب بهتری هستند؟

OAuth2 چارچوب delegation است: کاربر یا سیستم اجازه محدود به یک کلاینت می‌دهد بدون اینکه password خود را به آن کلاینت بدهد. OIDC روی OAuth2 لایه هویت اضافه می‌کند و برای login federated کاربرد دارد. انتخاب flow به نوع کلاینت بستگی دارد؛ SPA، موبایل، backend محرمانه و device flow ریسک و نیاز متفاوت دارند.

برای کلاینت عمومی از الگوی امن و PKCE استفاده کنید و redirect URI را دقیق allowlist کنید. wildcardهای باز، state نادیده‌گرفته‌شده و ذخیره secret در کد frontend اشتباه‌های جدی‌اند. scopeها را حداقلی تعریف کنید: خواندن پروفایل با حذف کاربر یکی نیست.

RBAC و scope؛ دسترسی را کوچک نگه دارید

در RBAC دسترسی بر اساس نقش‌هایی مثل admin، editor یا viewer تعیین می‌شود. scope می‌تواند مجوز را برای یک API یا عمل دقیق‌تر کند؛ مثلاً orders:read. در سیستم‌های پیچیده‌تر، مالکیت منبع، سازمان، زمان و ویژگی داده ممکن است به ABAC یا policy engine نیاز داشته باشد. مهم این است که کنترل دسترسی در backend enforce شود، نه فقط دکمه frontend مخفی شود.

همیشه object-level authorization را بررسی کنید. اینکه کاربر مجاز به دیدن endpoint سفارش است، به معنی مجاز بودن برای دیدن سفارش کاربر دیگر نیست. شناسه قابل حدس، endpoint داخلی یا تغییر id در request نباید به داده خصوصی دسترسی بدهد. تست‌های منفی برای هر نقش بنویسید؛ happy path به‌تنهایی امنیت نیست.

HTTPS، CORS و ذخیره credential

توکن و credential باید روی HTTPS منتقل شوند. CORS کنترل دسترسی مرورگر است، نه سیستم authentication؛ با allow کردن originهای بیش از حد، credential و wildcard ترکیب نکنید. برای cookieهای session، HttpOnly، Secure و SameSite را متناسب با معماری تنظیم کنید و در برابر CSRF محافظت داشته باشید.

Secretها را در environment یا secret manager نگه دارید و در log، error tracking و screenshot وارد نکنید. کلیدهای لو رفته را rotate و revoke کنید؛ فقط حذف از فایل کد کافی نیست چون ممکن است در history، build artifact یا log باقی مانده باشد. سرویس ثالثی که webhook می‌فرستد نیز باید امضای پیام و replay protection داشته باشد.

Rate limit و پایش رخداد

Rate limit جلوی سوءاستفاده، brute force و مصرف بی‌رویه را می‌گیرد، اما جای authorization نیست. limit را بر اساس identity، IP، endpoint و ریسک عملیات طراحی کنید. login، reset password و export داده معمولاً حساس‌تر از health check هستند. پاسخ 429 و headerهای مرتبط باید برای کلاینت قابل فهم باشند.

متریک‌های مفید شامل خطای 401 و 403، تلاش ناموفق login، refresh token reuse، تغییر scope، الگوی غیرعادی IP و مصرف endpointهای حساس است. آلارم باید به runbook و مالک وصل شود. راهنمای webhook و راهنمای میکروسرویس برای طراحی ارتباطات بین سرویس‌ها زمینه بیشتری می‌دهند.

چطور احراز هویت API را تست کنیم؟

1. درخواست بدون credential، credential منقضی و credential دستکاری‌شده را تست کنید.
2. دسترسی هر نقش به منبع خودش و منبع کاربر دیگر را بررسی کنید.
3. scope کم، audience اشتباه و issuer اشتباه را رد کنید.
4. rate limit، revoke، refresh و logout را در سناریوهای واقعی اجرا کنید.
5. اطمینان دهید خطاها secret یا اطلاعات وجود حساب را افشا نمی‌کنند.
6. تست integration را روی محیط جدا با secretهای آزمایشی انجام دهید.

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

• قرار دادن API key یا JWT داخل query string
• اعتبارسنجی فقط امضای JWT و نادیده گرفتن exp، iss و aud
• استفاده از access token بلندمدت بدون revoke
• اعتماد به مخفی بودن دکمه frontend به‌جای کنترل backend
• یک credential مشترک برای همه کاربران و محیط‌ها
• allow کردن CORS برای هر origin همراه credential
• نبودن لاگ امن، rate limit و تست دسترسی به object

چک‌لیست انتخاب روش احراز هویت

1. نوع کلاینت‌ها و مرز اعتماد مشخص شده است.
2. authentication از authorization جدا طراحی شده است.
3. scope و نقش‌ها حداقلی و قابل revoke هستند.
4. عمر توکن، refresh و چرخش secret تعریف شده است.
5. HTTPS، CORS، cookie و CSRF متناسب با معماری تنظیم شده‌اند.
6. rate limit، لاگ و هشدار برای مسیرهای حساس وجود دارد.
7. تست‌های منفی و object-level authorization اجرا می‌شوند.

جمع‌بندی

احراز هویت API انتخاب بین چند اسم نیست؛ تصمیمی درباره هویت، دامنه دسترسی، چرخه عمر credential و امکان پایش است. API Key برای سناریوی ساده می‌تواند کافی باشد، JWT باید دقیق validate و کوتاه‌عمر باشد و OAuth2/OIDC برای delegation و هویت بین سرویس‌ها کاربرد دارند. در همه حالت‌ها اصل least privilege، HTTPS، revoke و تست منفی را فراموش نکنید.

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