خط مشی DecodeJWS

شما در حال مشاهده مستندات Apigee Edge هستید.
به مستندات Apigee X مراجعه کنید . اطلاعات

چه

هدر JWS را بدون تأیید امضای JWS رمزگشایی می‌کند و هر هدر را در یک متغیر جریان می‌نویسد. این خط‌مشی زمانی بیشترین کاربرد را دارد که با خط‌مشی VerifyJWS هماهنگ استفاده شود، زمانی که مقدار یک هدر از درون JWS باید قبل از تأیید امضای JWS مشخص باشد.

یک JWS می‌تواند یک payload متصل داشته باشد، مانند شکل زیر:

header.payload.signature

یا، JWS می‌تواند payload را حذف کند، که به آن detached payload می‌گویند، و به شکل زیر باشد:

header..signature

سیاست DecodeJWS با هر دو فرم کار می‌کند زیرا فقط بخش هدر JWS را رمزگشایی می‌کند. سیاست DecodeJWS همچنین صرف نظر از الگوریتمی که برای امضای JWS استفاده شده است، کار می‌کند.

برای آشنایی بیشتر با JWS و بررسی اجمالی قالب آن، به بخش «مروری بر سیاست‌های JWS و JWT» مراجعه کنید.

ویدئو

برای یادگیری نحوه رمزگشایی JWT، یک ویدیوی کوتاه تماشا کنید. اگرچه این ویدیو مختص JWT است، اما بسیاری از مفاهیم برای JWS یکسان هستند.

نمونه: رمزگشایی یک JWS

سیاست نشان داده شده در زیر، JWS موجود در متغیر جریان var.JWS را رمزگشایی می‌کند. این متغیر باید وجود داشته باشد و حاوی یک JWS قابل اجرا (قابل رمزگشایی) باشد. این سیاست می‌تواند JWS را از هر متغیر جریانی دریافت کند.

<DecodeJWS name="JWS-Decode-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Source>var.JWS</Source>
</DecodeJWS>

برای هر سربرگ در بخش سربرگ JWS، این سیاست یک متغیر جریان به نام زیر تنظیم می‌کند:

jws.policy-name.header.header-name

اگر JWS یک payload متصل داشته باشد، متغیر جریان jws. policy-name .header.payload را به payload تنظیم می‌کند. برای یک payload جدا شده، payload خالی است. برای لیست کاملی از متغیرهای تنظیم شده توسط این خط‌مشی، به Flow variables مراجعه کنید.

مرجع عنصر برای رمزگشایی JWS

مرجع سیاست، عناصر و ویژگی‌های سیاست Decode JWS را شرح می‌دهد.

ویژگی‌هایی که به عنصر سطح بالا اعمال می‌شوند 

<DecodeJWS name="JWS" continueOnError="false" enabled="true" async="false">

ویژگی‌های زیر برای همه عناصر والد سیاست مشترک هستند.

ویژگی توضیحات پیش‌فرض حضور
نام نام داخلی سیاست. کاراکترهایی که می‌توانید در نام استفاده کنید به موارد زیر محدود شده‌اند: A-Z0-9._\-$ % . با این حال، رابط کاربری مدیریت Edge محدودیت‌های بیشتری را اعمال می‌کند، مانند حذف خودکار کاراکترهایی که الفبایی-عددی نیستند.

در صورت تمایل، از عنصر <displayname></displayname> برای برچسب‌گذاری سیاست در ویرایشگر پروکسی رابط کاربری مدیریت با یک نام متفاوت به زبان طبیعی استفاده کنید.

 ناموجود مورد نیاز
ادامهخطا برای بازگرداندن خطا در صورت عدم موفقیت یک سیاست، روی false تنظیم کنید. این رفتار برای اکثر سیاست‌ها مورد انتظار است.

برای ادامه اجرای جریان حتی پس از شکست یک سیاست، روی true تنظیم شود.

 نادرست اختیاری
فعال شده برای اعمال سیاست، روی true تنظیم کنید.

برای "خاموش کردن" سیاست، روی false تنظیم کنید. این سیاست حتی اگر به یک جریان متصل باقی بماند، اجرا نخواهد شد.

 درست اختیاری
ناهمگام این ویژگی منسوخ شده است. نادرست منسوخ شده

<نام نمایشی> 

<DisplayName>Policy Display Name</DisplayName>

علاوه بر ویژگی نام، از این ویژگی برای برچسب‌گذاری سیاست در ویرایشگر پروکسی رابط کاربری مدیریت با یک نام متفاوت به زبان طبیعی استفاده کنید.

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

<منبع> 

<Source>JWS-variable</Source>

در صورت وجود، متغیر جریانی را مشخص می‌کند که در آن سیاست انتظار دارد JWS را برای رمزگشایی پیدا کند.

پیش‌فرض request.header.authorization (برای اطلاعات مهم در مورد پیش‌فرض، به یادداشت بالا مراجعه کنید).
حضور اختیاری
نوع رشته
مقادیر معتبر نام متغیر جریان لبه

متغیرهای جریان

پس از موفقیت، سیاست های Verify JWS و Decode JWS متغیرهای زمینه را مطابق این الگو تنظیم می کنند:

jws.{policy_name}.{variable_name}

به عنوان مثال، اگر نام خط مشی verify-jws باشد، این خط مشی الگوریتم مشخص شده در JWS را در این متغیر زمینه ذخیره می کند: jws.verify-jws.header.algorithm

