خط‌مشی GenerateJWT

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

چه

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

ویدیو

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

نمونه‌ها

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

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

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

وقتی این کنش خط‌مشی راه‌اندازی می‌شود، Edge سرصفحه و محتوای JWT را کدبندی می‌کند، سپس JWT را به‌صورت دیجیتالی امضا می‌کند. برای دیدن نمونه کامل، ازجمله نحوه درخواست برای خط‌مشی، ویدیو بالا را ببینید.

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

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

… و پایه‌باری با محتوایی شبیه به این خواهد داشت:

{ 
  "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 «توکن وب JSON» را کدبندی و امضا می‌کند، ازجمله ادعاها. برای آشنایی با بخش‌های 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>

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

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

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

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

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

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

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

<AdditionalClaims/Claim>

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

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

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

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

وقتی عنصر <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>

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

<CriticalHeaders>

<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 ناموفق باشد.

<CustomClaims>

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

<ExpiresIn>

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

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

<Id>

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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<Issuer>

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

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

<NotBefore>

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

<OutputVariable>jwt-variable</OutputVariable>

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

<PrivateKey/Id>

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

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

<Subject>

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

<Subject ref="flow_variable" />

برای مثال:

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

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

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

خط‌مشی «تولید 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>