مروری بر سیاست های JWS و JWT

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

این مبحث اطلاعات کلی درباره JWT (JSON Web Token) و JWS (JSON Web Signature) و خط‌مشی‌های Apigee JWS/JWT را ارائه می‌دهد که ممکن است برای توسعه‌دهندگان پروکسی Apigee جالب باشد.

مقدمه

هر دو JWS و JWT معمولاً برای به اشتراک گذاشتن ادعاها یا ادعاها بین برنامه های کاربردی متصل استفاده می شوند. خط‌مشی‌های JWS/JWT پروکسی‌های Edge API را قادر می‌سازد:

  • یک JWT یا JWS امضا شده ایجاد کنید .
  • JWT یا JWS امضا شده و ادعاهای موجود در JWS/JWT را تأیید کنید .
  • یک JWT یا JWS امضا شده را بدون تایید امضا رمزگشایی کنید .

در دو مورد اخیر، خط‌مشی متغیرهایی را نیز تعیین می‌کند که به سیاست‌های اضافی یا خود سرویس‌های پشتیبان اجازه می‌دهد ادعاهای تایید شده را بررسی کنند و بر اساس آن ادعاها تصمیم بگیرند.

هنگام استفاده از خط‌مشی تأیید JWS/JWT، JWS/JWT نامعتبر رد می‌شود و منجر به شرایط خطا می‌شود. به طور مشابه، هنگام استفاده از خط مشی Decode JWS/JWT، یک JWS/JWT نادرست منجر به یک شرایط خطا می شود.

ویدیوها

برای معرفی سریع JWT یک ویدیوی کوتاه تماشا کنید. در حالی که این ویدیو مختص تولید یک JWT است، بسیاری از مفاهیم برای JWS یکسان است.

چه ویدیوی کوتاهی برای کسب اطلاعات بیشتر در مورد ساختار JWT.

موارد استفاده کنید

می توانید از سیاست های JWS/JWT برای موارد زیر استفاده کنید:

  • یک JWS/JWT جدید در هر دو طرف پراکسی یا نقطه پایانی یک پراکسی Edge ایجاد کنید. به عنوان مثال، ممکن است یک جریان درخواست پروکسی ایجاد کنید که یک JWS/JWT ایجاد کرده و آن را به یک کلاینت برمی گرداند. یا، ممکن است یک پروکسی طراحی کنید تا یک JWS/JWT در جریان درخواست هدف ایجاد کند و آن را به درخواست ارسال شده به هدف متصل کند. این ادعاها سپس برای فعال کردن خدمات پشتیبان برای اعمال پردازش امنیتی بیشتر در دسترس خواهند بود.
  • ادعاها را از یک JWS/JWT که از درخواست‌های مشتری ورودی، از پاسخ‌های سرویس هدف، از پاسخ‌های خط‌مشی Callout خدمات یا از منابع دیگر به‌دست می‌آید، تأیید و استخراج کنید. Edge امضای یک JWS/JWT را تأیید می‌کند، آیا JWS/JWT توسط شخص ثالث تولید شده است یا توسط خود Edge، با استفاده از الگوریتم‌های RSA یا HMAC.
  • یک JWS/JWT را رمزگشایی کنید. رمزگشایی زمانی که در هماهنگی با خط‌مشی تأیید JWS/JWT استفاده می‌شود، زمانی که ارزش یک ادعا (JWT) یا هدر (JWS/JWT) از داخل JWS/JWT باید قبل از تأیید JWS/JWT مشخص باشد، بسیار مفید است.

قطعات یک JWS/JWT

یک JWS/JWT امضا شده، اطلاعات را در سه قسمت که با نقطه از هم جدا شده اند، رمزگذاری می کند: هدر، بارگذاری و امضا:

header.payload.signature
  • خط مشی Generate JWS/JWT هر سه بخش را ایجاد می کند.
  • خط مشی Verify JWS/JWT هر سه بخش را بررسی می کند.
  • خط مشی Decode JWS/JWT فقط هدر و بار را بررسی می کند.

