ایجاد خط مشی JWT

شما در حال مشاهده اسناد 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 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>

<DisplayName>Policy Display Name</DisplayName>

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

<الگوریتم>

<Algorithm>algorithm-here</Algorithm>

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

<مخاطب>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

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

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

<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 جدید را از طریق UI اضافه می‌کنید، یک عنصر 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 ID (jti) یک شناسه منحصر به فرد برای JWT است. برای اطلاعات بیشتر در مورد jti، به RFC7519 مراجعه کنید.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<صادر کننده>

<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 برای مقادیر زمان مطلق

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

• دهه 10
• 60 متر
• ساعت 12

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

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

شناسه کلید (کودک) را مشخص می کند تا در هدر 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 32 بایت، برای HS384 48 بایت و برای HS512 64 بایت است. استفاده از یک کلید با قدرت کمتر باعث خطای زمان اجرا می شود.

<موضوع>

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

<Subject ref="flow_variable" />

به عنوان مثال:

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

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

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

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

مرجع خطا

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