بررسی سیاست JWS

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

چه

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

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

برای کسب اطلاعات در مورد بخش‌های یک JWS و نحوه رمزگذاری و امضای آنها، به RFC7515 مراجعه کنید.

ویدئو

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

نمونه‌ها

• تأیید یک JWS پیوست شده که با الگوریتم HS256 امضا شده است
• یک JWS جدا شده که با الگوریتم RS256 امضا شده است را تأیید کنید

تأیید یک JWS پیوست شده که با الگوریتم HS256 امضا شده است

این سیاست نمونه، یک JWS پیوست‌شده را که با الگوریتم رمزگذاری HS256، HMAC با استفاده از مجموع مقابله‌ای SHA-256 امضا شده است، تأیید می‌کند. JWS با استفاده از یک پارامتر فرم به نام JWS در درخواست پروکسی ارسال می‌شود. کلید در متغیری به نام private.secretkey قرار دارد.

یک JWS پیوست شده شامل هدر، بار داده و امضای کدگذاری شده است:

header.payload.signature

پیکربندی سیاست شامل اطلاعاتی است که Edge برای رمزگشایی و ارزیابی JWS نیاز دارد، مانند محل یافتن JWS (در یک متغیر جریان مشخص شده در عنصر <Source> )، الگوریتم امضای مورد نیاز و محل یافتن کلید مخفی (ذخیره شده در یک متغیر جریان Edge، که می‌توانست مثلاً از Edge KVM بازیابی شود).

<VerifyJWS name="JWS-Verify-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
</VerifyJWS>

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

یک JWS جدا شده که با الگوریتم RS256 امضا شده است را تأیید کنید

این سیاست نمونه، یک JWS جدا شده را که با الگوریتم RS256 امضا شده است، تأیید می‌کند. برای تأیید، باید کلید عمومی را ارائه دهید. JWS با استفاده از یک پارامتر فرم به نام JWS در درخواست پروکسی ارسال می‌شود. کلید عمومی در متغیری به نام public.publickey قرار دارد.

یک JWS جدا شده، محتوای مخرب (payload) را از JWS حذف می‌کند:

header..signature

این به شما بستگی دارد که با مشخص کردن نام متغیر حاوی بار داده در عنصر <DetachedContent> ، محتوای داده را به خط‌مشی VerifyJWS ارسال کنید. محتوای مشخص شده در <DetachedContent> باید به شکل اصلی و بدون رمزگذاری باشد که هنگام ایجاد امضای JWS وجود داشته است.

<VerifyJWS name="JWS-Verify-RS256">
    <DisplayName>JWS Verify RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <DetachedContent>private.payload</DetachedContent>
</VerifyJWS>

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

تنظیم عناصر کلیدی

عناصری که برای مشخص کردن کلید مورد استفاده برای تأیید JWS استفاده می‌کنید، به الگوریتم انتخاب شده بستگی دارد، همانطور که در جدول زیر نشان داده شده است:

<SecretKey>
  <Value ref="private.secretkey"/>
</SecretKey>

<PublicKey>
  <Value ref="rsa_public_key"/>
</PublicKey>

<PublicKey>
  <JWKS ref="jwks_val_ref_or_url"/>
</PublicKey>

مرجع عنصر

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

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

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

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

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

<نام نمایشی>

<DisplayName>Policy Display Name</DisplayName>

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

<الگوریتم>

<Algorithm>HS256</Algorithm>

الگوریتم رمزگذاری برای امضای توکن را مشخص می‌کند. الگوریتم‌های RS*/PS*/ES* از یک جفت کلید عمومی/مخفی استفاده می‌کنند، در حالی که الگوریتم‌های HS* از یک کلید مخفی مشترک استفاده می‌کنند. همچنین به «درباره الگوریتم‌های رمزگذاری امضا» مراجعه کنید.

شما می‌توانید چندین مقدار را که با کاما از هم جدا شده‌اند، مشخص کنید. برای مثال "HS256، HS512" یا "RS256، PS256". با این حال، نمی‌توانید الگوریتم‌های HS* را با هیچ الگوریتم دیگری یا الگوریتم‌های ES* را با هیچ الگوریتم دیگری ترکیب کنید زیرا به یک نوع کلید خاص نیاز دارند. می‌توانید الگوریتم‌های RS* و PS* را با هم ترکیب کنید.

<سرصفحه‌های اضافی/ادعا>

<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>

تأیید می‌کند که سرآیند JWS حاوی جفت(های) نام/مقدار ادعای اضافی مشخص شده است و مقادیر ادعای ادعا شده مطابقت دارند.

