خط مشی GenerateJWS

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

چه

یک JWS امضا شده با مجموعه‌ای از ادعاها (Claims) قابل تنظیم تولید می‌کند. سپس JWS می‌تواند به کلاینت‌ها برگردانده شود، به اهداف backend منتقل شود یا به روش‌های دیگر مورد استفاده قرار گیرد. برای مقدمه‌ای مفصل ، به مرور کلی سیاست‌های 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 را از یک payload موجود در متغیر 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 جدا شده، محتوای مخرب (payload) را از 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>Policy Display Name</DisplayName>

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

<الگوریتم>

<Algorithm>algorithm-here</Algorithm>

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

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

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

<هدرهای بحرانی>

<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>true|false</DetachContent>

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

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

header.payload.signature

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

header..signature

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

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

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<متغیر خروجی>

<OutputVariable>JWS-variable</OutputVariable>

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

<بار مفید>

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

or

<Payload>payload-value</Payload>

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

<کلید خصوصی/شناسه>

<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 ref="private.privatekey-password"/>
</PrivateKey>

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

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

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

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

<کلید مخفی/شناسه>

<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 ref="private.your-variable-name"/>
</SecretKey>

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

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

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

خط‌مشی Generate 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>