خط‌مشی VerifyJWS

درحال مشاهده اسناد 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 قرار دارد.

«امضای وب جاوااسکریپت» جداشده پایه‌بار را از «امضای وب جاوااسکریپت» حذف می‌کند:

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>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>HS256</Algorithm>

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

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

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

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

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

عنصر <Claim> این مشخصه‌ها را می‌پذیرد:

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

<DetachedContent>

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

‫JWS تولیدشده با محتوای داده‌برداری به‌صورت زیر است:

header.payload.signature

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

header..signature

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

خط‌مشی در موارد زیر خطا می‌دهد:

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

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

اگر می‌خواهید وقتی هریک از متغیرهای ارجاع‌شده مشخص‌شده در خط‌مشی غیرقابل‌حل است، خط‌مشی خطا ایجاد کند، آن را روی «نادرست» تنظیم کنید. برای اینکه هر متغیر غیرقابل‌حلی به‌عنوان رشته خالی (تهی) درنظر گرفته شود، روی درست تنظیم کنید.

<KnownHeaders>

<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 ناموفق باشد.

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

<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 باشد.

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

اگر مقدار را از نشانی وب عمومی واکشی کنید، Edge مقدار JWKS را برای مدت ۳۰۰ ثانیه در حافظه نهان ذخیره می‌کند. وقتی حافظه نهان منقضی می‌شود، Edge دوباره JWKS را واکشی می‌کند.

<PublicKey/Value>

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

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

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

<Source>

<Source>JWS-variable</Source>

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

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

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

jws.{policy_name}.{variable_name}

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

مرجع خطا

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

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

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

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

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

متغیرهای خطا

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

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

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