بررسی سیاست 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 جدا شده، بار را از 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>

مرجع عنصر

مرجع خط مشی عناصر و ویژگی های خط مشی Verify JWS را توصیف می کند.

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

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<الگوریتم>

<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 و هم مقدار ادعای صریح مشخص شده باشد، مقدار صریح پیش‌فرض است و اگر متغیر جریان ارجاع‌شده حل نشده باشد استفاده می‌شود.
• نوع - (اختیاری) یکی از: رشته (پیش‌فرض)، عدد، بولی یا نقشه
• آرایه - (اختیاری) برای نشان دادن اینکه آیا مقدار آرایه ای از انواع است، روی true تنظیم کنید. پیش فرض: نادرست.

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

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

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

header.payload.signature

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

header..signature

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

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

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

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

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

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

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

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

<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 مراجعه کنید.

اگر مقدار را از یک URL عمومی دریافت کنید، Edge JWKS را برای مدت 300 ثانیه در حافظه پنهان نگه می دارد. هنگامی که حافظه پنهان منقضی می شود، 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>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>