ایجاد خط مشی JWT

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

چه

یک JWT امضا شده با مجموعه‌ای از ادعاها (Claims) قابل تنظیم تولید می‌کند. سپس JWT می‌تواند به کلاینت‌ها برگردانده شود، به اهداف backend منتقل شود یا به روش‌های دیگر مورد استفاده قرار گیرد. برای مقدمه‌ای مفصل ، به مرور کلی سیاست‌های JWS و JWT مراجعه کنید.

ویدئو

برای یادگیری نحوه تولید یک JWT امضا شده، یک ویدیوی کوتاه تماشا کنید.

نمونه‌ها

• یک JWT امضا شده با الگوریتم HS256 تولید کنید
• یک JWT امضا شده با الگوریتم RS256 ایجاد کنید

یک JWT امضا شده با الگوریتم HS256 تولید کنید

این سیاست نمونه، یک JWT جدید تولید می‌کند و آن را با استفاده از الگوریتم HS256 امضا می‌کند. HS256 برای امضا و تأیید امضا به یک راز مشترک متکی است.

وقتی این اقدام سیاستی آغاز می‌شود، Edge هدر و بار داده JWT را رمزگذاری می‌کند، سپس JWT را به صورت دیجیتالی امضا می‌کند. برای مثال کامل، از جمله نحوه ارسال درخواست به سیاست، به ویدیوی بالا مراجعه کنید.

پیکربندی سیاست در اینجا یک JWT با مجموعه‌ای از ادعاهای استاندارد مطابق با مشخصات JWT، شامل انقضای ۱ ساعته و همچنین یک ادعای اضافی ایجاد می‌کند. می‌توانید هر تعداد ادعای اضافی که می‌خواهید را اضافه کنید. برای جزئیات بیشتر در مورد الزامات و گزینه‌های هر عنصر در این سیاست نمونه، به مرجع Element مراجعه کنید.

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

JWT حاصل این هدر را خواهد داشت…

{
  "typ" : "JWT", 
  "alg" : "HS256",
  "kid" : "1918290"
}

... و یک payload با محتویاتی مانند این خواهد داشت:

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "show",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

ارزش ادعاهای iat ، exp و jti متفاوت خواهد بود.

یک JWT امضا شده با الگوریتم RS256 ایجاد کنید

این سیاست نمونه، یک JWT جدید تولید می‌کند و آن را با استفاده از الگوریتم RS256 امضا می‌کند. تولید امضای RS256 به یک کلید خصوصی RSA متکی است که باید به صورت رمزگذاری شده با PEM ارائه شود. برای مثال کامل، از جمله نحوه درخواست به این سیاست، به ویدیوی بالا مراجعه کنید.

وقتی این اقدام سیاستی آغاز می‌شود، Edge، JWT، شامل ادعاها را رمزگذاری و به صورت دیجیتالی امضا می‌کند. برای کسب اطلاعات در مورد بخش‌های یک JWT و نحوه رمزگذاری و امضای آنها، به RFC7519 مراجعه کنید.

<GenerateJWT name="JWT-Generate-RS256">
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

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

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

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

مرجع سیاست، عناصر و ویژگی‌های سیاست Generate JWT را شرح می‌دهد.

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

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

<GenerateJWT name="JWT" continueOnError="false" enabled="true" async="false">

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

<نام نمایشی>

<DisplayName>Policy Display Name</DisplayName>

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

<الگوریتم>

<Algorithm>algorithm-here</Algorithm>

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

<مخاطب>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

این سیاست یک JWT تولید می‌کند که حاوی یک aud claim است که روی مقدار مشخص شده تنظیم شده است. این claim گیرنده‌هایی را که JWT برای آنها در نظر گرفته شده است، شناسایی می‌کند. این یکی از claimهای ثبت شده ذکر شده در RFC7519 است.

<ادعاهای اضافی/ادعا>

<AdditionalClaims>
    <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'/>
</AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

به شما امکان می‌دهد جفت(های) نام/مقدار اضافی را در payload JWT مشخص کنید. می‌توانید claim را به صراحت به عنوان رشته، عدد، مقدار بولی، نگاشت یا آرایه مشخص کنید. یک نگاشت به سادگی مجموعه‌ای از جفت‌های نام/مقدار است.

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

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

وقتی عنصر <Claim> را اضافه می‌کنید، نام‌های ادعا هنگام پیکربندی سیاست به صورت ایستا تنظیم می‌شوند. به عنوان یک جایگزین، می‌توانید یک شیء JSON برای مشخص کردن نام‌های ادعا ارسال کنید. از آنجا که شیء JSON به عنوان یک متغیر ارسال می‌شود، نام‌های ادعا در JWT تولید شده در زمان اجرا تعیین می‌شوند.

