سیاست JWT را تأیید کنید

شما در حال مشاهده اسناد 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 محدودیت‌های بیشتری را اعمال می‌کند، مانند حذف خودکار کاراکترهایی که حروف عددی نیستند.

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

N/A مورد نیاز
continueOnError برای بازگرداندن خطا در صورت شکست خط مشی، روی false تنظیم کنید. این رفتار مورد انتظار برای اکثر سیاست ها است.

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

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

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

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

<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 مورد نیاز است.
تایپ کنید رشته
مقادیر معتبر

برای encoding ، مقادیر معتبر hex ، base16 ، base64 یا base64url هستند. مقادیر رمزگذاری hex و base16 مترادف هستند.

از ویژگی ref برای ارسال کلید در متغیر جریان استفاده کنید.

نکته: اگر یک متغیر جریان باشد، باید پیشوند "خصوصی" داشته باشد. مثلا private.mysecret

<منبع>

<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 ثانیه (بدون مهلت)
حضور اختیاری
تایپ کنید رشته
مقادیر معتبر یک مقدار یا یک مرجع به یک متغیر جریان حاوی مقدار. بازه های زمانی را می توان به صورت زیر مشخص کرد:
  • s = ثانیه
  • m = دقیقه
  • h = ساعت
  • d = روز

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

پس از موفقیت، سیاست های 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، این متغیر تنظیم نشده است.

مرجع خطا

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Occurs when
steps.jwt.AlgorithmInTokenNotPresentInConfiguration 401 Occurs when the verification policy has multiple algorithms.
steps.jwt.AlgorithmMismatch 401 The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match.
steps.jwt.FailedToDecode 401 The policy was unable to decode the JWT. The JWT is possibly corrupted.
steps.jwt.GenerationFailed 401 The policy was unable to generate the JWT.
steps.jwt.InsufficientKeyLength 401 For a key less than 32 bytes for the HS256 algorithm, less than 48 bytes for the HS386 algortithm, and less than 64 bytes for the HS512 algorithm.
steps.jwt.InvalidClaim 401 For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jwt.InvalidCurve 401 The curve specified by the key is not valid for the Elliptic Curve algorithm.
steps.jwt.InvalidJsonFormat 401 Invalid JSON found in the header or payload.
steps.jwt.InvalidToken 401 This error occurs when the JWT signature verification fails.
steps.jwt.JwtAudienceMismatch 401 The audience claim failed on token verification.
steps.jwt.JwtIssuerMismatch 401 The issuer claim failed on token verification.
steps.jwt.JwtSubjectMismatch 401 The subject claim failed on token verification.
steps.jwt.KeyIdMissing 401 The Verify policy uses a JWKS as a source for public keys, but the signed JWT does not include a kid property in the header.
steps.jwt.KeyParsingFailed 401 The public key could not be parsed from the given key information.
steps.jwt.NoAlgorithmFoundInHeader 401 Occurs when the JWT contains no algorithm header.
steps.jwt.NoMatchingPublicKey 401 The Verify policy uses a JWKS as a source for public keys, but the kid in the signed JWT is not listed in the JWKS.
steps.jwt.SigningFailed 401 In GenerateJWT, for a key less than the minimum size for the HS384 or HS512 algorithms
steps.jwt.TokenExpired 401 The policy attempts to verify an expired token.
steps.jwt.TokenNotYetValid 401 The token is not yet valid.
steps.jwt.UnhandledCriticalHeader 401 A header found by the Verify JWT policy in the crit header is not listed in KnownHeaders.
steps.jwt.UnknownException 401 An unknown exception occurred.
steps.jwt.WrongKeyType 401 Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidNameForAdditionalClaim The deployment will fail if the claim used in the child element <Claim> of the <AdditionalClaims> element is one of the following registered names: kid, iss, sub, aud, iat, exp, nbf, or jti.
InvalidTypeForAdditionalClaim If the claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
MissingNameForAdditionalClaim If the name of the claim is not specified in the child element <Claim> of the <AdditionalClaims> element, the deployment will fail.
InvalidNameForAdditionalHeader This error ccurs when the name of the claim used in the child element <Claim> of the <AdditionalClaims> element is either alg or typ.
InvalidTypeForAdditionalHeader If the type of claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
InvalidValueOfArrayAttribute This error occurs when the value of the array attribute in the child element <Claim> of the <AdditionalClaims> element is not set to true or false.
InvalidValueForElement If the value specified in the <Algorithm> element is not a supported value, the deployment will fail.
MissingConfigurationElement This error will occur if the <PrivateKey> element is not used with RSA family algorithms or the <SecretKey> element is not used with HS Family algorithms.
InvalidKeyConfiguration If the child element <Value> is not defined in the <PrivateKey> or <SecretKey> elements, the deployment will fail.
EmptyElementForKeyConfiguration If the ref attribute of the child element <Value> of the <PrivateKey> or <SecretKey> elements is empty or unspecified, the deployment will fail.
InvalidConfigurationForVerify This error occurs if the <Id> element is defined within the <SecretKey> element.
InvalidEmptyElement This error occurs if the <Source> element of the Verify JWT policy is empty. If present, it must be defined with an Edge flow variable name.
InvalidPublicKeyValue If the value used in the child element <JWKS> of the <PublicKey> element does not use a valid format as specified in RFC 7517, the deployment will fail.
InvalidConfigurationForActionAndAlgorithm If the <PrivateKey> element is used with HS Family algorithms or the <SecretKey> element is used with RSA Family algorithms, the deployment will fail.

متغیرهای خطا

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

متغیرها کجا مثال
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>