یک JWS همچنین از فرمت جدا شده ای پشتیبانی می کند که بار را از JWS حذف می کند:

header..signature

با یک JWS جدا، محموله به طور جداگانه از JWS ارسال می شود. شما از عنصر <DetachedContent> در خط مشی Verify JWS برای تعیین بار خام و رمزگذاری نشده JWS استفاده می کنید. سپس خط مشی Verify JWS با استفاده از هدر و امضا در JWS و بار مشخص شده توسط عنصر <DetachedContent> ، JWS را تأیید می کند.

برای کسب اطلاعات بیشتر در مورد توکن ها و نحوه رمزگذاری و امضای آنها، نگاه کنید به:

تفاوت بین JWS و JWT

می‌توانید از JWT یا JWS برای اشتراک‌گذاری ادعاها یا ادعاها بین برنامه‌های متصل استفاده کنید. تفاوت عمده بین این دو در نمایش بار است:

  • JWT
    • payload همیشه یک شی JSON است
    • محموله همیشه به JWT متصل است
    • هدر typ توکن همیشه روی JWT تنظیم می شود
  • JWS
    • محموله را می توان با هر قالبی نشان داد، مانند یک شی JSON، جریان بایت، جریان هشت تایی و موارد دیگر
    • لازم نیست محموله به JWS متصل شود

از آنجایی که قالب JWT همیشه از یک شی JSON برای نشان دادن بار استفاده می‌کند، خط‌مشی‌های Edge Generate JWT و Verify JWT برای مدیریت نام‌های ادعای ثبت‌شده رایج، مانند aud ، iss ، sub ، و موارد دیگر پشتیبانی ایجاد کرده‌اند. این بدان معناست که می‌توانید از عناصر خط‌مشی Generate JWT برای تنظیم این ادعاها در محموله و از عناصر سیاست تأیید JWT برای تأیید مقادیر آنها استفاده کنید. برای اطلاعات بیشتر به بخش نام‌های ادعای ثبت شده در مشخصات JWT مراجعه کنید.

خط مشی Generate JWT همراه با پشتیبانی از نام‌های ادعای ثبت‌شده خاص، مستقیماً از افزودن ادعاهایی با نام‌های دلخواه به JWT پشتیبانی می‌کند. هر ادعا یک جفت نام/مقدار ساده است که مقدار آن می تواند از نوع عدد، بولی، رشته، نقشه یا آرایه باشد.

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

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

خط‌مشی‌های JWS/JWT Verification و JWS/JWT Generation از الگوریتم‌های RSA، RSASSA-PSS، ECDSA، و HMAC با استفاده از جمع‌های بررسی SHA2 با قدرت بیت ۲۵۶، ۳۸۴ یا ۵۱۲ پشتیبانی می‌کنند. خط‌مشی رمزگشایی JWS/JWT بدون توجه به الگوریتم کار می‌کند. برای امضای JWS/JWT استفاده می شود.

الگوریتم HMAC

الگوریتم HMAC برای ایجاد امضا (همچنین به عنوان امضای JWS/JWT شناخته می شود) و برای تأیید امضا بر یک راز مشترک، معروف به کلید مخفی، متکی است.

حداقل طول کلید مخفی به قدرت بیت الگوریتم بستگی دارد:

  • HS256: حداقل طول کلید 32 بایت
  • HS386: حداقل طول کلید 48 بایت
  • HS512: حداقل طول کلید 64 بایت

الگوریتم RSA

الگوریتم RSA از یک جفت کلید عمومی/خصوصی برای امضای رمزنگاری استفاده می کند. با امضاهای RSA، طرف امضاکننده از یک کلید خصوصی RSA برای امضای JWS/JWT استفاده می‌کند و طرف تأییدکننده از کلید عمومی RSA منطبق برای تأیید امضا در JWS/JWT استفاده می‌کند. هیچ الزامی برای اندازه در کلیدها وجود ندارد.

الگوریتم RSASSA-PSS

