خط‌مشی DecodeJWT

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

چه

‫JWT را بدون درستی‌سنجی امضای آن رمزگشایی می‌کند. این ویژگی زمانی بیشترین کاربرد را دارد که همراه با خط‌مشی VerifyJWT استفاده شود، یعنی زمانی که مقدار ادعایی از درون JWT باید قبل‌از تأیید امضای JWT مشخص شود.

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

ویدیو

برای آشنایی با نحوه رمزگشایی JWT، ویدیو کوتاهی را تماشا کنید.

نمونه: رمزگشایی JWT

خط‌مشی نشان‌داده‌شده در زیر، یک JWT را که در متغیر جریان var.jwt پیدا شده است رمزگشایی می‌کند. این متغیر باید وجود داشته باشد و حاوی یک JWT معتبر (قابل‌رمزگشایی) باشد. خط‌مشی می‌تواند JWT را از هر متغیر جاری‌سازی دریافت کند.

<DecodeJWT name="JWT-Decode-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Source>var.jwt</Source>
</DecodeJWT>

این خط‌مشی برونداد خود را در متغیرهای زمینه‌ای می‌نویسد تا خط‌مشی‌ها یا شرایط بعدی در پراکسی API بتوانند آن مقادیر را بررسی کنند. برای فهرست متغیرهای تنظیم‌شده توسط این خط‌مشی، متغیرهای جاری‌سازی را ببینید.

مرجع عنصر برای «رمزگشایی JWT»

مرجع خط‌مشی عناصر و مشخصه‌های خط‌مشی «رمزگشایی JWT» را توصیف می‌کند.

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

<DecodeJWT name="JWT" continueOnError="false" enabled="true" async="false">

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

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

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

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

روی true تنظیم کنید تا اجرای جریان حتی پس‌از ناموفق بودن خط‌مشی ادامه یابد.

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

برای «خاموش کردن» خط‌مشی، روی false تنظیم کنید. حتی اگر خط‌مشی به جریانی پیوست شده باشد، اجرا نخواهد شد.

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Source>

<Source>jwt-variable</Source>

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

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

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

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

jwt.{policy_name}.{variable_name}

به عنوان مثال، اگر نام خط مشی jwt-parse-token باشد، آنگاه این خط مشی موضوع مشخص شده در JWT را در متغیر زمینه به نام jwt.jwt-parse-token.decoded.claim.sub ذخیره می کند. (برای سازگاری به عقب، در jwt.jwt-parse-token.claim.subject نیز موجود خواهد بود)

نام متغیر توضیحات
claim.audience ادعای مخاطبان JWT. این مقدار ممکن است یک رشته یا آرایه ای از رشته ها باشد.
claim.expiry تاریخ/زمان انقضا، بر حسب میلی‌ثانیه از آن دوره بیان می‌شود.
claim.issuedat تاریخ انتشار توکن، که از آن دوره برحسب میلی ثانیه بیان می‌شود.
claim.issuer ادعای صادرکننده JWT.
claim.notbefore اگر JWT شامل یک ادعای nbf باشد، این متغیر حاوی مقداری خواهد بود که از آن دوره در میلی ثانیه بیان شده است.
claim.subject ادعای موضوع JWT.
claim. name ارزش ادعای نامگذاری شده (استاندارد یا اضافی) در بار. یکی از اینها برای هر ادعا در محموله تنظیم می شود.
decoded.claim. name مقدار JSON قابل تجزیه ادعای نام‌گذاری شده (استاندارد یا اضافی) در بار. برای هر ادعا در محموله یک متغیر تنظیم شده است. برای مثال، می‌توانید از decoded.claim.iat برای بازیابی زمان صدور JWT، که بر حسب ثانیه از آن دوره بیان می‌شود، استفاده کنید. در حالی که می توانید از claim. name متغیرهای جریان، این متغیر توصیه شده برای دسترسی به ادعا است.
decoded.header. name مقدار قابل تجزیه JSON یک هدر در بار. یک متغیر برای هر هدر در محموله تنظیم شده است. در حالی که می توانید از header. name متغیرهای جریان، این متغیر پیشنهادی برای استفاده برای دسترسی به هدر است.
expiry_formatted تاریخ/زمان انقضا، به عنوان یک رشته قابل خواندن توسط انسان قالب بندی شده است. مثال: 2017-09-28T21:30:45.000+0000
header.algorithm الگوریتم امضای مورد استفاده در JWT. به عنوان مثال، RS256، HS384، و غیره. برای اطلاعات بیشتر به پارامتر سرصفحه (الگوریتم) مراجعه کنید.
header.kid شناسه کلید، اگر هنگام تولید JWT اضافه شود. همچنین به «استفاده از مجموعه کلیدهای وب JSON (JWKS)» در نمای کلی خط‌مشی‌های JWT برای تأیید JWT مراجعه کنید. برای اطلاعات بیشتر به پارامتر سرصفحه (شناسه کلید) مراجعه کنید.
header.type روی JWT تنظیم خواهد شد.
header. name مقدار هدر نامگذاری شده (استاندارد یا اضافی). یکی از اینها برای هر هدر اضافی در قسمت هدر JWT تنظیم می شود.
header-json هدر با فرمت JSON.
is_expired درست یا نادرست
payload-claim-names مجموعه ای از ادعاهای پشتیبانی شده توسط JWT.
payload-json
محموله در قالب JSON.
seconds_remaining تعداد ثانیه های قبل از توکن منقضی می شود. اگر توکن منقضی شده باشد، این عدد منفی خواهد بود.
time_remaining_formatted زمان باقی‌مانده تا توکن منقضی می‌شود که به‌صورت رشته‌ای قابل خواندن توسط انسان قالب‌بندی شده است. مثال: 00:59:59.926
valid در مورد VerifyJWT، این متغیر زمانی درست خواهد بود که امضا تایید شود، و زمان فعلی قبل از انقضای توکن است و بعد از مقدار notBefore توکن، در صورت وجود. در غیر این صورت نادرست.

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

مرجع خطا

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

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

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

کد خطا وضعیت HTTP علت رفع اشکال
steps.jwt.FailedToDecode 401 وقتی خط‌مشی نتواند JWT را کدگشایی کند رخ می‌دهد. ‫JWT ممکن است ساختار نادرست، نامعتبر، یا به‌صورت دیگری غیرقابل رمزگشایی باشد.
steps.jwt.FailedToResolveVariable 401 زمانی رخ می‌دهد که متغیر جاری مشخص‌شده در عنصر <Source> خط‌مشی وجود نداشته باشد.
steps.jwt.InvalidToken 401 زمانی رخ می‌دهد که متغیر جاری مشخص‌شده در عنصر <Source> خط‌مشی خارج از محدوده باشد یا قابل‌حل نباشد.

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

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

نام خطا علت رفع اشکال
InvalidEmptyElement زمانی رخ می‌دهد که متغیر جاری‌سازی حاوی JWT برای رمزگشایی در عنصر <Source> خط‌مشی مشخص نشده باشد.

متغیرهای خطا

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

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

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

کدهای خطای خط مشی JWT

برای رسیدگی به خطا، بهترین روش به دام انداختن قسمت 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>