یک ادعای اضافی از نامی استفاده می‌کند که جزو نام‌های ادعای استاندارد و ثبت‌شده‌ی JWS نیست. مقدار یک ادعای اضافی می‌تواند یک رشته، یک عدد، یک مقدار بولی، یک نقشه یا یک آرایه باشد. یک نقشه صرفاً مجموعه‌ای از جفت‌های نام/مقدار است. مقدار هر یک از این نوع ادعاها را می‌توان به صراحت در پیکربندی سیاست یا به طور غیرمستقیم از طریق ارجاع به یک متغیر جریان مشخص کرد.

عنصر <Claim> این ویژگی‌ها را می‌پذیرد:

• نام - (الزامی) نام ادعا.
• ref - (اختیاری) نام یک متغیر جریان. در صورت وجود، سیاست از مقدار این متغیر به عنوان ادعا استفاده خواهد کرد. اگر هم ویژگی ref و هم مقدار ادعای صریح مشخص شده باشند، مقدار صریح پیش‌فرض است و در صورتی استفاده می‌شود که متغیر جریان ارجاع داده شده حل نشده باشد.
• نوع - (اختیاری) یکی از: رشته (پیش‌فرض)، عدد، بولی یا نقشه
• آرایه - (اختیاری) برای نشان دادن اینکه آیا مقدار، آرایه‌ای از انواع است یا خیر، روی true تنظیم می‌شود. پیش‌فرض: false.

<محتوای جدا شده>

<DetachedContent>variable-name-here</DetachedContent>

یک JWS تولید شده با محتوای payload به شکل زیر است:

header.payload.signature

اگر از سیاست GenerateJWS برای ایجاد بار داده‌ی جدا استفاده کنید، JWS تولید شده بار داده را حذف کرده و به شکل زیر خواهد بود:

header..signature

برای یک محتوای جدا شده، ارسال محتوای جدا شده به سیاست VerifyJWS با استفاده از عنصر <DetachedContent> به عهده شماست. محتوای جدا شده باید به شکل اصلی و بدون رمزگذاری باشد که هنگام ایجاد امضای JWS وجود داشته است.

این خط‌مشی زمانی خطا می‌دهد که:

• <DetachedContent> زمانی مشخص می‌شود که JWS حاوی محتوای جدا شده نباشد (کد خطا steps.jws.ContentIsNotDetached است).
• <DetachedContent> حذف شده است و JWS دارای محتوای جداگانه است (کد خطا steps.jws.InvalidSignature است).

<نادیده گرفتن هدرهای بحرانی>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

اگر می‌خواهید سیاست در صورت عدم وجود هر سرآیند ذکر شده در سرآیند crit از JWS در عنصر <KnownHeaders> ، خطا صادر کند، روی false تنظیم کنید. اگر می‌خواهید سیاست VerifyJWS سرآیند crit را نادیده بگیرد، روی true تنظیم کنید.

یکی از دلایل تنظیم این عنصر روی مقدار true این است که اگر در یک محیط آزمایشی هستید و نمی‌خواهید سیاست به دلیل از دست دادن یک هدر با شکست مواجه شود.

<نادیده گرفتن متغیرهای حل نشده>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

اگر می‌خواهید سیاست در صورت غیرقابل حل بودن هر متغیر ارجاع‌شده در سیاست، خطا صادر کند، روی false تنظیم کنید. اگر می‌خواهید هر متغیر غیرقابل حل را به عنوان یک رشته خالی (null) در نظر بگیرید، روی true تنظیم کنید.

<سربرگ‌های شناخته‌شده>

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref=’variable_containing_headers’/>

سیاست GenerateJWS از عنصر <CriticalHeaders> برای پر کردن هدر crit در یک توکن استفاده می‌کند. برای مثال:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

سیاست VerifyJWS در صورت وجود، هدر crit را در JWS بررسی می‌کند و برای هر مورد فهرست‌شده، بررسی می‌کند که عنصر <KnownHeaders> نیز آن هدر را فهرست کرده باشد. عنصر <KnownHeaders> می‌تواند شامل مجموعه‌ای از موارد فهرست‌شده در crit باشد. فقط لازم است که تمام هدرهای فهرست‌شده در crit در عنصر <KnownHeaders> فهرست شده باشند. هر هدری که سیاست در crit پیدا کند و در <KnownHeaders> نیز فهرست نشده باشد، باعث عدم موفقیت سیاست VerifyJWS می‌شود.