الگوریتم RSASSA-PSS به روز رسانی الگوریتم RSA است. مانند RSS، RSASSA-PSS از یک جفت کلید عمومی/خصوصی RSA برای امضای رمزنگاری استفاده می‌کند. فرمت کلید مانند RSS است. طرف امضاکننده از یک کلید خصوصی برای امضای JWS/JWT استفاده می‌کند و طرف تأییدکننده از کلید عمومی منطبق برای تأیید امضای JWS/JWT استفاده می‌کند. هیچ الزامی برای اندازه در کلیدها وجود ندارد.

الگوریتم ECDSA

الگوریتم امضای دیجیتال منحنی بیضی (ECDSA) یک الگوریتم رمزنگاری منحنی بیضوی با منحنی P-256، P-384، و P-521 است. هنگامی که از الگوریتم های ECDSA استفاده می کنید، الگوریتم نوع کلید عمومی و خصوصی را که باید مشخص کنید تعیین می کند:

الگوریتم منحنی نیاز کلیدی
ES256 P-256 یک کلید تولید شده از منحنی P-256 (همچنین به عنوان secp256r1 یا prime256v1 شناخته می شود)
ES384 P-384 یک کلید تولید شده از منحنی P-384 (همچنین به عنوان secp384r1 شناخته می شود)
ES512 P-521 یک کلید تولید شده از منحنی P-521 (همچنین به عنوان secp521r1 شناخته می شود)

الگوریتم های رمزگذاری کلید

خط‌مشی‌های JWS/JWT از همه الگوریتم‌های رمزگذاری کلیدی پشتیبانی شده توسط OpenSSL پشتیبانی می‌کنند.

استفاده از مجموعه کلیدهای وب JSON (JWKS) برای تأیید JWS/JWT

هنگامی که یک JWS/JWT امضا شده را تأیید می‌کنید، باید کلید عمومی را ارائه دهید که با کلید خصوصی مورد استفاده برای امضای رمز مرتبط است. شما دو گزینه برای ارائه کلید عمومی برای تأیید خط مشی های JWS/JWT دارید:

  • از مقدار واقعی کلید عمومی (معمولاً در متغیر جریان ارائه می شود) استفاده کنید
  • از یک کلید عمومی پیچیده شده در JWKS استفاده کنید.

درباره JWKS

JWKS یک ساختار JSON است که مجموعه‌ای از کلیدهای وب JSON (JWKs) را نشان می‌دهد. JWK یک ساختار داده JSON است که یک کلید رمزنگاری را نشان می دهد. JWK و JWKS در RFC7517 توضیح داده شده اند. نمونه های JKWS را در ضمیمه A ببینید. نمونه مجموعه کلیدهای وب JSON

ساختار JWKS

RFC7517 عناصر کلیدی JWKS را برای هر نوع کلید، مانند "RSA" یا "EC" توصیف می کند. به عنوان مثال، بسته به نوع کلید، این پارامترها می توانند شامل موارد زیر باشند:

  • kty - نوع کلید، مانند "RSA" یا "EC".
  • kid (شناسه کلید) - می تواند هر مقدار دلخواه باشد (بدون تکرار در مجموعه کلید). اگر JWT ورودی دارای شناسه کلیدی باشد که در مجموعه JWKS وجود دارد، خط‌مشی از کلید عمومی صحیح برای تأیید امضای JWS/JWT استفاده می‌کند.

در زیر نمونه هایی از عناصر اختیاری و مقادیر آنها آورده شده است:

  • alg - الگوریتم کلید. باید با الگوریتم امضا در JWS/JWT مطابقت داشته باشد.
  • استفاده - در صورت وجود، باید علامت باشد.