برای مثال:

<AdditionalClaims ref='json_claims'/>

جایی که متغیر json_claims شامل یک شیء JSON به شکل زیر است:

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

JWT تولید شده شامل تمام ادعاهای موجود در شیء JSON است.

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

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

جفت(های) نام/مقدار ادعایی اضافی را در هدر JWT قرار می‌دهد.

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

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

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

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

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

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

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

<ادعاهای سفارشی>

نکته: در حال حاضر، وقتی یک سیاست GenerateJWT جدید را از طریق رابط کاربری اضافه می‌کنید، یک عنصر CustomClaims اضافه می‌شود. این عنصر کاربردی نیست و نادیده گرفته می‌شود. عنصر صحیح برای استفاده، <AdditionalClaims> است. رابط کاربری بعداً برای اضافه کردن عناصر صحیح به‌روزرسانی خواهد شد.

<منقضی می‌شود>

<ExpiresIn>time-value-here</ExpiresIn>

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

<شناسه>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

یک JWT با ادعای jti خاص تولید می‌کند. وقتی مقدار متن و ویژگی ref هر دو خالی باشند، این سیاست یک jti حاوی یک UUID تصادفی تولید می‌کند. ادعای JWT ID (jti) یک شناسه منحصر به فرد برای JWT است. برای اطلاعات بیشتر در مورد jti، به RFC7519 مراجعه کنید.

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

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<صادرکننده>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

این سیاست یک JWT تولید می‌کند که حاوی یک ادعا با نام iss است و مقداری که روی مقدار مشخص شده تنظیم شده است. ادعایی که صادرکننده JWT را شناسایی می‌کند. این یکی از مجموعه ادعاهای ثبت شده ذکر شده در RFC7519 است.

<قبلاً نه>

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

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

مقادیر زمانی معتبر برای عنصر NotBefore برای مقادیر زمانی مطلق

برای مقادیر زمانی نسبی، یک عدد صحیح و یک دوره زمانی مشخص کنید، برای مثال:

• ده‌ها
• ۶۰ متر
• ۱۲ ساعت

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

<OutputVariable>jwt-variable</OutputVariable>

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

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

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

or

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

شناسه کلید (kid) را برای درج در هدر JWT مشخص می‌کند. فقط زمانی استفاده می‌شود که الگوریتم یکی از 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 را مشخص می‌کند که برای امضای JWT استفاده می‌شود. از ویژگی 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) را برای قرار گرفتن در هدر JWT یک JWT امضا شده با الگوریتم 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 بایت است. استفاده از کلید با قدرت کمتر باعث خطای زمان اجرا می‌شود.

<موضوع>

<Subject>subject-string-here</Subject>

<Subject ref="flow_variable" />

برای مثال:

<Subject ref="apigee.developer.email"/>

این سیاست یک JWT تولید می‌کند که شامل یک sub claim است و روی مقدار مشخص شده تنظیم شده است. این claim موضوع JWT را شناسایی یا در مورد آن بیانیه‌ای صادر می‌کند. این یکی از مجموعه‌های استاندارد claimهای ذکر شده در RFC7519 است.

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

سیاست Generate JWT متغیرهای جریان را تنظیم نمی‌کند.

مرجع خطا

این بخش کدهای خطا و پیام‌های خطایی را که برگردانده می‌شوند و متغیرهای خطا را که توسط Edge تنظیم می‌شوند، هنگامی که این خط‌مشی خطا را راه‌اندازی می‌کند، توضیح می‌دهد. این اطلاعات برای دانستن اینکه آیا در حال توسعه قوانین خطا برای رسیدگی به خطاها هستید، مهم است. برای کسب اطلاعات بیشتر، آنچه را که باید در مورد خطاهای خط مشی و مدیریت خطاها بدانید را ببینید.

خطاهای زمان اجرا

این خطاها ممکن است هنگام اجرای سیاست رخ دهند.

خطاهای استقرار

این خطاها ممکن است زمانی رخ دهند که یک پروکسی حاوی این خط مشی را مستقر می کنید.

متغیرهای خطا

این متغیرها زمانی تنظیم می شوند که یک خطای زمان اجرا رخ دهد. برای اطلاعات بیشتر، به آنچه باید در مورد خطاهای خط مشی بدانید مراجعه کنید.

نمونه پاسخ خطا

برای رسیدگی به خطا، بهترین روش به دام انداختن قسمت errorcode در پاسخ به خطا است. به متن موجود در faultstring تکیه نکنید، زیرا ممکن است تغییر کند.

