تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتيح Tink إنشاء رموز JWT وإثبات صحتها، وهي معيار مستخدَم على نطاق واسع على الويب. يوفّر تنفيذ JWT في Tink مجموعة فرعية من معيار JWT
المحدّد في RFC 7519 التي يرى فريق Tink أنّها آمنة للاستخدام
وتناسب مكتبة Tink بشكل جيد.
لا تتوافق مكتبة Tink مع أجزاء من المعيار نادرًا ما يتم استخدامها أو يصعب استخدامها بشكل صحيح. في ما يلي القيود:
تتوافق مكتبة Tink مع العناوين typ وalg وkid فقط. لا تتوافق مع جميع العناوين الأخرى.
لا تسمح مكتبة Tink بتحليل الرموز المميزة قبل التحقّق من صحة التوقيع أو رمز مصادقة الرسالة (MAC).
توقيعات JWT
إذا كانت جهات مختلفة تنشئ الرموز المميزة وتثبت صحتها، عليك استخدام مفاتيح غير متماثلة مع العناصر الأساسية JwtPublicKeySign وJwtPublicKeyVerify.
يُستخدَم المفتاح الخاص لإنشاء الرموز المميزة، ويُستخدَم المفتاح العام للتحقّق من صحة الرموز المميزة. الخوارزميات التي تتيحها هذه العناصر الأساسية هي: ES256 وES384 وES512 وRS256 وRS384 وRS512 وPS256 وPS384 وPS512.
اختيار نوع المفتاح
تستخدم توقيعات JWT أنواع مفاتيح مختلفة عن التوقيع الرقمي العادي في Tink. هذا الإجراء ضروري لأنّ بعض البيانات الوصفية (مثل alg وkid) يجب تخزينها مع المفتاح.
ننصح باستخدام JWT_ES256 في معظم حالات الاستخدام. تحتوي الرموز المميّزة التي يتم إنشاؤها باستخدام نوع المفتاح هذا دائمًا على عنوان kid. إذا كنت تفضّل رموزًا مميّزة أقصر قليلاً بدون عنوان kid، اختَر نوع المفتاح JWT_ES256_RAW. للاطّلاع على جميع أنواع المفاتيح المتوافقة، راجِع أنواع المفاتيح المتوافقة.
توزيع مجموعة المفاتيح العامة
تسمح Tink بتحويل مجموعات المفاتيح العامة إلى تنسيق JWK Sets
المحدّد في RFC 7517، والذي تفهمه معظم مكتبات JWT، والعكس.
لا تتيح Tink تصدير مفاتيح JWT العامة بأي تنسيق آخر. والسبب في ذلك هو أنّ التنسيقات الأخرى لا تحتوي على البيانات الوصفية alg وkid التي سيتم استخدامها في عملية التحقّق، ما يجعل استخدامها أكثر عرضة للأخطاء وقد يصعّب عملية تدوير المفاتيح.
من الأفضل عدم مشاركة مجموعة المفاتيح العامة مرة واحدة فقط، بل توفير طريقة لتعديلها تلقائيًا. (إذا لم يكن الأمر كذلك، سيكون من الصعب جدًا التبديل إلى مفتاح جديد). ويتم ذلك غالبًا من خلال نشر مجموعة المفاتيح العامة على عنوان URL موثوق وآمن. على الخادم الذي يتحقّق من الرموز المميزة أن يعيد جلب مجموعة المفاتيح العامة بشكل دوري من عنوان URL هذا، مثلاً مرة واحدة في اليوم. لتدوير المفتاح، يجب إضافة المفتاح العام الجديد إلى مجموعة المفاتيح العامة قبل يوم واحد على الأقل من استخدامه لتوقيع الرموز المميزة. وفي حال عدم تنفيذ ذلك، سترفض الخوادم التي لا تزال تستخدم مجموعة المفاتيح العامة القديمة الرموز المميزة الجديدة الموقَّعة باستخدام المفتاح الخاص الجديد.
JWT MAC
تتيح Tink أيضًا استخدام رموز JWT المميزة مع المفاتيح المتماثلة باستخدام الوحدة الأولية JwtMac. لا تستخدِم هذا النوع الأساسي إلا إذا كانت الجهة نفسها هي التي تنشئ الرموز المميزة وتتحقّق منها. الخوارزميات التي يتيحها هذا العنصر الأساسي هي HS256 وHS384 وHS512.
اختيار نوع المفتاح
تختلف أنواع مفاتيح MAC الخاصة برمز JWT عن أنواع مفاتيح MAC العادية. ننصحك باستخدام
JWT_HS256 في معظم حالات الاستخدام.
تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eTink supports creating and validating JSON Web Tokens (JWTs) using a secure subset of the RFC 7519 standard.\u003c/p\u003e\n"],["\u003cp\u003eIt offers both asymmetric and symmetric key cryptography options for signing and verifying JWTs, with various algorithms like ES256, RS256, HS256, and others.\u003c/p\u003e\n"],["\u003cp\u003eTink emphasizes secure key management practices, including using distinct key types for JWTs and enabling public keyset distribution in the JWK Sets format for easier sharing and rotation.\u003c/p\u003e\n"],["\u003cp\u003eHowever, it has certain limitations, such as supporting only the JWS Compact Serialization format and specific headers, while excluding features like JWE and the 'None' algorithm.\u003c/p\u003e\n"],["\u003cp\u003eFor optimal security, Tink enforces signature/MAC verification before parsing tokens and recommends periodic public keyset updates to facilitate key rotation and minimize disruptions.\u003c/p\u003e\n"]]],["Tink supports generating and verifying JWTs, implementing a secure subset of the standard. It utilizes JWS Compact Serialization, excluding JWS JSON Serialization and JWE. Supported headers are `typ`, `alg`, and `kid`; the `None` `alg` value is unsupported. Asymmetric keys (`JwtPublicKeySign`, `JwtPublicKeyVerify`) should be used between different entities, with supported algorithms including `ES256`, `RS256`, and `PS256`. Symmetric keys (`JwtMac`) are for same-entity usage, supporting `HS256`. Tink offers JWK Sets format conversion for public keys and recommends automated public keyset updates.\n"],null,["# JSON Web Tokens (JWTs)\n\nTink supports generating and verifying JWTs, which are a widely used standard on\nthe web. Tink's JWT implementation provides a *subset* of the JWT standard\ndefined in [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519 \"JSON Web Token (JWT)\") that the Tink team considers safe to use, and\nthat fits well into the Tink library.\n\nTink does not support parts of the standard that are rarely used or difficult to\nuse correctly. These are the limitations:\n\n- Tink only supports the [JWS Compact Serialization](https://datatracker.ietf.org/doc/html/rfc7515#section-3.1 \"JWS Compact Serialization\") format. [JWS\n JSON Serialization](https://datatracker.ietf.org/doc/html/rfc7515#section-3.2 \"JWS JSON Serialization\") and [JWE](https://datatracker.ietf.org/doc/html/rfc7516 \"JSON Web Encryption (JWE)\") are not supported.\n- Tink does not support the `None` value in the `alg` header.\n- Tink only supports the headers `typ`, `alg`, and `kid`. All other headers are not supported.\n- Tink does not allow tokens to be parsed before the signature or MAC is verified.\n\n### JWT Signatures\n\nIf tokens are generated and verified by different entities, then you should use\nasymmetric keys with the primitives `JwtPublicKeySign` and `JwtPublicKeyVerify`.\nThe private key is used to generate tokens, and the public key is used to verify\ntokens. The [algorithms](https://datatracker.ietf.org/doc/html/rfc7518#section-3) supported by these primitives are: `ES256`,\n`ES384`, `ES512`, `RS256`, `RS384`, `RS512`, `PS256`, `PS384` and `PS512`.\n\n#### Choose a key type\n\nJWT signatures use *different* key types than the normal digital signature in\nTink. This is needed because some metadata (such as `alg`and `kid`) needs to be\nstored with the key.\n\nWe recommend using `JWT_ES256` for most use cases. Tokens generated with this\nkey type always have a `kid` header. If you prefer slightly shorter tokens\nwithout a `kid` header, choose the key type `JWT_ES256_RAW`. For all supported\nkey types, see [Supported Key Types](/tink/supported-key-types#jwt_signature).\n\n#### Public keyset distribution\n\nTink allows public keysets to be converted to and from the JWK Sets format\ndefined in [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517#section-5), which most JWT libraries understand.\n| **Note:** Tink's JSON keyset serialization format is *not* a JWK Set and other libraries will probably not be able to read it.\n\nTink does not support exporting public JWT keys in any other format. The reason\nfor this is that other formats don't contain the `alg` and `kid` metadata to be\nused in the verification, which makes using them more error-prone and may make\nit more difficult to rotate keys.\n\nIt is preferable to not just share the public keyset once, but to provide a way\nto *automatically* update the public keyset. (If not, rotating to a new key is\nvery hard.) This is often done by publishing the public keyset on a trusted and\nsecured URL. A server that verifies tokens then has to periodically re-fetch the\npublic keyset from that URL, for example once per day. To rotate the key, the\nnew public key needs to be added to the public keyset *at least one day before*\nit is used to sign tokens. Otherwise the new tokens signed with the new private\nkey will be rejected by servers that still use the old public keyset.\n| **Note:** Some implementations re-fetch the public key as soon as a token with an unknown `kid` header is received. Implementing this logic is not possible in Tink, since the token is not parsed before it is verified. We don't recommend doing this anyway, as it may result in lots of extra requests to the keyset URL if malicious tokens with random `kid` headers are sent.\n\n### JWT MAC\n\nTink also supports JWT with symmetric keys with the primitive `JwtMac`. Only use\nthis primitive if the tokens are generated and verified by the same entity. The\n[algorithms](https://datatracker.ietf.org/doc/html/rfc7518#section-3) supported by this primitive are `HS256`, `HS384` and\n`HS512`.\n\n#### Choose a key type\n\nJWT MAC key types are *different* from normal MAC key types. We recommend using\n`JWT_HS256` for most use cases.\n\n### Example use cases\n\nSee [I want to create and verify JWTs](/tink/create-jwts)."]]
