شما در حال مشاهده اسناد Apigee Edge هستید.
به مستندات Apigee X بروید . اطلاعات
چی
امضای JWT دریافت شده از مشتریان یا سایر سیستم ها را تأیید می کند. این خطمشی همچنین ادعاها را در متغیرهای زمینه استخراج میکند تا سیاستها یا شرایط بعدی بتوانند آن مقادیر را برای تصمیمگیری مجوز یا مسیریابی بررسی کنند. برای معرفی دقیق ، مرور کلی سیاست های JWS و JWT را ببینید.
وقتی این سیاست اجرا میشود، Edge امضای یک JWT را تأیید میکند، و تأیید میکند که JWT مطابق با زمانهای انقضا و در صورت وجود آنها، معتبر است. این خطمشی میتواند بهصورت اختیاری ارزش ادعاهای خاص در JWT، مانند موضوع، صادرکننده، مخاطب یا ارزش ادعاهای اضافی را تأیید کند.
اگر JWT تأیید و معتبر باشد، تمام ادعاهای موجود در JWT برای استفاده در خطمشیها یا شرایط بعدی در متغیرهای زمینه استخراج میشوند و به درخواست اجازه ادامه داده میشود. اگر امضای JWT نمی تواند تأیید شود یا اگر JWT به دلیل یکی از مهرهای زمانی نامعتبر باشد، تمام پردازش متوقف می شود و یک خطا در پاسخ باز می گردد.
برای آشنایی با قطعات یک JWT و نحوه رمزگذاری و امضای آنها، به RFC7519 مراجعه کنید.
ویدیو
برای یادگیری نحوه تأیید امضا در JWT، یک ویدیوی کوتاه تماشا کنید.
نمونه ها
JWT امضا شده با الگوریتم HS256 را تأیید کنید
این خط مشی مثال یک JWT را تأیید می کند که با الگوریتم رمزگذاری HS256، HMAC با استفاده از یک جمع کنترل SHA-256 امضا شده است. JWT در درخواست پراکسی با استفاده از پارامتر فرم به نام jwt ارسال می شود. کلید در متغیری به نام private.secretkey قرار دارد. برای مثال کامل، از جمله نحوه درخواست از خط مشی، ویدیوی بالا را ببینید.
پیکربندی خط مشی شامل اطلاعاتی است که Edge برای رمزگشایی و ارزیابی JWT نیاز دارد، مانند مکان یافتن JWT (در متغیر جریان مشخص شده در عنصر Source)، الگوریتم امضای مورد نیاز، مکان یافتن کلید مخفی (ذخیره شده در یک Edge). متغیر جریان، که میتوانست برای مثال از Edge KVM بازیابی شود)، و مجموعهای از ادعاهای مورد نیاز و مقادیر آنها.
<VerifyJWT name="JWT-Verify-HS256">
<DisplayName>JWT Verify HS256</DisplayName>
<Algorithm>HS256</Algorithm>
<Source>request.formparam.jwt</Source>
<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
<SecretKey encoding="base64">
<Value ref="private.secretkey"/>
</SecretKey>
<Subject>monty-pythons-flying-circus</Subject>
<Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
<Audience>fans</Audience>
<AdditionalClaims>
<Claim name="show">And now for something completely different.</Claim>
</AdditionalClaims>
</VerifyJWT>خط مشی خروجی خود را روی متغیرهای زمینه می نویسد تا سیاست ها یا شرایط بعدی در پراکسی API بتوانند آن مقادیر را بررسی کنند. برای لیستی از متغیرهای تنظیم شده توسط این خط مشی، متغیرهای جریان را ببینید.
JWT امضا شده با الگوریتم RS256 را تأیید کنید
این خط مشی مثال یک JWT را تأیید می کند که با الگوریتم RS256 امضا شده است. برای تأیید، باید کلید عمومی را ارائه دهید. JWT در درخواست پراکسی با استفاده از پارامتر فرم به نام jwt ارسال می شود. کلید عمومی در متغیری به نام public.publickey قرار دارد. برای مثال کامل، از جمله نحوه درخواست از خط مشی، ویدیوی بالا را ببینید.
برای جزئیات بیشتر در مورد الزامات و گزینههای هر عنصر در این خطمشی نمونه، به مرجع عنصر مراجعه کنید.
<VerifyJWT name="JWT-Verify-RS256">
<Algorithm>RS256</Algorithm>
<Source>request.formparam.jwt</Source>
<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
<PublicKey>
<Value ref="public.publickey"/>
</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 با این هدر…
{
"typ" : "JWT",
"alg" : "RS256"
}و این محموله…
{
"sub" : "apigee-seattle-hatrack-montage",
"iss" : "urn://apigee-edge-JWT-policy-test",
"aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
"show": "And now for something completely different."
}اگر بتوان امضا را با کلید عمومی ارائه شده تأیید کرد، … معتبر تلقی خواهد شد.
یک JWT با هدر یکسان اما با این بار…
{
"sub" : "monty-pythons-flying-circus",
"iss" : "urn://apigee-edge-JWT-policy-test",
"aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
"show": "And now for something completely different."
}… نامعتبر است، حتی اگر امضا قابل تأیید باشد، زیرا ادعای «sub» موجود در JWT با مقدار لازم عنصر «موضوع» که در پیکربندی خطمشی مشخص شده مطابقت ندارد.
خط مشی خروجی خود را روی متغیرهای زمینه می نویسد تا سیاست ها یا شرایط بعدی در پراکسی API بتوانند آن مقادیر را بررسی کنند. برای لیستی از متغیرهای تنظیم شده توسط این خط مشی، متغیرهای جریان را ببینید.
تنظیم عناصر کلیدی
عناصری که برای تعیین کلید مورد استفاده برای تأیید JWT استفاده می کنید به الگوریتم انتخابی بستگی دارد، همانطور که در جدول زیر نشان داده شده است:
| الگوریتم | عناصر کلیدی | |
|---|---|---|
| HS* | <SecretKey encoding="base16|hex|base64|base64url"> <Value ref="private.secretkey"/> </SecretKey> | |
| RS*، ES*، PS* | <PublicKey> <Value ref="rsa_public_key_or_value"/> </PublicKey> یا: <PublicKey> <Certificate ref="signed_cert_val_ref"/> </PublicKey> یا: <PublicKey> <JWKS ref="jwks_val_or_ref"/> </PublicKey> | |
| * برای اطلاعات بیشتر در مورد الزامات کلیدی، درباره الگوریتمهای رمزگذاری امضا را ببینید. | ||
مرجع عنصر
مرجع خط مشی عناصر و ویژگی های خط مشی Verify JWT را توصیف می کند.
توجه: پیکربندی بسته به الگوریتم رمزگذاری مورد استفاده شما تا حدودی متفاوت خواهد بود. برای نمونه هایی که پیکربندی ها را برای موارد استفاده خاص نشان می دهد، به نمونه ها مراجعه کنید.
ویژگی هایی که برای عنصر سطح بالا اعمال می شود
<VerifyJWT name="JWT" continueOnError="false" enabled="true" async="false">
ویژگی های زیر برای همه عناصر اصلی خط مشی مشترک است.
| صفت | توضیحات | پیش فرض | حضور |
|---|---|---|---|
| نام | نام داخلی سیاست. نویسه هایی که می توانید در نام استفاده کنید محدود به: A-Z0-9._\-$ % . با این حال، رابط کاربری مدیریت Edge محدودیتهای بیشتری را اعمال میکند، مانند حذف خودکار کاراکترهایی که حروف عددی نیستند. به صورت اختیاری، از عنصر | N/A | مورد نیاز |
| continueOnError | برای بازگرداندن خطا در صورت شکست خط مشی، روی false تنظیم کنید. این رفتار مورد انتظار برای اکثر سیاست ها است. روی | نادرست | اختیاری |
| فعال شد | برای اجرای خط مشی روی true تنظیم کنید. برای "خاموش کردن" خط مشی، روی | درست است | اختیاری |
| ناهمگام | این ویژگی منسوخ شده است. | نادرست | منسوخ شده است |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
علاوه بر ویژگی نام، برای برچسبگذاری خطمشی در ویرایشگر پروکسی رابط کاربری مدیریت با نامی متفاوت و به زبان طبیعی، از آن استفاده کنید.
| پیش فرض | اگر این عنصر را حذف کنید، از مقدار ویژگی نام خط مشی استفاده می شود. |
| حضور | اختیاری |
| تایپ کنید | رشته |
<الگوریتم>
<Algorithm>HS256</Algorithm>
الگوریتم رمزگذاری را برای امضای توکن مشخص می کند. الگوریتمهای RS*/PS*/ES* از یک جفت کلید عمومی/مخفی استفاده میکنند، در حالی که الگوریتمهای HS* از یک راز مشترک استفاده میکنند. درباره الگوریتمهای رمزگذاری امضا نیز ببینید.
می توانید چندین مقدار را مشخص کنید که با کاما از هم جدا شده اند. به عنوان مثال "HS256, HS512" یا "RS256, PS256". با این حال، نمیتوانید الگوریتمهای HS* را با سایر الگوریتمها یا الگوریتمهای ES* را با سایر الگوریتمها ترکیب کنید، زیرا به نوع خاصی از کلید نیاز دارند. می توانید الگوریتم های RS* و PS* را ترکیب کنید.
| پیش فرض | N/A |
| حضور | مورد نیاز |
| تایپ کنید | رشته ای از مقادیر جدا شده با کاما |
| مقادیر معتبر | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 |
<مخاطب>
<Audience>audience-here</Audience> or: <Audience ref='variable-name-here'/>
این خطمشی تأیید میکند که ادعای مخاطب در JWT با مقدار مشخصشده در پیکربندی مطابقت دارد. اگر مطابقت وجود نداشته باشد، خط مشی خطایی ایجاد می کند. این ادعا گیرندگانی را که JWT برای آنها در نظر گرفته شده است مشخص می کند. این یکی از ادعاهای ثبت شده در RFC7519 است.
| پیش فرض | N/A |
| حضور | اختیاری |
| تایپ کنید | رشته |
| مقادیر معتبر | یک متغیر جریان یا رشته ای که مخاطب را شناسایی می کند. |
<AdditionalClaims/Claim>
<AdditionalClaims> <Claim name='claim1'>explicit-value-of-claim-here</Claim> <Claim name='claim2' ref='variable-name-here'/> <Claim name='claim3' ref='variable-name-here' type='boolean'/> </AdditionalClaims> or: <AdditionalClaims ref='claim_payload'/>
تأیید می کند که بار JWT حاوی ادعای(های) اضافی مشخص شده است و مقادیر ادعای ادعا شده مطابقت دارند.
یک ادعای اضافی از نامی استفاده می کند که یکی از نام های استاندارد و ثبت شده ادعای JWT نیست. مقدار یک ادعای اضافی می تواند یک رشته، یک عدد، یک بولی، یک نقشه یا یک آرایه باشد. نقشه به سادگی مجموعه ای از جفت نام/مقدار است. مقدار ادعای هر یک از این انواع را می توان به صراحت در پیکربندی خط مشی یا به طور غیرمستقیم از طریق ارجاع به متغیر جریان مشخص کرد.
| پیش فرض | N/A |
| حضور | اختیاری |
| تایپ کنید | رشته، عدد، بولی یا نقشه |
| آرایه | برای نشان دادن اینکه آیا مقدار آرایه ای از انواع است، روی true تنظیم کنید. پیش فرض: نادرست |
| مقادیر معتبر | هر مقداری که می خواهید برای ادعای اضافی استفاده کنید. |
عنصر <Claim> این ویژگی ها را می گیرد:
- نام - (لازم) نام ادعا.
- ref - (اختیاری) نام یک متغیر جریان. در صورت وجود، خط مشی از مقدار این متغیر به عنوان ادعا استفاده می کند. اگر هم یک ویژگی ref و هم مقدار ادعای صریح مشخص شده باشد، مقدار صریح پیشفرض است و اگر متغیر جریان ارجاعشده حل نشده باشد استفاده میشود.
- نوع - (اختیاری) یکی از: رشته (پیشفرض)، عدد، بولی یا نقشه
- آرایه - (اختیاری) برای نشان دادن اینکه آیا مقدار آرایه ای از انواع است، روی true تنظیم کنید. پیش فرض: نادرست.
وقتی عنصر <Claim> وارد میکنید، هنگام پیکربندی خطمشی، نام ادعاها به صورت ایستا تنظیم میشوند. همچنین، میتوانید یک شی JSON را برای تعیین نام ادعا ارسال کنید. از آنجا که شی JSON به عنوان یک متغیر ارسال می شود، نام ادعا در زمان اجرا تعیین می شود.
به عنوان مثال:
<AdditionalClaims ref='json_claims'/>
جایی که متغیر json_claims حاوی یک شی JSON به شکل زیر است:
{ "sub" : "person@example.com", "iss" : "urn://secure-issuer@example.com", "non-registered-claim" : { "This-is-a-thing" : 817, "https://example.com/foobar" : { "p": 42, "q": false } } }
<AdditionalHeaders/Claim>
<AdditionalHeaders> <Claim name='claim1'>explicit-value-of-claim-here</Claim> <Claim name='claim2' ref='variable-name-here'/> <Claim name='claim3' ref='variable-name-here' type='boolean'/> <Claim name='claim4' ref='variable-name' type='string' array='true'/> </AdditionalHeaders>
تأیید می کند که سرصفحه JWT شامل جفت(های) نام/مقدار ادعای اضافی مشخص شده است و مقادیر ادعای ادعا شده مطابقت دارند.
یک ادعای اضافی از نامی استفاده می کند که یکی از نام های استاندارد و ثبت شده ادعای JWT نیست. مقدار یک ادعای اضافی می تواند یک رشته، یک عدد، یک بولی، یک نقشه یا یک آرایه باشد. نقشه به سادگی مجموعه ای از جفت نام/مقدار است. مقدار ادعای هر یک از این انواع را می توان به صراحت در پیکربندی خط مشی یا به طور غیرمستقیم از طریق ارجاع به متغیر جریان مشخص کرد.
| پیش فرض | N/A |
| حضور | اختیاری |
| تایپ کنید | رشته (پیشفرض)، عدد، بولی یا نقشه. در صورتی که هیچ نوع مشخصی نداشته باشد، نوع پیشفرض روی رشته است. |
| آرایه | برای نشان دادن اینکه آیا مقدار آرایه ای از انواع است، روی true تنظیم کنید. پیش فرض: نادرست |
| مقادیر معتبر | هر مقداری که می خواهید برای ادعای اضافی استفاده کنید. |
عنصر <Claim> این ویژگی ها را می گیرد:
- نام - (لازم) نام ادعا.
- ref - (اختیاری) نام یک متغیر جریان. در صورت وجود، خط مشی از مقدار این متغیر به عنوان ادعا استفاده می کند. اگر هم یک ویژگی ref و هم مقدار ادعای صریح مشخص شده باشد، مقدار صریح پیشفرض است و اگر متغیر جریان ارجاعشده حل نشده باشد استفاده میشود.
- نوع - (اختیاری) یکی از: رشته (پیشفرض)، عدد، بولی یا نقشه
- آرایه - (اختیاری) برای نشان دادن اینکه آیا مقدار آرایه ای از انواع است، روی true تنظیم کنید. پیش فرض: نادرست.
<CustomClaims>
توجه: در حال حاضر، وقتی یک خطمشی GenerateJWT جدید را از طریق UI اضافه میکنید، یک عنصر CustomClaims درج میشود. این عنصر کاربردی نیست و نادیده گرفته می شود. عنصر صحیح برای استفاده در عوض <AdditionalClaims> است. رابط کاربری برای درج عناصر صحیح در فرصتی دیگر به روز می شود.
<Id>
<Id>explicit-jti-value-here</Id> -or- <Id ref='variable-name-here'/> -or- <Id/>
تأیید می کند که JWT ادعای jti خاص را دارد. وقتی مقدار متن و ویژگی ref هر دو خالی باشند، این خط مشی یک jti حاوی یک UUID تصادفی ایجاد می کند. ادعای JWT ID (jti) یک شناسه منحصر به فرد برای JWT است. برای اطلاعات بیشتر در مورد jti، به RFC7519 مراجعه کنید.
| پیش فرض | N/A |
| حضور | اختیاری |
| تایپ کنید | رشته یا مرجع. |
| مقادیر معتبر | یک رشته یا نام یک متغیر جریان حاوی شناسه. |
<IgnoreCriticalHeaders>
<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>
اگر میخواهید وقتی هر هدر فهرست شده در هدر crit JWT در عنصر <KnownHeaders> فهرست نشده است، خطمشی خطا ایجاد کند، روی false تنظیم کنید. روی true تنظیم کنید تا باعث شود خط مشی VerifyJWT هدر crit را نادیده بگیرد.
یکی از دلایل تنظیم این عنصر بر روی true این است که اگر در یک محیط آزمایشی هستید و هنوز آماده نیستید که یک هدر از دست رفته را خراب کنید.
| پیش فرض | نادرست |
| حضور | اختیاری |
| تایپ کنید | بولی |
| مقادیر معتبر | درست یا نادرست |
<IgnoreIssuedAt>
<IgnoreIssuedAt>true|false</IgnoreIssuedAt>
اگر میخواهید زمانی که یک JWT حاوی یک ادعای iat (در تاریخ صادر شده) است که زمانی را در آینده مشخص میکند، خطمشی خطایی ایجاد کند، روی false (پیشفرض) تنظیم کنید. روی true تنظیم کنید تا باعث شود خط مشی iat را در حین تأیید نادیده بگیرد.
| پیش فرض | نادرست |
| حضور | اختیاری |
| تایپ کنید | بولی |
| مقادیر معتبر | درست یا نادرست |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
اگر میخواهید وقتی هر متغیر ارجاعی مشخصشده در خطمشی غیرقابل حل است، خطمشی خطایی ایجاد کند، روی false تنظیم کنید. مقدار true را تنظیم کنید تا هر متغیر غیرقابل حلی را به عنوان یک رشته خالی (تهی) در نظر بگیرید.
| پیش فرض | نادرست |
| حضور | اختیاری |
| تایپ کنید | بولی |
| مقادیر معتبر | درست یا نادرست |
<صادر کننده>
<Issuer ref='variable-name-here'/> <Issuer>issuer-string-here</Issuer>
خط مشی تأیید می کند که صادرکننده در JWT با رشته مشخص شده در عنصر پیکربندی مطابقت دارد. ادعایی که صادرکننده JWT را مشخص می کند. این یکی از مجموعه ادعاهای ثبت شده ذکر شده در RFC7519 است.
| پیش فرض | N/A |
| حضور | اختیاری |
| تایپ کنید | رشته یا مرجع |
| مقادیر معتبر | هر |
<KnownHeaders>
<KnownHeaders>a,b,c</KnownHeaders> or: <KnownHeaders ref=’variable_containing_headers’/>
خط مشی GenerateJWT از عنصر <CriticalHeaders> برای پر کردن هدر crit در JWT استفاده می کند. به عنوان مثال:
{
“typ: “...”,
“alg” : “...”,
“crit” : [ “a”, “b”, “c” ],
}خط مشی VerifyJWT سرصفحه کریت را در JWT بررسی می کند، در صورت وجود، و برای هر هدر فهرست شده بررسی می کند که عنصر <KnownHeaders> آن هدر را نیز فهرست کند. عنصر <KnownHeaders> میتواند شامل یک ابر مجموعه از موارد فهرست شده در crit باشد. فقط لازم است که تمام هدرهای فهرست شده در crit در عنصر <KnownHeaders> فهرست شوند. هر هدری که خطمشی در کریت پیدا میکند و در <KnownHeaders> نیز فهرست نشده است باعث میشود که خطمشی VerifyJWT با شکست مواجه شود.
با تنظیم عنصر <IgnoreCriticalHeaders> روی true میتوانید بهطور اختیاری خطمشی VerifyJWT را برای نادیده گرفتن هدر کریت پیکربندی کنید.
| پیش فرض | N/A |
| حضور | اختیاری |
| تایپ کنید | آرایه رشته ها با کاما جدا شده است |
| مقادیر معتبر | یک آرایه یا نام یک متغیر حاوی آرایه. |
<PublicKey/Certificate>
<PublicKey> <Certificate ref="signed_public.cert"/> </PublicKey> -or- <PublicKey> <Certificate> -----BEGIN CERTIFICATE----- cert data -----END CERTIFICATE----- </Certificate> </PublicKey>
گواهی امضا شده مورد استفاده برای تأیید امضا در JWT را مشخص می کند. از ویژگی ref برای ارسال گواهی امضا شده در یک متغیر جریان استفاده کنید، یا گواهی رمزگذاری شده با PEM را مستقیماً مشخص کنید. فقط زمانی استفاده کنید که الگوریتم یکی از RS256/RS384/RS512، PS256/PS384/PS512، یا ES256/ES384/ES512 باشد.
| پیش فرض | N/A |
| حضور | برای تأیید یک JWT امضا شده با الگوریتم RSA، باید از عناصر Certificate، JWKS یا Value استفاده کنید. |
| تایپ کنید | رشته |
| مقادیر معتبر | یک متغیر جریان یا رشته. |
<PublicKey/JWKS>
<!-- Specify the JWKS. --> <PublicKey> <JWKS>jwks-value-here</JWKS> </PublicKey> or: <!-- Specify a variable containing the JWKS. --> <PublicKey> <JWKS ref="public.jwks"/> </PublicKey> or: <!-- Specify a public URL that returns the JWKS. The URL is static, meaning you cannot set it using a variable. --> <PublicKey> <JWKS uri="jwks-url"/> </PublicKey>
مقداری را در قالب JWKS ( RFC 7517 ) که حاوی مجموعه ای از کلیدهای عمومی است، مشخص می کند. فقط زمانی استفاده کنید که الگوریتم یکی از RS256/RS384/RS512، PS256/PS384/PS512، یا ES256/ES384/ES512 باشد.
اگر JWT ورودی دارای شناسه کلیدی باشد که در مجموعه JWKS وجود دارد، خطمشی از کلید عمومی صحیح برای تأیید امضای JWT استفاده میکند. برای جزئیات بیشتر درباره این ویژگی، به استفاده از مجموعه کلیدهای وب JSON (JWKS) برای تأیید JWT مراجعه کنید.
اگر مقدار را از یک URL عمومی دریافت کنید، Edge JWKS را برای مدت 300 ثانیه در حافظه پنهان نگه می دارد. هنگامی که حافظه پنهان منقضی می شود، Edge دوباره JWKS را واکشی می کند.
| پیش فرض | N/A |
| حضور | برای تأیید یک JWT با استفاده از الگوریتم RSA، باید از عنصر Certificate، JWKS یا Value استفاده کنید. |
| تایپ کنید | رشته |
| مقادیر معتبر | یک متغیر جریان، مقدار رشته یا URL. |
<PublicKey/Value>
<PublicKey> <Value ref="public.publickeyorcert"/> </PublicKey> -or- <PublicKey> <Value> -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2 ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx DQIDAQAB -----END PUBLIC KEY----- </Value> </PublicKey>
کلید عمومی یا گواهی عمومی مورد استفاده برای تأیید امضا در JWT را مشخص می کند. از ویژگی ref برای ارسال کلید/گواهی در متغیر جریان استفاده کنید یا کلید رمزگذاری شده PEM را مستقیماً مشخص کنید. فقط زمانی استفاده کنید که الگوریتم یکی از RS256/RS384/RS512، PS256/PS384/PS512، یا ES256/ES384/ES512 باشد.
| پیش فرض | N/A |
| حضور | برای تأیید یک JWT امضا شده با الگوریتم RSA، باید از عناصر Certificate، JWKS یا Value استفاده کنید. |
| تایپ کنید | رشته |
| مقادیر معتبر | یک متغیر جریان یا رشته. |
<SecretKey/Value>
<SecretKey encoding="base16|hex|base64|base64url"> <Value ref="private.your-variable-name"/> </SecretKey>
کلید مخفی مورد استفاده برای تأیید یا امضای نشانه ها با الگوریتم HMAC را ارائه می دهد. فقط زمانی استفاده کنید که الگوریتم یکی از HS256، HS384، HS512 باشد. .
| پیش فرض | N/A |
| حضور | برای الگوریتم های HMAC مورد نیاز است. |
| تایپ کنید | رشته |
| مقادیر معتبر | برای از ویژگی ref برای ارسال کلید در متغیر جریان استفاده کنید. نکته: اگر یک متغیر جریان باشد، باید پیشوند "خصوصی" داشته باشد. مثلا |
<منبع>
<Source>jwt-variable</Source>
در صورت وجود، متغیر جریانی را مشخص می کند که در آن خط مشی انتظار دارد JWT را برای تأیید پیدا کند.
| پیش فرض | request.header.authorization (برای اطلاعات مهم در مورد پیش فرض به یادداشت بالا مراجعه کنید). |
| حضور | اختیاری |
| تایپ کنید | رشته |
| مقادیر معتبر | نام متغیر جریان لبه. |
<موضوع>
<Subject>subject-string-here</Subject>
خط مشی تأیید می کند که موضوع در JWT با رشته مشخص شده در پیکربندی خط مشی مطابقت دارد. این ادعا موضوع JWT را شناسایی یا بیان می کند. این یکی از مجموعه استاندارد ادعاهای ذکر شده در RFC7519 است.
| پیش فرض | N/A |
| حضور | اختیاری |
| تایپ کنید | رشته |
| مقادیر معتبر | هر ارزشی که به طور منحصر به فرد یک موضوع را شناسایی می کند. |
<TimeAllowance>
<TimeAllowance>120s</TimeAllowance>
"دوره مهلت" برای زمان ها. بهعنوان مثال، اگر زمان مجاز روی 60 ثانیه پیکربندی شده باشد، یک JWT منقضی شده همچنان معتبر است، تا 60 ثانیه پس از انقضای اعلام شده. زمان غیر قبل نیز به همین ترتیب ارزیابی خواهد شد. پیشفرض 0 ثانیه (بدون مهلت).
| پیش فرض | 0 ثانیه (بدون مهلت) |
| حضور | اختیاری |
| تایپ کنید | رشته |
| مقادیر معتبر | یک مقدار یا یک مرجع به یک متغیر جریان حاوی مقدار. بازه های زمانی را می توان به صورت زیر مشخص کرد:
|
Flow variables
Upon success, the Verify JWT and Decode JWT policies set context variables according to this pattern:
jwt.{policy_name}.{variable_name}
For example, if the policy name is jwt-parse-token , then the policy will store
the subject specified in the JWT to the context variable named jwt.jwt-parse-token.decoded.claim.sub.
(For backward compatibility, it will also be available in jwt.jwt-parse-token.claim.subject)
| Variable name | Description |
|---|---|
claim.audience |
The JWT audience claim. This value may be a string, or an array of strings. |
claim.expiry |
The expiration date/time, expressed in milliseconds since epoch. |
claim.issuedat |
The Date the token was issued, expressed in milliseconds since epoch. |
claim.issuer |
The JWT issuer claim. |
claim.notbefore |
If the JWT includes a nbf claim, this variable will contain the value, expressed in milliseconds since epoch. |
claim.subject |
The JWT subject claim. |
claim.name |
The value of the named claim (standard or additional) in the payload. One of these will be set for every claim in the payload. |
decoded.claim.name |
The JSON-parsable value of the named claim (standard or additional) in the payload. One variable is set for
every claim in the payload. For example, you can use decoded.claim.iat to
retrieve the issued-at time of the JWT, expressed in seconds since epoch. While you
can also use the claim.name flow variables, this is the
recommended variable to use to access a claim. |
decoded.header.name |
The JSON-parsable value of a header in the payload. One variable is set for
every header in the payload. While you can also use the header.name flow variables,
this is the recommended variable to use to access a header. |
expiry_formatted |
The expiration date/time, formatted as a human-readable string. Example: 2017-09-28T21:30:45.000+0000 |
header.algorithm |
The signing algorithm used on the JWT. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more. |
header.kid |
The Key ID, if added when the JWT was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT policies overview to verify a JWT. See (Key ID) Header Parameter for more. |
header.type |
Will be set to JWT. |
header.name |
The value of the named header (standard or additional). One of these will be set for every additional header in the header portion of the JWT. |
header-json |
The header in JSON format. |
is_expired |
true or false |
payload-claim-names |
An array of claims supported by the JWT. |
payload-json |
The payload in JSON format.
|
seconds_remaining |
The number of seconds before the token will expire. If the token is expired, this number will be negative. |
time_remaining_formatted |
The time remaining before the token will expire, formatted as a human-readable string. Example: 00:59:59.926 |
valid |
In the case of VerifyJWT, this variable will be true when the signature is verified, and
the current time is before the token expiry, and after the token notBefore value, if they
are present. Otherwise false.
In the case of DecodeJWT, this variable is not set. |
مرجع خطا
این بخش کدهای خطا و پیامهای خطایی را که برگردانده میشوند و متغیرهای خطا را که توسط Edge تنظیم میشوند، هنگامی که این خطمشی خطا را راهاندازی میکند، توضیح میدهد. این اطلاعات برای دانستن اینکه آیا در حال توسعه قوانین خطا برای رسیدگی به خطاها هستید، مهم است. برای کسب اطلاعات بیشتر، آنچه را که باید در مورد خطاهای خط مشی و مدیریت خطاها بدانید را ببینید.
خطاهای زمان اجرا
این خطاها ممکن است هنگام اجرای سیاست رخ دهند.
| کد خطا | وضعیت HTTP | زمانی رخ می دهد |
|---|---|---|
steps.jwt.AlgorithmInTokenNotPresentInConfiguration | 401 | زمانی رخ می دهد که خط مشی تأیید چندین الگوریتم داشته باشد. |
steps.jwt.AlgorithmMismatch | 401 | الگوریتم مشخصشده در خطمشی Generate با الگوریتم مورد انتظار در خطمشی تأیید مطابقت نداشت. الگوریتم های مشخص شده باید مطابقت داشته باشند. |
steps.jwt.FailedToDecode | 401 | این خط مشی قادر به رمزگشایی JWT نبود. JWT احتمالاً خراب است. |
steps.jwt.GenerationFailed | 401 | این سیاست قادر به ایجاد JWT نبود. |
steps.jwt.InsufficientKeyLength | 401 | برای یک کلید کمتر از 32 بایت برای الگوریتم HS256، کمتر از 48 بایت برای الگوریتم HS386، و کمتر از 64 بایت برای الگوریتم HS512. |
steps.jwt.InvalidClaim | 401 | برای ادعای مفقود یا عدم تطابق ادعا، یا عدم تطابق سرصفحه یا سرصفحه. |
steps.jwt.InvalidCurve | 401 | منحنی مشخص شده توسط کلید برای الگوریتم منحنی بیضی معتبر نیست. |
steps.jwt.InvalidJsonFormat | 401 | JSON نامعتبر در هدر یا محموله یافت شد. |
steps.jwt.InvalidToken | 401 | این خطا زمانی رخ می دهد که تأیید امضای JWT ناموفق باشد. |
steps.jwt.JwtAudienceMismatch | 401 | ادعای مخاطب در راستیآزمایی رمز شکست خورد. |
steps.jwt.JwtIssuerMismatch | 401 | ادعای صادرکننده در تأیید توکن ناموفق بود. |
steps.jwt.JwtSubjectMismatch | 401 | ادعای موضوع در تأیید رمز شکست خورد. |
steps.jwt.KeyIdMissing | 401 | خطمشی تأیید از یک JWKS به عنوان منبع کلیدهای عمومی استفاده میکند، اما JWT امضاشده دارای ویژگی kid در سرصفحه نیست. |
steps.jwt.KeyParsingFailed | 401 | کلید عمومی از اطلاعات کلید داده شده قابل تجزیه نیست. |
steps.jwt.NoAlgorithmFoundInHeader | 401 | زمانی اتفاق میافتد که JWT فاقد سربرگ الگوریتم باشد. |
steps.jwt.NoMatchingPublicKey | 401 | خطمشی تأیید از یک JWKS به عنوان منبع کلیدهای عمومی استفاده میکند، اما kid در JWT امضا شده در JWKS فهرست نشده است. |
steps.jwt.SigningFailed | 401 | در GenerateJWT، برای کلیدی کمتر از حداقل اندازه الگوریتمهای HS384 یا HS512 |
steps.jwt.TokenExpired | 401 | این خطمشی تلاش میکند تا یک توکن منقضی شده را تأیید کند. |
steps.jwt.TokenNotYetValid | 401 | رمز هنوز معتبر نیست. |
steps.jwt.UnhandledCriticalHeader | 401 | سرصفحه ای که توسط خط مشی Verify JWT در سرصفحه crit یافت شده است در KnownHeaders فهرست نشده است. |
steps.jwt.UnknownException | 401 | یک استثنا ناشناخته رخ داد. |
steps.jwt.WrongKeyType | 401 | نوع کلید اشتباه مشخص شده است. به عنوان مثال، اگر یک کلید RSA برای یک الگوریتم منحنی بیضی یا یک کلید منحنی برای یک الگوریتم RSA مشخص کنید. |
خطاهای استقرار
این خطاها ممکن است زمانی رخ دهند که یک پروکسی حاوی این خط مشی را مستقر می کنید.
| نام خطا | علت | ثابت |
|---|---|---|
InvalidNameForAdditionalClaim | اگر ادعای مورد استفاده در عنصر فرزند <Claim> عنصر <AdditionalClaims> یکی از نامهای ثبتشده زیر باشد، استقرار ناموفق خواهد بود: kid ، iss ، sub ، aud ، iat ، exp ، nbf ، یا jti . | build |
InvalidTypeForAdditionalClaim | اگر ادعای استفاده شده در عنصر فرزند <Claim> عنصر <AdditionalClaims> از نوع string ، number ، boolean یا map نباشد، استقرار با شکست مواجه خواهد شد. | build |
MissingNameForAdditionalClaim | اگر نام ادعا در عنصر فرزند <Claim> عنصر <AdditionalClaims> مشخص نشده باشد، استقرار با شکست مواجه خواهد شد. | build |
InvalidNameForAdditionalHeader | این خطا زمانی رخ می دهد که نام ادعای مورد استفاده در عنصر فرزند <Claim> عنصر <AdditionalClaims> alg یا typ باشد. | build |
InvalidTypeForAdditionalHeader | اگر نوع ادعای استفاده شده در عنصر فرزند <Claim> عنصر <AdditionalClaims> از نوع string ، number ، boolean یا map نباشد، استقرار با شکست مواجه خواهد شد. | build |
InvalidValueOfArrayAttribute | این خطا زمانی رخ می دهد که مقدار ویژگی آرایه در عنصر فرزند <Claim> عنصر <AdditionalClaims> روی true یا false تنظیم نشده باشد. | build |
InvalidValueForElement | اگر مقدار مشخص شده در عنصر <Algorithm> یک مقدار پشتیبانی نشده باشد، استقرار با شکست مواجه خواهد شد. | build |
MissingConfigurationElement | اگر عنصر <PrivateKey> با الگوریتم های خانواده RSA استفاده نشود یا عنصر <SecretKey> با الگوریتم های خانواده HS استفاده نشود، این خطا رخ می دهد. | build |
InvalidKeyConfiguration | اگر عنصر فرزند <Value> در عناصر <PrivateKey> یا <SecretKey> تعریف نشده باشد، استقرار با شکست مواجه خواهد شد. | build |
EmptyElementForKeyConfiguration | اگر ویژگی ref عنصر فرزند <Value> از عناصر <PrivateKey> یا <SecretKey> خالی یا نامشخص باشد، استقرار با شکست مواجه خواهد شد. | build |
InvalidConfigurationForVerify | اگر عنصر <Id> در عنصر <SecretKey> تعریف شده باشد، این خطا رخ می دهد. | build |
InvalidEmptyElement | این خطا در صورتی رخ می دهد که عنصر <Source> از خط مشی Verify JWT خالی باشد. در صورت وجود، باید با نام متغیر Edge flow تعریف شود. | build |
InvalidPublicKeyValue | اگر مقدار استفاده شده در عنصر فرزند <JWKS> عنصر <PublicKey> از قالب معتبری که در RFC 7517 مشخص شده است استفاده نکند، استقرار با شکست مواجه خواهد شد. | build |
InvalidConfigurationForActionAndAlgorithm | اگر عنصر <PrivateKey> با الگوریتم های خانواده HS یا عنصر <SecretKey> با الگوریتم های خانواده RSA استفاده شود، استقرار با شکست مواجه می شود. | build |
متغیرهای خطا
این متغیرها زمانی تنظیم می شوند که یک خطای زمان اجرا رخ دهد. برای اطلاعات بیشتر، به آنچه باید در مورد خطاهای خط مشی بدانید مراجعه کنید.
| متغیرها | کجا | مثال |
|---|---|---|
fault.name=" fault_name " | fault_name نام خطا است، همانطور که در جدول خطاهای Runtime در بالا ذکر شده است. نام خطا آخرین قسمت کد خطا است. | fault.name Matches "TokenExpired" |
JWT.failed | همه خط مشی های JWT متغیرهای یکسانی را در صورت خرابی تنظیم می کنند. | JWT.failed = true |
نمونه پاسخ خطا
برای رسیدگی به خطا، بهترین روش به دام انداختن قسمت errorcode در پاسخ به خطا است. به متن موجود در faultstring تکیه نکنید، زیرا ممکن است تغییر کند.
مثال قانون خطا
<FaultRules>
<FaultRule name="JWT Policy Errors">
<Step>
<Name>JavaScript-1</Name>
<Condition>(fault.name Matches "TokenExpired")</Condition>
</Step>
<Condition>JWT.failed=true</Condition>
</FaultRule>
</FaultRules>