مثال قانون خطا

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>
    

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

چه

یک JWT امضا شده با مجموعه‌ای از ادعاها (Claims) قابل تنظیم تولید می‌کند. سپس JWT می‌تواند به کلاینت‌ها برگردانده شود، به اهداف backend منتقل شود یا به روش‌های دیگر مورد استفاده قرار گیرد. برای مقدمه‌ای مفصل ، به مرور کلی سیاست‌های JWS و JWT مراجعه کنید.

ویدئو

برای یادگیری نحوه تولید یک JWT امضا شده، یک ویدیوی کوتاه تماشا کنید.

نمونه‌ها

• یک JWT امضا شده با الگوریتم HS256 تولید کنید
• یک JWT امضا شده با الگوریتم RS256 ایجاد کنید

یک JWT امضا شده با الگوریتم HS256 تولید کنید

این سیاست نمونه، یک JWT جدید تولید می‌کند و آن را با استفاده از الگوریتم HS256 امضا می‌کند. HS256 برای امضا و تأیید امضا به یک راز مشترک متکی است.

وقتی این اقدام سیاستی آغاز می‌شود، Edge هدر و بار داده JWT را رمزگذاری می‌کند، سپس JWT را به صورت دیجیتالی امضا می‌کند. برای مثال کامل، از جمله نحوه ارسال درخواست به سیاست، به ویدیوی بالا مراجعه کنید.

پیکربندی سیاست در اینجا یک JWT با مجموعه‌ای از ادعاهای استاندارد مطابق با مشخصات JWT، شامل انقضای ۱ ساعته و همچنین یک ادعای اضافی ایجاد می‌کند. می‌توانید هر تعداد ادعای اضافی که می‌خواهید را اضافه کنید. برای جزئیات بیشتر در مورد الزامات و گزینه‌های هر عنصر در این سیاست نمونه، به مرجع Element مراجعه کنید.

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

JWT حاصل این هدر را خواهد داشت…

{
  "typ" : "JWT", 
  "alg" : "HS256",
  "kid" : "1918290"
}

... و یک payload با محتویاتی مانند این خواهد داشت:

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "show",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

ارزش ادعاهای iat ، exp و jti متفاوت خواهد بود.

یک JWT امضا شده با الگوریتم RS256 ایجاد کنید

این سیاست نمونه، یک JWT جدید تولید می‌کند و آن را با استفاده از الگوریتم RS256 امضا می‌کند. تولید امضای RS256 به یک کلید خصوصی RSA متکی است که باید به صورت رمزگذاری شده با PEM ارائه شود. برای مثال کامل، از جمله نحوه درخواست به این سیاست، به ویدیوی بالا مراجعه کنید.

وقتی این اقدام سیاستی آغاز می‌شود، Edge، JWT، شامل ادعاها را رمزگذاری و به صورت دیجیتالی امضا می‌کند. برای کسب اطلاعات در مورد بخش‌های یک JWT و نحوه رمزگذاری و امضای آنها، به RFC7519 مراجعه کنید.

<GenerateJWT name="JWT-Generate-RS256">
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

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

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

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

مرجع سیاست، عناصر و ویژگی‌های سیاست Generate JWT را شرح می‌دهد.

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

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

<GenerateJWT name="JWT" continueOnError="false" enabled="true" async="false">

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

<نام نمایشی>

<DisplayName>Policy Display Name</DisplayName>

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

<الگوریتم>

<Algorithm>algorithm-here</Algorithm>

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

<مخاطب>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

این سیاست یک JWT تولید می‌کند که حاوی یک aud claim است که روی مقدار مشخص شده تنظیم شده است. این claim گیرنده‌هایی را که JWT برای آنها در نظر گرفته شده است، شناسایی می‌کند. این یکی از claimهای ثبت شده ذکر شده در RFC7519 است.

<ادعاهای اضافی/ادعا>

<AdditionalClaims>
    <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'/>
</AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

به شما امکان می‌دهد جفت(های) نام/مقدار اضافی را در payload JWT مشخص کنید. می‌توانید claim را به صراحت به عنوان رشته، عدد، مقدار بولی، نگاشت یا آرایه مشخص کنید. یک نگاشت به سادگی مجموعه‌ای از جفت‌های نام/مقدار است.

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

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

وقتی عنصر <Claim> را اضافه می‌کنید، نام‌های ادعا هنگام پیکربندی سیاست به صورت ایستا تنظیم می‌شوند. به عنوان یک جایگزین، می‌توانید یک شیء JSON برای مشخص کردن نام‌های ادعا ارسال کنید. از آنجا که شیء JSON به عنوان یک متغیر ارسال می‌شود، نام‌های ادعا در JWT تولید شده در زمان اجرا تعیین می‌شوند.

