خط‌مشی GenerateJWS

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

چه

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

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

ویدیو

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

نمونه‌ها

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

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

این خط‌مشی نمونه یک JWS پیوست‌شده تولید می‌کند و آن را بااستفاده از الگوریتم HS256 امضا می‌کند. ‫HS256 برای امضا کردن و درستی‌سنجی امضا به یک رمز مشترک متکی است.

یک JWS پیوست‌شده حاوی سرایند، بار، و امضای کدبندی‌شده است:

header.payload.signature

برای تولید محتوای جداشده، <DetachContent> را روی درست تنظیم کنید. برای اطلاعات بیشتر درباره ساختار و قالب JWS، به بخش‌های JWS/JWT مراجعه کنید.

از عنصر <Payload> برای مشخص کردن محتوای خام و کدبندی‌نشده JWS استفاده کنید. در این مثال، متغیری حاوی پایه‌بار است. وقتی این کنش خط‌مشی راه‌اندازی می‌شود، ‫Edge سرصفحه و محتوای JWS را کدبندی می‌کند، سپس امضای کدبندی‌شده را برای امضای دیجیتالی JWS اضافه می‌کند.

پیکربندی خط‌مشی زیر از پایه‌باری که در متغیر private.payload قرار دارد یک JWS می‌سازد.

<GenerateJWS name="JWS-Generate-HS256">
    <DisplayName>JWS Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <Payload ref="private.payload" />
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

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

این خط‌مشی نمونه یک JWS جداشده تولید می‌کند و آن را بااستفاده از الگوریتم RS256 امضا می‌کند. تولید امضای RS256 به کلید خصوصی RSA متکی است که باید در قالب کدبندی‌شده با PEM ارائه شود.

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

header..signature

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

<GenerateJWS name="JWS-Generate-RS256">
    <DisplayName>JWS Generate RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Payload ref="private.payload" />
    <DetachContent>true</DetachContent>
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

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

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

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

<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="private.privatekey-id"/>
</PrivateKey>

مرجع عنصر برای «تولید JWS»

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

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

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

الگوریتم رمزگذاری را برای امضای نشان مشخص می‌کند.

<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 قرار می‌دهد.

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

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

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

سرصفحه بحرانی، crit، را به JWS اضافه می‌کند. سرایند crit آرایه‌ای از نام‌های سرایند است که باید توسط گیرنده JWS شناخته و تشخیص داده شود. برای مثال:

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

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

<DetachContent>

<DetachContent>true|false</DetachContent>

مشخص می‌کند که آیا JWS با محتوای جداشده تولید شود، <DetachContent>true</DetachContent>، یا نه، <DetachContent>false</DetachContent>.

اگر مقدار false را مشخص کنید (مقدار پیش‌فرض)، JWS تولیدشده به‌صورت زیر است:

header.payload.signature

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

header..signature

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

مشخص می‌کند که JWS تولیدشده توسط این خط‌مشی کجا قرار داده شود. به‌طور پیش‌فرض در متغیر جاری‌سازی jws.POLICYNAME.generated_jws قرار می‌گیرد.

<Payload>

<Payload ref="flow-variable-name-here" />

or

<Payload>payload-value</Payload>

پایه‌بار JWS خام و کدبندی‌نشده را مشخص می‌کند. متغیری حاوی پایه‌بار یا رشته‌ای را مشخص کنید.

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

شناسه کلید (kid) را که باید در سرایند JWS گنجانده شود مشخص می‌کند. فقط زمانی استفاده کنید که الگوریتم یکی از این موارد باشد: RS256/RS384/RS512،‏ PS256/PS384/PS512، یا ES256/ES384/ES512.

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

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

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

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

<SecretKey/Id>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

شناسه کلید (kid) را مشخص می‌کند تا در سرایند JWS یک JWS که با الگوریتم HMAC امضا شده است اضافه شود. فقط زمانی استفاده کنید که الگوریتم یکی از HS256/HS384/HS512 باشد.

<SecretKey/Value>

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

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

‫Edge حداقل قدرت کلید را برای الگوریتم‌های HS256/HS384/HS512 اعمال می‌کند. حداقل طول کلید برای HS256، ۳۲ بایت، برای HS384، ۴۸ بایت، و برای HS512، ۶۴ بایت است. استفاده از کلید با قدرت کمتر باعث خطای زمان اجرا می‌شود.

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

خط‌مشی «تولید JWS» متغیرهای جریان را تنظیم نمی‌کند.

مرجع خطا

این بخش کدهای خطا و پیام‌های خطایی را که برگردانده می‌شوند و متغیرهای خطایی را که 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>