اعتبارسنجی JWT

گاردریل jwt_validation یک توکن JWT را از متن استخراج می‌کند و اعتبار آن را با یکی از روش‌های پشتیبانی‌شده بررسی می‌کند. از این نوع وقتی استفاده کنید که وجود توکن معتبر بخشی از سیاست امنیتی متن ورودی شماست.

این گاردریل فقط از «اعتبارسنجی» (operation: "validate") پشتیبانی می‌کند و متن را تغییر نمی‌دهد.

هشدار

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

چه زمانی استفاده کنید؟

از این گاردریل برای این کارها استفاده کنید:

الزام وجود Bearer JWT معتبر در متن ورودی مدل.
بررسی «صادرکننده» و «مخاطب» توکن پیش از ادامه مسیر.
اعتبارسنجی توکن با «کلید مشترک»، «JWKS درون‌خطی»، «آدرس JWKS» یا «آدرس بررسی توکن».
جلوگیری از ادامه مسیر وقتی توکن داخل متن وجود ندارد یا معتبر نیست.

اگر هدف شما جلوگیری از نشت توکن در متن است، تشخیص Secret را هم فعال کنید.

رفتار اجرایی

الگوی پیش‌فرض دنبال قالب زیر می‌گردد:

Bearer <header>.<payload>.<signature>

اگر توکن پیدا نشود، علت JWT token is missing ثبت می‌شود. اگر توکن پیدا شود، گدارAI این موارد را بررسی می‌کند:

exp، اگر وجود داشته باشد، نباید گذشته باشد.
nbf، اگر وجود داشته باشد، نباید در آینده باشد.
iss فقط وقتی بررسی می‌شود که «صادرکننده» را وارد کرده باشید.
aud فقط وقتی بررسی می‌شود که «مخاطب» را وارد کرده باشید.

سپس یکی از روش‌های اعتبارسنجی اجرا می‌شود:

عنوان UI	مقدار API	رفتار
کلید مشترک	`shared_secret`	امضای `HS256`، `HS384` یا `HS512` را بررسی می‌کند.
JWKS درون‌خطی	`inline_jwks`	کلید RSA را از JWKS واردشده پیدا می‌کند.
آدرس JWKS	`jwks_uri`	JWKS را از آدرس واردشده دریافت و امضای RSA را بررسی می‌کند.
آدرس بررسی توکن	`introspection_url`	توکن را با درخواست `POST` بررسی می‌کند و `active: true` می‌خواهد.

اگر «آدرس بررسی توکن» وارد شده باشد، پس از بررسی claimها از همان مسیر استفاده می‌شود و بررسی امضای محلی اجرا نمی‌شود.

تنظیمات

عنوان UI	مقدار API	توضیح
Regex استخراج توکن	`token_regex`	اختیاری است. اگر وارد شود، توکن باید در capture group اول باشد.
صادرکننده	`issuer`	مقدار مورد انتظار claim برابر `iss`.
مخاطب	`audience`	مقدار مورد انتظار claim برابر `aud`.
کلید مشترک	`shared_secret`	یکی از روش‌های اعتبارسنجی. برای الگوریتم‌های HMAC.
JWKS درون‌خطی	`inline_jwks`	یکی از روش‌های اعتبارسنجی. باید شامل `keys` غیرخالی باشد.
آدرس JWKS	`jwks_uri`	یکی از روش‌های اعتبارسنجی.
آدرس بررسی توکن	`introspection_url`	یکی از روش‌های اعتبارسنجی فعال‌بودن توکن.
هدر احراز هویت بررسی توکن	`introspection_auth_header`	اختیاری است. مقدار کامل سرآیند `Authorization` برای آدرس بررسی توکن.

باید دست‌کم یکی از «کلید مشترک»، «JWKS درون‌خطی»، «آدرس JWKS» یا «آدرس بررسی توکن» را وارد کنید.

نکته

اگر توکن شما با قالب پیش‌فرض Bearer ... در متن نیست، token_regex را طوری تنظیم کنید که خود توکن در capture group اول قرار بگیرد.

نمونه با کلید مشترک

{
  "slug": "signed-user-token",
  "name": "اعتبارسنجی توکن کاربر",
  "description": "وجود JWT معتبر با صادرکننده و مخاطب مشخص را بررسی می‌کند.",
  "type": "jwt_validation",
  "operation": "validate",
  "enforcement": "enforce",
  "enabled": true,
  "config": {
    "issuer": "https://identity.your-company.ir",
    "audience": "godarai-api",
    "shared_secret": "REPLACE_WITH_SECRET"
  }
}

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

نمونه با آدرس JWKS

{
  "slug": "jwt-with-jwks",
  "name": "اعتبارسنجی JWT با JWKS",
  "type": "jwt_validation",
  "operation": "validate",
  "enforcement": "enforce",
  "enabled": true,
  "config": {
    "issuer": "https://identity.your-company.ir",
    "audience": "godarai-api",
    "jwks_uri": "https://identity.your-company.ir/.well-known/jwks.json"
  }
}

نمونه استفاده

برای کنترل ورودی مدل:

x-godarai-guardrails: {"llm_input_guardrails":["guardrails/signed-user-token"]}

متنی که بررسی می‌شود باید شامل توکن با قالب پیش‌فرض باشد، مگر اینکه «Regex استخراج توکن» را تغییر داده باشید.

بررسی نتیجه

اگر توکن وجود نداشته باشد، علت JWT token is missing ثبت می‌شود. اگر توکن پیدا شود اما اعتبارسنجی ناموفق باشد، علت JWT validation failed ثبت می‌شود.

نمونه نتیجه ناموفق:

{
  "selector": "guardrails/signed-user-token",
  "status": "blocked",
  "operation": "validate",
  "enforcement": "enforce",
  "reason": "JWT validation failed"
}

محدودیت‌ها و نکات امنیتی

وجود exp الزامی نیست؛ فقط اگر در توکن باشد بررسی می‌شود.
«Regex استخراج توکن» باید capture group داشته باشد. اگر Regex نامعتبر باشد، موتور از الگوی پیش‌فرض استفاده می‌کند.
دریافت JWKS و بررسی توکن از راه شبکه انجام می‌شود و برای هر اجرا مهلت محدودی دارد.
«آدرس JWKS» و «آدرس بررسی توکن» را فقط به سرویس‌های قابل اعتماد بدهید.
مقدارهای حساس این تنظیمات در پیکربندی گاردریل نگهداری می‌شوند. دسترسی مدیریت گاردریل‌ها را محدود کنید.
گاردریل آماده برای این نوع وجود ندارد؛ باید گاردریل اختصاصی بسازید.
گاردریل خروجی با پاسخ جریانی پشتیبانی نمی‌شود.

گام بعدی

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

چه زمانی استفاده کنید؟​

رفتار اجرایی​

تنظیمات​

نمونه با کلید مشترک​

نمونه با آدرس JWKS​

نمونه استفاده​

بررسی نتیجه​

محدودیت‌ها و نکات امنیتی​

گام بعدی​