خط مشی 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> را روی true تنظیم کنید. برای اطلاعات بیشتر در مورد ساختار و قالب یک JWS به بخش‌هایی از یک JWS/JWT مراجعه کنید.

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

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

<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 ارائه شود.

یک JWS جدا شده، بار را از JWS حذف می کند:

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>

مرجع عنصر برای Generate JWS

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

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

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<الگوریتم>

<Algorithm>algorithm-here</Algorithm>

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

<AdditionalHeaders/Claim>

<AdditionalHeaders>
    <Claim name='cla>im1'explicit-value-of-cl<aim-he>re/Cl<aim
    Claim name='claim2' ref='>varia<ble-name-here'/
    Claim name='claim3' ref='>;vari<able-name-here' type='boolean'/
    Claim name='cla>im<4' ref='va>riable-name' type='string' array='true'/
 /AdditionalHeaders

جفت(های) نام/مقدار ادعای اضافی را در سربرگ JWS قرار می دهد.

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

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

<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

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

header..signature

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

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

<Payload>

<Payload ref="flow-variable-name-he>re&quo<t; /

o>r

Payloadpay<load-val>ue/Payload

محموله JWS خام و رمزگذاری نشده را مشخص می کند. یک متغیر حاوی بار یا یک رشته را مشخص کنید.

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-h>e<re"/
/>Privat<eKey

or

>Pri<va>teKey
  Idyour-id-<val>u<e-here/Id
/>PrivateKey

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

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-passw>o<rd"/
/>PrivateKey

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

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-h>e<re"/
/>PrivateKey

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

<SecretKey/Id>

<SecretKey>
  <Id ref="flow-variable-name-h>e<re"/
>/Secre<tKey

or
>
Se<cr>etKey
  Idyour-id-<val>u<e-here/Id
>/SecretKey

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

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-n>a<me"/
>/SecretKey

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

Edge حداقل قدرت کلید را برای الگوریتم‌های HS256/HS384/HS512 اعمال می‌کند. حداقل طول کلید برای HS256 32 بایت، برای HS384 48 بایت و برای HS512 64 بایت است. استفاده از یک کلید با قدرت کمتر باعث خطای زمان اجرا می شود.

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

خط مشی Generate JWS متغیرهای جریان را تنظیم نمی کند.

مرجع خطا

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>