درحال مشاهده اسناد Apigee Edge هستید.
به
اسناد Apigee X بروید. اطلاعات
این موضوع اطلاعات کلی درباره JWT (نشان وب JSON) و JWS (امضای وب JSON) و خط‌مشی‌های Apigee JWS/JWT که ممکن است برای توسعه‌دهندگان پراکسی Apigee جالب باشد ارائه می‌دهد.
مقدمه
از هر دو نوع JWS و JWT معمولاً برای هم‌رسانی ادعاها یا اظهارات بین برنامه‌های متصل استفاده می‌شود. خط‌مشی‌های JWS/JWT پراکسی‌های Edge API را قادر می‌سازد تا:
- یک تولید JWT امضاشده یا JWS.
- درستی‌سنجی یک JWT امضاشده یا JWS و ادعاهای درون JWS/JWT.
- رمزگشایی JWT امضاشده یا JWS بدون اعتبارسنجی امضا.
در دو مورد آخر، خط‌مشی متغیرهایی را نیز تنظیم می‌کند که به خط‌مشی‌های اضافی یا خود خدمات زیرینه اجازه می‌دهد ادعاهای تأییدشده را بررسی کنند و براساس آن ادعاها تصمیم‌گیری کنند.
هنگام استفاده از خط‌مشی «درستی‌سنجی JWS/JWT»، یک JWS/JWT نامعتبر رد خواهد شد و منجر به وضعیت خطا خواهد شد. به‌همین ترتیب، هنگام استفاده از خط‌مشی «کدگشایی JWS/JWT»، یک JWS/JWT بدشکل منجر به وضعیت خطا می‌شود.
ویدیوها
برای آشنایی سریع با JWT، ویدیو کوتاهی را تماشا کنید. اگرچه این ویدیو به‌طور خاص به تولید JWT می‌پردازد، بسیاری از مفاهیم برای JWS یکسان هستند.
ویدیو کوتاهی برای آشنایی بیشتر با ساختار JWT.
موارد استفاده
می‌توانید از خط‌مشی‌های JWS/JWT برای موارد زیر استفاده کنید:
- در طرفین نقطه پایان هدف یا پراکسی، یک JWS/JWT جدید در پراکسی Edge تولید کنید. برای مثال، ممکن است یک جریان درخواست پراکسی ایجاد کنید که یک JWS/JWT تولید می‌کند و آن را به یک مشتری برمی‌گرداند. یا می‌توانید کارگزار نیابتی را طراحی کنید تا JWS/JWT را در جریان درخواست هدف تولید کند و آن را به درخواست ارسال‌شده به هدف پیوست کند. سپس آن ادعاها برای فعال کردن سرویس‌های زیرینه دردسترس قرار می‌گیرند تا پردازش امنیتی بیشتری اعمال کنند.
- ادعاهای JWS/JWT را که از درخواست‌های ورودی کارخواه، از پاسخ‌های سرویس هدف، از پاسخ‌های خط‌مشی «پیام‌واره سرویس»، یا از منابع دیگر به‌دست آمده است درستی‌سنجی و استخراج کنید. Edge بااستفاده از الگوریتم‌های RSA یا HMAC، امضای JWS/JWT را، چه JWS/JWT توسط طرف سوم تولید شده باشد چه توسط خود Edge، تأیید می‌کند.
- یک JWS/JWT را رمزگشایی کنید. وقتی مقدار ادعا (JWT) یا سرایند (JWS/JWT) از داخل JWS/JWT باید قبل‌از درستی‌سنجی JWS/JWT مشخص شود، رمزگشایی درصورت استفاده هم‌زمان با خط‌مشی «درستی‌سنجی JWS/JWT» بسیار مفید است.
بخش‌های JWS/JWT
JWS/JWT امضاشده اطلاعات را در سه بخش که با نقطه از هم جدا شده‌اند کدبندی می‌کند: سرصفحه، محتوا، و امضا:
header.payload.signature
- خط‌مشی «تولید JWS/JWT» هر سه بخش را ایجاد می‌کند.
- خط‌مشی «درستی‌سنجی JWS/JWT» هر سه بخش را بررسی می‌کند.
- خط‌مشی «رمزگشایی JWS/JWT» فقط سرصفحه و داده‌بار را بررسی می‌کند.
JWS همچنین از قالب جداشده پشتیبانی می‌کند که پایه‌بار را از JWS حذف می‌کند:
header..signature
در JWS جداشده، پایه‌بار به‌صورت جداگانه از JWS ارسال می‌شود. از عنصر
<DetachedContent> خط‌مشی «درستی‌سنجی JWS» برای تعیین بار JWS خام و کدبندی‌نشده استفاده می‌کنید.
خط‌مشی «درستی‌سنجی JWS» سپس JWS را بااستفاده از سرایند و امضا در JWS و بار
مشخص‌شده توسط عنصر <DetachedContent> درستی‌سنجی می‌کند.
برای کسب اطلاعات بیشتر درباره نشان‌ها و نحوه کدگذاری و امضای آن‌ها، به موارد زیر مراجعه کنید:
- JWT: IETF RFC7519
- JWS: IETF RFC7515
تفاوت‌های بین JWS و JWT
می‌توانید از JWT یا JWS برای هم‌رسانی ادعاها یا اظهارات بین برنامه‌های متصل استفاده کنید. تفاوت اصلی بین این دو، نمایش پایه‌بار است:
- JWT
- پایه‌بار همیشه یک شیء JSON است
- بار همیشه به JWT پیوست می‌شود
- سرصفحه
typنشان همیشه رویJWTتنظیم می‌شود
- JWS
- بار می‌تواند با هر قالبی، مانند شیء JSON، جاری‌سازی بایت، جاری‌سازی هشت‌تایی، و غیره نشان داده شود
- پایه‌بار لازم نیست به JWS پیوست شود
ازآنجایی‌که قالب JWT همیشه از شیء JSON برای نمایش پایه‌بار استفاده می‌کند، خط‌مشی‌های «تولید JWT» و «درستی‌سنجی JWT» در Edge از پشتیبانی داخلی برای مدیریت «نام‌های ادعای ثبت‌شده» رایج، مثل aud، iss، sub، و موارد دیگر برخوردارند. یعنی می‌توانید از عناصر خط‌مشی «تولید خط‌مشی JWT» برای تنظیم این ادعاها در محتوای پیام و از عناصر خط‌مشی «درستی‌سنجی خط‌مشی JWT» برای درستی‌سنجی مقادیر آن‌ها استفاده کنید. برای اطلاعات بیشتر، بخش نام‌های ادعای ثبت‌شده مشخصات JWT را ببینید.
خط‌مشی «تولید JWT» علاوه‌بر پشتیبانی از «نام‌های ادعای ثبت‌شده» خاص، مستقیماً از افزودن ادعاهایی با نام‌های اختیاری به JWT پشتیبانی می‌کند. هر ادعا یک جفت نام/مقدار ساده است، که مقدار می‌تواند از نوع عدد، بولی، رشته، نقشه، یا آرایه باشد.
ازآنجایی‌که JWS می‌تواند از هر نمایش داده‌ای برای محتوا استفاده کند، نمی‌توانید ادعاهایی را به محتوا اضافه کنید. خط‌مشی «تولید JWS» از افزودن ادعاهایی با نام‌های اختیاری به سرایند JWS پشتیبانی می‌کند. همچنین، خط‌مشی‌های JWS از بار جداشده پشتیبانی می‌کنند، جایی که JWS بار را حذف می‌کند. پایه‌بار جداشده به شما امکان می‌دهد JWS و پایه‌بار را جداگانه ارسال کنید و توسط چندین استاندارد امنیتی الزامی است.
جلوگیری از تزریق الگو هنگام استفاده از JWS و JWT
برای جلوگیری از افشای غیرمجاز داده‌ها، هنگام استفاده از خط‌مشی‌های GenerateJWT یا GenerateJWS، این دستورالعمل‌ها را دنبال کنید:
- از ارجاع مستقیم به ورودی کاربر خودداری کنید: هرگز از ورودی غیرقابل‌اعتماد (مثل
request.queryparam.*یاrequest.header.*) به‌طور مستقیم در ویژگیrefکه از الگو پشتیبانی می‌کند استفاده نکنید. - پاک‌سازی ورودی: اگر باید از داده‌های خارجی در ادعای JWT/JWS استفاده کنید، ابتدا از
خط‌مشی AssignMessage
برای حذف هرگونه آکولاد (
{ }) یا نویسه‌های الگوی دیگر از ورودی قبل‌از ارجاع دادن به آن استفاده کنید. - استفاده از ادعاهای صریح برای رشته‌ها: برای ادعاهای رشته‌ای ساده، از
type="map"اجتناب کنید. استفاده ازtype="string"پیش‌فرض مانع از الگوسازی ضمنی مقدار ارجاع‌شده می‌شود. - به ناسازگاری رفتاری بین خط‌مشی‌های تأیید و تولید توجه کنید: خط‌مشی‌های تولید JWS و JWT درخصوص الگو با خط‌مشی‌های تأیید رفتار متفاوتی دارند.
درباره الگوریتم‌های امضا
خط‌مشی‌های «درستی‌سنجی JWS/JWT» و «تولید JWS/JWT» از الگوریتم‌های RSA، RSASSA-PSS، ECDSA، و HMAC بااستفاده از مجموعهای وارسی SHA2 با قدرت بیت ۲۵۶، ۳۸۴، یا ۵۱۲ پشتیبانی می‌کنند. خط‌مشی «رمزگشایی JWS/JWT» صرف‌نظر از الگوریتمی که برای امضای JWS/JWT استفاده شده است کار می‌کند.
الگوریتم HMAC
الگوریتم HMAC برای ایجاد امضا (که به آن امضای JWS/JWT نیز گفته می‌شود) و برای درستی‌سنجی امضا، به یک رمز مشترک که به‌عنوان کلید رمز شناخته می‌شود متکی است.
حداقل طول کلید مخفی به قدرت بیت الگوریتم بستگی دارد:
- HS256: حداقل طول کلید ۳۲ بایت
- HS386: حداقل طول کلید ۴۸ بایت
- HS512: حداقل طول کلید ۶۴ بایت
الگوریتم RSA
الگوریتم RSA از جفت کلید عمومی/خصوصی برای امضای رمزنگاری‌شده استفاده می‌کند. در امضاهای RSA، طرف امضاکننده از کلید خصوصی RSA برای امضا کردن JWS/JWT استفاده می‌کند و طرف درستی‌سنج از کلید عمومی RSA متناظر برای درستی‌سنجی امضای JWS/JWT استفاده می‌کند. هیچ الزامی برای اندازه کلیدها وجود ندارد.
الگوریتم RSASSA-PSS
الگوریتم RSASSA-PSS به‌روزرسانی الگوریتم RSA است. مانند RSS، RSASSA-PSS از جفت کلید عمومی/خصوصی RSA برای امضای رمزنگاری استفاده می‌کند. قالب کلید همانند قالب کلید RSS است. طرف امضاکننده از کلید خصوصی برای امضا کردن JWS/JWT استفاده می‌کند و طرف درستی‌سنج از کلید عمومی مطابق برای درستی‌سنجی امضای JWS/JWT استفاده می‌کند. هیچ الزامی برای اندازه کلیدها وجود ندارد.
الگوریتم ECDSA
الگوریتم «الگوریتم امضای دیجیتال منحنی بیضوی» (ECDSA) الگوریتم رمزنگاری منحنی بیضوی با منحنی P-256، P-384، و P-521 است. وقتی از الگوریتم‌های ECDSA استفاده می‌کنید، الگوریتم نوع کلید عمومی و خصوصی را که باید مشخص کنید تعیین می‌کند:
| الگوریتم | خمیده | الزام کلیدی |
|---|---|---|
| ES256 | P-256 | کلیدی که از منحنی P-256 تولید شده است (همچنین به‌عنوان secp256r1 یا prime256v1 شناخته می‌شود) |
| ES384 | P-384 | کلیدی که از منحنی P-384 (که با نام secp384r1 نیز شناخته می‌شود) تولید شده است |
| ES512 | P-521 | کلیدی که از منحنی P-521 (که با نام secp521r1 نیز شناخته می‌شود) تولید شده است |
الگوریتم‌های رمزگذاری کلید
خط‌مشی‌های JWS/JWT از همه الگوریتم‌های رمزگذاری کلید پشتیبانی‌شده توسط OpenSSL پشتیبانی می‌کنند.
استفاده از مجموعه کلید وب JSON (JWKS) برای درستی‌سنجی JWS/JWT
وقتی JWS/JWT امضاشده‌ای را درستی‌سنجی می‌کنید، باید کلید عمومی‌ای را که با کلید خصوصی استفاده‌شده برای امضا کردن کد ارتباط دارد ارائه دهید. برای ارائه کلید عمومی به خط‌مشی‌های «درستی‌سنجی JWS/JWT»، دو گزینه دارید:
- از مقدار کلید عمومی واقعی (معمولاً در متغیر جاری‌سازی ارائه می‌شود) استفاده کنید، یا
- از کلید عمومی پیچیده‌شده در JWKS استفاده کنید.
درباره JWKS
JWKS ساختار JSON است که مجموعهای از «کلیدهای وب JSON» (JWK) را نشان می‌دهد. JWK ساختار داده‌ای JSON است که کلید رمزگذاری را نشان می‌دهد. JWK و JWKS در RFC7517 توضیح داده شده‌اند. نمونه‌های JKWS را در پیوست الف ببینید. مجموعه‌های کلید وب JSON نمونه
ساختار JWKS
RFC7517 عناصر کلید JWKS را برای هر نوع کلید، مانند «RSA» یا «EC»، توصیف می‌کند. برای مثال، بسته به نوع کلید، این پارامترها می‌تواند شامل موارد زیر باشد:
- kty - نوع کلید، مانند «RSA» یا «EC».
- kid (شناسه کلید) - می‌تواند هر مقدار اختیاری باشد (بدون تکرار در مجموعه کلید). اگر JWT ورودی دارای شناسه کلیدی باشد که در مجموعه JWKS وجود دارد، خط‌مشی از کلید عمومی صحیح برای درستی‌سنجی امضای JWS/JWT استفاده خواهد کرد.
در زیر نمونه‌هایی از عناصر اختیاری و مقادیر آن‌ها آورده شده است:
- alg - الگوریتم کلید. باید با الگوریتم امضا در JWS/JWT مطابقت داشته باشد.
- استفاده - اگر وجود دارد، باید sig باشد.
JWKS زیر شامل عناصر و مقادیر الزامی است و در Edge معتبر خواهد بود (از https://www.googleapis.com/oauth2/v3/certs):
{
"keys":[
{
"kty":"RSA",
"alg":"RS256",
"use":"sig",
"kid":"ca04df587b5a7cead80abee9ea8dcf7586a78e01",
"n":"iXn-WmrwLLBa-QDiToBozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt7-V7KDjCq0_Nkd-X9rMRV5LKgCa0_F8YgI30QS3bUm9orFryrdOc65PUIVFVxIwMZuGDY1hj6HEJVWIr0CZdcgNIll06BasclckkUK4O-Eh7MaQrqb646ghFlG3zlgk9b2duHbDOq3s39ICPinRQWC6NqTYfqg7E8GN_NLY9srUCc_MswuUfMJ2cKT6edrhLuIwIj_74YGkpOwilr2VswKsvJ7dcoiJxheKYvKDKtZFkbKrWETTJSGX2Xeh0DFB0lqbKLVvqkM2lFU2Qx1OgtTnrw",
"e":"AQAB"
},
{
"kty":"EC",
"alg":"ES256",
"use":"enc",
"kid":"k05TUSt7-V7KDjCq0_N"
"crv":"P-256",
"x":"Xej56MungXuFZwmk_xccvsMpCtXmqhvEEMCmHyAmKF0",
"y":"Bozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt",
}
]
}درحال طراحی پراکسی برای استفاده از JWKS
وقتی JWS/JWT از صادرکننده دریافت می‌شود، اغلب صادرکننده «شناسه کلید» (یا kid) را در سرایند JWS/JWT درج می‌کند. کلید به گیرنده JWS/JWT می‌گوید که چگونه کلید عمومی یا رمز لازم برای تأیید امضای JWS/JWT امضاشده را پیدا کند.
به‌عنوان مثال، فرض کنید صادرکننده‌ای یک JWT را با کلید خصوصی امضا می‌کند. «شناسه کلید» کلید عمومی مطابق را برای استفاده در درستی‌سنجی JWT شناسایی می‌کند. فهرست کلیدهای عمومی معمولاً در برخی‌از نقاط پایانی شناخته‌شده دردسترس است، برای مثال: https://www.googleapis.com/oauth2/v3/certs.
این توالی پایه است که Edge (یا هر پلاتفرمی که با JWKS کار می‌کند) باید برای کار با JWS/JWT که JWKS دارد انجام دهد:
- سرصفحه JWS/JWT را بررسی کنید تا «شناسه کلید» (kid) را پیدا کنید.
- سرصفحه JWS/JWT را بررسی کنید تا الگوریتم امضا (alg) را پیدا کنید، مثلاً RS256.
- فهرست کلیدها و شناسه‌ها را از JWKS نقطه پایانی شناخته‌شده برای صادرکننده معین بازیابی کنید.
- کلید عمومی را از فهرست کلیدها با شناسه کلید ذکرشده در سرایند JWS/JWT استخراج کنید و درصورت مشخص کردن الگوریتم توسط کلید JWKS، الگوریتم مطابقت را استخراج کنید.
- از آن کلید عمومی برای درستی‌سنجی امضای JWS/JWT استفاده کنید.
به‌عنوان توسعه‌دهنده پراکسی Edge API، برای انجام درستی‌سنجی JWS/JWT باید کارهای زیر را انجام دهید:
- فهرست کلیدها و شناسه‌ها را از نقطه پایانی شناخته‌شده برای صادرکننده معینی بازیابی کنید. می‌توانید از خط‌مشی «خدمات پیامک» برای این مرحله استفاده کنید.
- در خط‌مشی «درستی‌سنجی JWS/JWT»، مکان JWS/JWT را در عنصر
<Source>و بار JWKS را در عنصر<PublicKey/JWKS>مشخص کنید. برای مثال، برای خط‌مشی VerifyJWT:<VerifyJWT name="JWT-Verify-RS256"> <Algorithm>RS256</Algorithm> <Source>json.jwt</Source> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <PublicKey> <JWKS ref="public.jwks"/> </PublicKey> <Subject>apigee-seattle-hatrack-montage</Subject> <Issuer>urn://apigee-edge-JWT-policy-test</Issuer> <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience> <AdditionalClaims> <Claim name="show">And now for something completely different.</Claim> </AdditionalClaims> </VerifyJWT>
خط‌مشی «درستی‌سنجی JWT» همه کارهای دیگر را انجام می‌دهد:
- اگر کلیدی با «شناسه کلید» که با «شناسه کلید» (kid) ادعاشده در JWT مطابقت داشته باشد در JWKS پیدا نشود، خطای خط‌مشی «درستی‌سنجی JWT» صادر می‌شود و JWT درستی‌سنجی نمی‌شود.
- اگر JWT ورودی در سرایند خود شناسه کلید (kid) نداشته باشد، این نگاشت شناسه کلید به کلید درستی‌سنجی امکان‌پذیر نیست.
به‌عنوان طراح پراکسی، مسئولیت تعیین کلید مورد استفاده برعهده شما است؛ در برخی موارد، این کلید ممکن است یک کلید ثابت و کدبندی‌شده باشد.