JWKS زیر شامل عناصر و مقادیر مورد نیاز است و در Edge معتبر است (از https://www.googleapis.com/oauth2/v3/certs ): 

{  
   "keys":[  
      {  
         "kty":"RSA",
         "alg":"RS256",
         "use":"sig",
         "kid":"ca04df587b5a7cead80abee9ea8dcf7586a78e01",
         "n":"iXn-WmrwLLBa-QDiToBozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt7-V7KDjCq0_Nkd-X9rMRV5LKgCa0_F8YgI30QS3bUm9orFryrdOc65PUIVFVxIwMZuGDY1hj6HEJVWIr0CZdcgNIll06BasclckkUK4O-Eh7MaQrqb646ghFlG3zlgk9b2duHbDOq3s39ICPinRQWC6NqTYfqg7E8GN_NLY9srUCc_MswuUfMJ2cKT6edrhLuIwIj_74YGkpOwilr2VswKsvJ7dcoiJxheKYvKDKtZFkbKrWETTJSGX2Xeh0DFB0lqbKLVvqkM2lFU2Qx1OgtTnrw",
         "e":"AQAB"
      },
      {
          "kty":"EC",
          "alg":"ES256",
          "use":"enc",
          "kid":"k05TUSt7-V7KDjCq0_N"
          "crv":"P-256",
          "x":"Xej56MungXuFZwmk_xccvsMpCtXmqhvEEMCmHyAmKF0",
          "y":"Bozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt",
      }
   ]
}

طراحی پروکسی خود برای استفاده از JWKS

هنگامی که یک JWS/JWT از یک صادرکننده دریافت می‌شود، اغلب صادرکننده یک شناسه کلیدی (یا بچه) را در هدر JWS/JWT درج می‌کند. کلید به گیرنده JWS/JWT می گوید که چگونه کلید عمومی یا مخفی را که برای تأیید امضای امضا شده روی JWS/JWT لازم است، پیدا کند.

به عنوان مثال، فرض کنید یک صادرکننده JWT را با یک کلید خصوصی امضا می کند. "شناسه کلید" کلید عمومی منطبق را برای تأیید JWT شناسایی می کند. فهرست کلیدهای عمومی معمولاً در برخی از نقاط پایانی شناخته شده موجود است، برای مثال: https://www.googleapis.com/oauth2/v3/certs .

این دنباله اصلی است که Edge (یا هر پلتفرمی که با JWKS کار می کند) برای کار با JWS/JWT که دارای JWKS است باید انجام دهد:

  1. هدر JWS/JWT را برای یافتن شناسه کلید (کودک) بررسی کنید.
  2. هدر JWS/JWT را بررسی کنید تا الگوریتم امضا (alg)، مانند RS256 را بیابید.
  3. فهرست کلیدها و شناسه‌ها را از JWKS نقطه پایانی معروف برای یک صادرکننده خاص بازیابی کنید.
  4. اگر کلید JWKS الگوریتم را مشخص می کند، کلید عمومی را با شناسه کلید ذکر شده در سربرگ JWS/JWT و با الگوریتم منطبق از لیست کلیدها استخراج کنید.
  5. از آن کلید عمومی برای تأیید امضا در JWS/JWT استفاده کنید.

به عنوان یک توسعه دهنده پروکسی Edge API، برای انجام تأیید JWS/JWT باید موارد زیر را انجام دهید:

  1. فهرست کلیدها و شناسه‌ها را از نقطه پایانی شناخته شده برای یک صادرکننده خاص بازیابی کنید. برای این مرحله می توانید از یک خط مشی Callout Service استفاده کنید.
  2. در سیاست تأیید JWS/JWT، مکان JWS/JWT را در عنصر <Source> و بار JWKS را در عنصر <PublicKey/JWKS> مشخص کنید. به عنوان مثال، برای سیاست VerifyJWT: 
    <VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>json.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <JWKS ref="public.jwks"/>
    </PublicKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>    
    </AdditionalClaims>
</VerifyJWT>

خط مشی Verify JWT همه کارهای دیگر را انجام می دهد:

  • اگر کلیدی با شناسه کلیدی که با شناسه کلید (کودک) اعلام شده در JWT مطابقت دارد در JWKS یافت نشد، خط مشی Verify JWT خطایی ایجاد می کند و JWT را تأیید نمی کند.
  • اگر JWT ورودی دارای شناسه کلید (kid) در هدر نباشد، این نگاشت از keyid-to-verification-key امکان پذیر نیست.

به عنوان طراح پروکسی، شما مسئول تعیین کلید مورد استفاده هستید. در برخی موارد ممکن است این یک کلید ثابت و با کد سخت باشد.