برای مثال:

<AdditionalClaims ref='json_claims'/>

جایی که متغیر json_claims شامل یک شیء JSON به شکل زیر است:

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

JWT تولید شده شامل تمام ادعاهای موجود در شیء JSON است.

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

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

جفت(های) نام/مقدار ادعایی اضافی را در هدر JWT قرار می‌دهد.

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

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

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

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

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

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

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

<ادعاهای سفارشی>

نکته: در حال حاضر، وقتی یک سیاست GenerateJWT جدید را از طریق رابط کاربری اضافه می‌کنید، یک عنصر CustomClaims اضافه می‌شود. این عنصر کاربردی نیست و نادیده گرفته می‌شود. عنصر صحیح برای استفاده، <AdditionalClaims> است. رابط کاربری بعداً برای اضافه کردن عناصر صحیح به‌روزرسانی خواهد شد.

<منقضی می‌شود>

<ExpiresIn>time-value-here</ExpiresIn>

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

<شناسه>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

یک JWT با ادعای jti خاص تولید می‌کند. وقتی مقدار متن و ویژگی ref هر دو خالی باشند، این سیاست یک jti حاوی یک UUID تصادفی تولید می‌کند. ادعای JWT ID (jti) یک شناسه منحصر به فرد برای JWT است. برای اطلاعات بیشتر در مورد jti، به RFC7519 مراجعه کنید.

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

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<صادرکننده>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

این سیاست یک JWT تولید می‌کند که حاوی یک ادعا با نام iss است و مقداری که روی مقدار مشخص شده تنظیم شده است. ادعایی که صادرکننده JWT را شناسایی می‌کند. این یکی از مجموعه ادعاهای ثبت شده ذکر شده در RFC7519 است.

<قبلاً نه>

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

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

مقادیر زمانی معتبر برای عنصر NotBefore برای مقادیر زمانی مطلق

برای مقادیر زمانی نسبی، یک عدد صحیح و یک دوره زمانی مشخص کنید، برای مثال:

• ده‌ها
• ۶۰ متر
• ۱۲ ساعت

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

<OutputVariable>jwt-variable</OutputVariable>

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

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

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

or

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

شناسه کلید (kid) را برای درج در هدر JWT مشخص می‌کند. فقط زمانی استفاده می‌شود که الگوریتم یکی از 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 را مشخص می‌کند که برای امضای JWT استفاده می‌شود. از ویژگی 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) را برای قرار گرفتن در هدر JWT یک JWT امضا شده با الگوریتم 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 بایت است. استفاده از کلید با قدرت کمتر باعث خطای زمان اجرا می‌شود.

<موضوع>

<Subject>subject-string-here</Subject>

<Subject ref="flow_variable" />

برای مثال:

<Subject ref="apigee.developer.email"/>

این سیاست یک JWT تولید می‌کند که شامل یک sub claim است و روی مقدار مشخص شده تنظیم شده است. این claim موضوع JWT را شناسایی یا در مورد آن بیانیه‌ای صادر می‌کند. این یکی از مجموعه‌های استاندارد claimهای ذکر شده در RFC7519 است.

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

سیاست Generate JWT متغیرهای جریان را تنظیم نمی‌کند.

مرجع خطا

این بخش کدهای خطا و پیام‌های خطایی را که برگردانده می‌شوند و متغیرهای خطا را که توسط Edge تنظیم می‌شوند، هنگامی که این خط‌مشی خطا را راه‌اندازی می‌کند، توضیح می‌دهد. این اطلاعات برای دانستن اینکه آیا در حال توسعه قوانین خطا برای رسیدگی به خطاها هستید، مهم است. برای کسب اطلاعات بیشتر، آنچه را که باید در مورد خطاهای خط مشی و مدیریت خطاها بدانید را ببینید.

خطاهای زمان اجرا

این خطاها ممکن است هنگام اجرای سیاست رخ دهند.

خطاهای استقرار

این خطاها ممکن است زمانی رخ دهند که یک پروکسی حاوی این خط مشی را مستقر می کنید.

متغیرهای خطا

این متغیرها زمانی تنظیم می شوند که یک خطای زمان اجرا رخ دهد. برای اطلاعات بیشتر، به آنچه باید در مورد خطاهای خط مشی بدانید مراجعه کنید.

نمونه پاسخ خطا

برای رسیدگی به خطا، بهترین روش به دام انداختن قسمت errorcode در پاسخ به خطا است. به متن موجود در faultstring تکیه نکنید، زیرا ممکن است تغییر کند.

مثال قانون خطا

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>