خط مشی 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='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 تنظیم کنید. پیش فرض: نادرست.

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

شناسه کلید (کودک) را برای درج در هدر 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>

شناسه کلید (کودک) را مشخص می کند تا در هدر 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 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>