شما می‌توانید به صورت اختیاری، با تنظیم عنصر <IgnoreCriticalHeaders> روی true ، سیاست VerifyJWS را طوری پیکربندی کنید که هدر crit را نادیده بگیرد.

<کلید عمومی/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 باشد.

اگر JWS ورودی دارای شناسه کلیدی باشد که در مجموعه JWKS موجود باشد، آنگاه سیاست از کلید عمومی صحیح برای تأیید امضای JWS استفاده خواهد کرد. برای جزئیات بیشتر در مورد این ویژگی، به استفاده از مجموعه کلید وب JSON (JWKS) برای تأیید JWS مراجعه کنید.

اگر مقدار را از یک URL عمومی دریافت کنید، Edge فایل JWKS را به مدت ۳۰۰ ثانیه ذخیره می‌کند. وقتی مدت زمان ذخیره به پایان برسد، Edge دوباره JWKS را دریافت می‌کند.

<کلید عمومی/مقدار>

<PublicKey>
   <Value ref="public.publickey"/>
</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>

کلید عمومی مورد استفاده برای تأیید امضا در JWS را مشخص می‌کند. از ویژگی ref برای ارسال کلید در یک متغیر جریان استفاده کنید، یا کلید رمزگذاری شده با PEM را مستقیماً مشخص کنید. فقط زمانی استفاده کنید که الگوریتم یکی از RS256/RS384/RS512، PS256/PS384/PS512 یا ES256/ES384/ES512 باشد.

<کلید مخفی/مقدار>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

کلید مخفی مورد استفاده برای تأیید یا امضای توکن‌ها با الگوریتم HMAC را ارائه می‌دهد. فقط زمانی استفاده می‌شود که الگوریتم یکی از HS256، HS384، HS512 باشد. از ویژگی ref برای ارسال کلید در یک متغیر جریان استفاده کنید.

<منبع>

<Source>JWS-variable</Source>

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

Flow variables

Upon success, the Verify JWS and Decode JWS policies set context variables according to this pattern:

jws.{policy_name}.{variable_name}

For example, if the policy name is verify-jws, then the policy will store the algorithm specified in the JWS to this context variable: jws.verify-jws.header.algorithm

مرجع خطا

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.

Deployment errors

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

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

<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>

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

چه

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

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

برای کسب اطلاعات در مورد بخش‌های یک JWS و نحوه رمزگذاری و امضای آنها، به RFC7515 مراجعه کنید.

ویدئو

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

نمونه‌ها

• تأیید یک JWS پیوست شده که با الگوریتم HS256 امضا شده است
• یک JWS جدا شده که با الگوریتم RS256 امضا شده است را تأیید کنید

تأیید یک JWS پیوست شده که با الگوریتم HS256 امضا شده است

این سیاست نمونه، یک JWS پیوست‌شده را که با الگوریتم رمزگذاری HS256، HMAC با استفاده از مجموع مقابله‌ای SHA-256 امضا شده است، تأیید می‌کند. JWS با استفاده از یک پارامتر فرم به نام JWS در درخواست پروکسی ارسال می‌شود. کلید در متغیری به نام private.secretkey قرار دارد.

یک JWS پیوست شده شامل هدر، بار داده و امضای کدگذاری شده است:

header.payload.signature

پیکربندی سیاست شامل اطلاعاتی است که Edge برای رمزگشایی و ارزیابی JWS نیاز دارد، مانند محل یافتن JWS (در یک متغیر جریان مشخص شده در عنصر <Source> )، الگوریتم امضای مورد نیاز و محل یافتن کلید مخفی (ذخیره شده در یک متغیر جریان Edge، که می‌توانست مثلاً از Edge KVM بازیابی شود).

<VerifyJWS name="JWS-Verify-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
</VerifyJWS>

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

یک JWS جدا شده که با الگوریتم RS256 امضا شده است را تأیید کنید

این سیاست نمونه، یک JWS جدا شده را که با الگوریتم RS256 امضا شده است، تأیید می‌کند. برای تأیید، باید کلید عمومی را ارائه دهید. JWS با استفاده از یک پارامتر فرم به نام JWS در درخواست پروکسی ارسال می‌شود. کلید عمومی در متغیری به نام public.publickey قرار دارد.

یک JWS جدا شده، محتوای مخرب (payload) را از JWS حذف می‌کند:

header..signature