نام متغیر توضیحات
decoded.header. name مقدار قابل تجزیه JSON یک هدر در بار. یک متغیر برای هر هدر در محموله تنظیم شده است. در حالی که می توانید از header. name متغیرهای جریان، این متغیر پیشنهادی برای استفاده برای دسترسی به هدر است.
header.algorithm الگوریتم امضای مورد استفاده در JWS. به عنوان مثال، RS256، HS384، و غیره. برای اطلاعات بیشتر به پارامتر سرصفحه (الگوریتم) مراجعه کنید.
header.kid شناسه کلید، اگر هنگام تولید JWS اضافه شود. همچنین به «استفاده از مجموعه کلیدهای وب JSON (JWKS)» در نمای کلی خط‌مشی‌های JWT و JWS برای تأیید JWS مراجعه کنید. برای اطلاعات بیشتر به پارامتر سرصفحه (شناسه کلید) مراجعه کنید.
header.type مقدار نوع سرصفحه برای اطلاعات بیشتر به پارامتر سرصفحه (تایپ) مراجعه کنید.
header. name مقدار هدر نامگذاری شده (استاندارد یا اضافی). یکی از اینها برای هر هدر اضافی در قسمت هدر JWS تنظیم می شود.
header-json هدر با فرمت JSON.
payload محموله JWS اگر JWS دارای محموله متصل باشد. برای بار جدا شده، این متغیر خالی است.
valid در مورد VerifyJWS، این متغیر زمانی درست خواهد بود که امضا تایید شود، و زمان فعلی قبل از انقضای توکن است، و بعد از مقدار notBefore توکن، در صورت وجود. در غیر این صورت نادرست.

در مورد DecodeJWS، این متغیر تنظیم نشده است.

مرجع خطا

این بخش کدهای خطا و پیام‌های خطایی را که برگردانده می‌شوند و متغیرهای خطا را که توسط Edge تنظیم می‌شوند، هنگامی که این خط‌مشی خطا را راه‌اندازی می‌کند، توضیح می‌دهد. این اطلاعات برای دانستن اینکه آیا در حال توسعه قوانین خطا برای رسیدگی به خطاها هستید، مهم است. برای کسب اطلاعات بیشتر، آنچه را که باید در مورد خطاهای خط مشی و مدیریت خطاها بدانید را ببینید.

خطاهای زمان اجرا

این خطاها ممکن است هنگام اجرای سیاست رخ دهند.

کد خطا وضعیت HTTP زمانی رخ می دهد
steps.jws.FailedToDecode 401 این خط مشی قادر به رمزگشایی JWS نبود. JWS احتمالاً خراب است.
steps.jws.FailedToResolveVariable 401 زمانی رخ می دهد که متغیر جریان مشخص شده در عنصر <Source> خط مشی وجود نداشته باشد.
steps.jws.InvalidClaim 401 برای ادعای مفقود یا عدم تطابق ادعا، یا عدم تطابق سرصفحه یا سرصفحه.
steps.jws.InvalidJsonFormat 401 JSON نامعتبر در هدر JWS یافت شد.
steps.jws.InvalidJws 401 این خطا زمانی رخ می دهد که تأیید امضای JWS ناموفق باشد.
steps.jws.InvalidPayload 401 محموله JWS نامعتبر است.
steps.jws.InvalidSignature 401 <DetachedContent> حذف شده است و JWS دارای یک بار محتوای جدا شده است.
steps.jws.MissingPayload 401 محموله JWS وجود ندارد.
steps.jws.NoAlgorithmFoundInHeader 401 زمانی رخ می دهد که JWS سربرگ الگوریتم را حذف کند.
steps.jws.UnknownException 401 یک استثنا ناشناخته رخ داد.

خطاهای استقرار

این خطاها ممکن است زمانی رخ دهند که یک پروکسی حاوی این خط مشی را مستقر می کنید.

نام خطا زمانی رخ می دهد
InvalidAlgorithm تنها مقادیر معتبر عبارتند از: RS256، RS384، RS512، PS256، PS384، PS512، ES256، ES384، ES512، HS256، HS384، HS512.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

 سایر خطاهای احتمالی استقرار

متغیرهای خطا

این متغیرها زمانی تنظیم می شوند که یک خطای زمان اجرا رخ دهد. برای اطلاعات بیشتر، به آنچه باید در مورد خطاهای خط مشی بدانید مراجعه کنید.

متغیرها کجا مثال
fault.name=" fault_name " fault_name نام خطا است، همانطور که در جدول خطاهای Runtime در بالا ذکر شده است. نام خطا آخرین قسمت کد خطا است. fault.name Matches "TokenExpired"
JWS.failed همه خط مشی های JWS در صورت خرابی یک متغیر را تنظیم می کنند. jws.JWS-Policy.failed = true

نمونه پاسخ خطا

برای رسیدگی به خطا، بهترین روش به دام انداختن قسمت errorcode در پاسخ به خطا است. به متن موجود در faultstring تکیه نکنید، زیرا ممکن است تغییر کند.

مثال قانون خطا 

<FaultRules>
    <FaultRule name="JWS Policy Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "TokenExpired")</Condition>
        </Step>
        <Condition>JWS.failed=true</Condition>
    </FaultRule>
</FaultRules>