این به شما بستگی دارد که با مشخص کردن نام متغیر حاوی بار داده در عنصر <DetachedContent> ، محتوای داده را به خط‌مشی VerifyJWS ارسال کنید. محتوای مشخص شده در <DetachedContent> باید به شکل اصلی و بدون رمزگذاری باشد که هنگام ایجاد امضای JWS وجود داشته است.

<VerifyJWS name="JWS-Verify-RS256">
    <DisplayName>JWS Verify RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <DetachedContent>private.payload</DetachedContent>
</VerifyJWS>

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

تنظیم عناصر کلیدی

عناصری که برای مشخص کردن کلید مورد استفاده برای تأیید JWS استفاده می‌کنید، به الگوریتم انتخاب شده بستگی دارد، همانطور که در جدول زیر نشان داده شده است:

<SecretKey>
  <Value ref="private.secretkey"/>
</SecretKey>

<PublicKey>
  <Value ref="rsa_public_key"/>
</PublicKey>

<PublicKey>
  <JWKS ref="jwks_val_ref_or_url"/>
</PublicKey>

مرجع عنصر

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

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

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

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

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

<نام نمایشی>

<DisplayName>Policy Display Name</DisplayName>

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

<الگوریتم>

<Algorithm>HS256</Algorithm>

الگوریتم رمزگذاری برای امضای توکن را مشخص می‌کند. الگوریتم‌های RS*/PS*/ES* از یک جفت کلید عمومی/مخفی استفاده می‌کنند، در حالی که الگوریتم‌های HS* از یک کلید مخفی مشترک استفاده می‌کنند. همچنین به «درباره الگوریتم‌های رمزگذاری امضا» مراجعه کنید.

شما می‌توانید چندین مقدار را که با کاما از هم جدا شده‌اند، مشخص کنید. برای مثال "HS256، HS512" یا "RS256، PS256". با این حال، نمی‌توانید الگوریتم‌های HS* را با هیچ الگوریتم دیگری یا الگوریتم‌های ES* را با هیچ الگوریتم دیگری ترکیب کنید زیرا به یک نوع کلید خاص نیاز دارند. می‌توانید الگوریتم‌های RS* و PS* را با هم ترکیب کنید.

<سرصفحه‌های اضافی/ادعا>

<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>

تأیید می‌کند که سرآیند JWS حاوی جفت(های) نام/مقدار ادعای اضافی مشخص شده است و مقادیر ادعای ادعا شده مطابقت دارند.

یک ادعای اضافی از نامی استفاده می‌کند که جزو نام‌های ادعای استاندارد و ثبت‌شده‌ی JWS نیست. مقدار یک ادعای اضافی می‌تواند یک رشته، یک عدد، یک مقدار بولی، یک نقشه یا یک آرایه باشد. یک نقشه صرفاً مجموعه‌ای از جفت‌های نام/مقدار است. مقدار هر یک از این نوع ادعاها را می‌توان به صراحت در پیکربندی سیاست یا به طور غیرمستقیم از طریق ارجاع به یک متغیر جریان مشخص کرد.

عنصر <Claim> این ویژگی‌ها را می‌پذیرد:

• نام - (الزامی) نام ادعا.
• ref - (اختیاری) نام یک متغیر جریان. در صورت وجود، سیاست از مقدار این متغیر به عنوان ادعا استفاده خواهد کرد. اگر هم ویژگی ref و هم مقدار ادعای صریح مشخص شده باشند، مقدار صریح پیش‌فرض است و در صورتی استفاده می‌شود که متغیر جریان ارجاع داده شده حل نشده باشد.
• نوع - (اختیاری) یکی از: رشته (پیش‌فرض)، عدد، بولی یا نقشه
• آرایه - (اختیاری) برای نشان دادن اینکه آیا مقدار، آرایه‌ای از انواع است یا خیر، روی true تنظیم می‌شود. پیش‌فرض: false.

<محتوای جدا شده>

<DetachedContent>variable-name-here</DetachedContent>

یک JWS تولید شده با محتوای payload به شکل زیر است:

header.payload.signature

اگر از سیاست GenerateJWS برای ایجاد بار داده‌ی جدا استفاده کنید، JWS تولید شده بار داده را حذف کرده و به شکل زیر خواهد بود:

header..signature

برای یک محتوای جدا شده، ارسال محتوای جدا شده به سیاست VerifyJWS با استفاده از عنصر <DetachedContent> به عهده شماست. محتوای جدا شده باید به شکل اصلی و بدون رمزگذاری باشد که هنگام ایجاد امضای JWS وجود داشته است.

این خط‌مشی زمانی خطا می‌دهد که:

• <DetachedContent> زمانی مشخص می‌شود که JWS حاوی محتوای جدا شده نباشد (کد خطا steps.jws.ContentIsNotDetached است).
• <DetachedContent> حذف شده است و JWS دارای محتوای جداگانه است (کد خطا steps.jws.InvalidSignature است).

<نادیده گرفتن هدرهای بحرانی>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

اگر می‌خواهید سیاست در صورت عدم وجود هر سرآیند ذکر شده در سرآیند crit از JWS در عنصر <KnownHeaders> ، خطا صادر کند، روی false تنظیم کنید. اگر می‌خواهید سیاست VerifyJWS سرآیند crit را نادیده بگیرد، روی true تنظیم کنید.

یکی از دلایل تنظیم این عنصر روی مقدار true این است که اگر در یک محیط آزمایشی هستید و نمی‌خواهید سیاست به دلیل از دست دادن یک هدر با شکست مواجه شود.

<نادیده گرفتن متغیرهای حل نشده>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

اگر می‌خواهید سیاست در صورت غیرقابل حل بودن هر متغیر ارجاع‌شده در سیاست، خطا صادر کند، روی false تنظیم کنید. اگر می‌خواهید هر متغیر غیرقابل حل را به عنوان یک رشته خالی (null) در نظر بگیرید، روی true تنظیم کنید.

<سربرگ‌های شناخته‌شده>

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref=’variable_containing_headers’/>

سیاست GenerateJWS از عنصر <CriticalHeaders> برای پر کردن هدر crit در یک توکن استفاده می‌کند. برای مثال:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

سیاست VerifyJWS در صورت وجود، هدر crit را در JWS بررسی می‌کند و برای هر مورد فهرست‌شده، بررسی می‌کند که عنصر <KnownHeaders> نیز آن هدر را فهرست کرده باشد. عنصر <KnownHeaders> می‌تواند شامل مجموعه‌ای از موارد فهرست‌شده در crit باشد. فقط لازم است که تمام هدرهای فهرست‌شده در crit در عنصر <KnownHeaders> فهرست شده باشند. هر هدری که سیاست در crit پیدا کند و در <KnownHeaders> نیز فهرست نشده باشد، باعث عدم موفقیت سیاست VerifyJWS می‌شود.

شما می‌توانید به صورت اختیاری، با تنظیم عنصر <IgnoreCriticalHeaders> روی true ، سیاست VerifyJWS را طوری پیکربندی کنید که هدر crit را نادیده بگیرد.

<کلید عمومی/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 باشد.

اگر JWS ورودی دارای شناسه کلیدی باشد که در مجموعه JWKS موجود باشد، آنگاه سیاست از کلید عمومی صحیح برای تأیید امضای JWS استفاده خواهد کرد. برای جزئیات بیشتر در مورد این ویژگی، به استفاده از مجموعه کلید وب JSON (JWKS) برای تأیید JWS مراجعه کنید.

اگر مقدار را از یک URL عمومی دریافت کنید، Edge فایل JWKS را به مدت ۳۰۰ ثانیه ذخیره می‌کند. وقتی مدت زمان ذخیره به پایان برسد، Edge دوباره JWKS را دریافت می‌کند.

<کلید عمومی/مقدار>

<PublicKey>
   <Value ref="public.publickey"/>
</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>

کلید عمومی مورد استفاده برای تأیید امضا در JWS را مشخص می‌کند. از ویژگی ref برای ارسال کلید در یک متغیر جریان استفاده کنید، یا کلید رمزگذاری شده با PEM را مستقیماً مشخص کنید. فقط زمانی استفاده کنید که الگوریتم یکی از RS256/RS384/RS512، PS256/PS384/PS512 یا ES256/ES384/ES512 باشد.

<کلید مخفی/مقدار>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

کلید مخفی مورد استفاده برای تأیید یا امضای توکن‌ها با الگوریتم HMAC را ارائه می‌دهد. فقط زمانی استفاده می‌شود که الگوریتم یکی از HS256، HS384، HS512 باشد. از ویژگی ref برای ارسال کلید در یک متغیر جریان استفاده کنید.

<منبع>

<Source>JWS-variable</Source>

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

Flow variables

Upon success, the Verify JWS and Decode JWS policies set context variables according to this pattern:

jws.{policy_name}.{variable_name}

For example, if the policy name is verify-jws, then the policy will store the algorithm specified in the JWS to this context variable: jws.verify-jws.header.algorithm

مرجع خطا

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.

Deployment errors

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

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

<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>