معرفی کتابخانه python-jose در پایتون

python-jose یک پیاده‌سازی از استانداردهای JOSE (JSON Object Signing and Encryption) برای پایتون است که قابلیت‌هایی مثل ساخت و بررسی JWT (JSON Web Token)، امضای دیجیتال (JWS)، و کار با کلیدهای JWK را فراهم می‌کند. این کتابخانه برای پروژه‌هایی که نیاز به احراز هویت مبتنی بر توکن یا تبادل امن اطلاعات دارند، بسیار کاربردی است.

چرا از python-jose استفاده کنیم؟

• پیاده‌سازی ساده و روان برای ایجاد و اعتبارسنجی JWT.
• پشتیبانی از الگوریتم‌های رایج مانند HS256، RS256، ES256 و …
• امکان کار با JWK / JWKS برای اعتبارسنجی توکن‌های صادرشده توسط هویت‌دهنده‌های خارجی (مانند Auth0 یا Google).
• امکانات مدیریتی در بررسی ادعاها (claims) مانند audience، issuer و expiration.

نصب

برای استفاده از الگوریتم‌های مبتنی بر کلیدهای نامتقارن (RS*, ES*) لازم است افزونه cryptography نصب شود:

pip install python-jose[cryptography]

این دستور کتابخانه اصلی و پشتیبانی‌های لازم برای کلیدهای RSA/EC را نصب می‌کند.

مثال پایه: تولید و بررسی JWT

from jose import jwt

# ساخت یک توکن با HMAC-SHA256
payload = {"sub": "1234567890", "name": "Alice", "admin": True}
secret = "my-super-secret"
token = jwt.encode(payload, secret, algorithm="HS256")

# بررسی و دیکد توکن
decoded = jwt.decode(token, secret, algorithms=["HS256"])
print(decoded)

در این مثال، با استفاده از کلید متقارن (secret) و الگوریتم HS256 یک توکن ساخته و سپس همان کلید برای دیکد و اعتبارسنجی استفاده شده است. تابع jwt.encode یک رشته توکن به فرم JWT برمی‌گرداند و jwt.decode آن را به دیکشنری پایتون تبدیل می‌کند.

بررسی ادعاها (claims) و گزینه‌ها

decoded = jwt.decode(
    token,
    secret,
    algorithms=["HS256"],
    audience="my_audience",
    issuer="https://my.issuer/",
    options={"verify_exp": True}
)

در این مثال از پارامترهای audience و issuer برای بررسی ادعاها استفاده شد. همچنین options به شما امکان کنترل بررسی expiration یا سایر بررسی‌ها را می‌دهد.

کار با کلیدهای عمومی (RSA) و RS256

در سیستم‌هایی که کلید خصوصی در سرور صادرکننده است و کلید عمومی در مصرف‌کننده استفاده می‌شود، معمولاً از RS256 استفاده می‌شود. نمونه:

from jose import jwt

private_key = open("private.pem").read()
public_key = open("public.pem").read()

token = jwt.encode({"sub": "42"}, private_key, algorithm="RS256")
claims = jwt.decode(token, public_key, algorithms=["RS256"])

در این حالت jwt.encode با کلید خصوصی امضا را تولید می‌کند و jwt.decode با کلید عمومی آن را بررسی می‌کند. مطمئن شوید فرمت PEM کلیدها صحیح است.

اعتبارسنجی توکن‌های صادرشده توسط سرویس‌های خارجی (JWKS)

یک سناریوی رایج دریافت JWKS از یک endpoint (مثلاً https://example/.well-known/jwks.json) و انتخاب کلید براساس header توکن است. الگوی کامل:

import requests
from jose import jwk, jwt
from jose.utils import base64url_decode

jwks = requests.get("https://example.com/.well-known/jwks.json").json()
unverified_header = jwt.get_unverified_header(token)

for key in jwks["keys"]:
    if key["kid"] == unverified_header["kid"]:
        public_key = jwk.construct(key)
        message, encoded_sig = token.rsplit(".", 1)
        decoded_sig = base64url_decode(encoded_sig.encode("utf-8"))
        if public_key.verify(message.encode("utf-8"), decoded_sig):
            claims = jwt.decode(token, public_key.to_pem().decode("utf-8"), algorithms=[unverified_header["alg"]])
            break

در این مثال ابتدا header توکن بدون اعتبارسنجی خوانده می‌شود تا kid و alg استخراج شوند. سپس در مجموعه کلیدهای JWKS به دنبال همان kid گشته و با استفاده از jwk.construct کلید ساخته می‌شود. پس از تأیید امضا، می‌توان با jwt.decode توکن را دیکد و ادعاها را بررسی کرد.

نکات امنیتی و بهترین شیوه‌ها

• هرگز الگوریتم را از توکن خوانده و blind trust نکنید. همواره لیست الگوریتم‌های مجاز را به jwt.decode ارسال کنید.
• از بررسی audience و issuer برای جلوگیری از استفادهٔ توکن در مقصدهای نادرست استفاده کنید.
• از نگهداری امن کلیدها و روتیشن (عوض کردن) دوره‌ای کلیدهای خصوصی غفلت نکنید.
• مراقب ضعف زیادی مانند alg=none باشید؛ همیشه تأیید امضا را فعال نگه دارید.

خطاها و مدیریت استثناء

python-jose چند استثناء رایج دارد که باید مدیریت شوند، مثل ExpiredSignatureError برای توکن‌های منقضی و JWTClaimsError برای ادعاهای نامعتبر. نمونه مدیریت:

from jose import jwt
from jose.exceptions import JWTError, ExpiredSignatureError, JWTClaimsError

try:
    claims = jwt.decode(token, key, algorithms=["RS256"], audience="my_aud")
except ExpiredSignatureError:
    print("Token expired")
except JWTClaimsError:
    print("Invalid claims")
except JWTError:
    print("General JWT error")

از این استثناء‌ها برای اطلاع‌دهی دقیق‌تر و پاسخ مناسب در سطح اپلیکیشن استفاده کنید.

مقایسه خلاصه الگوریتم‌ها

جمع‌بندی و توصیه‌های عملی

python-jose یک ابزار قدرتمند و مناسب برای مدیریت JWT در پایتون است. با رعایت نکات امنیتی (مثل بررسی ادعاها، انتخاب الگوریتم‌های مجاز، و استفاده از JWKS برای کلیدهای عمومی) می‌توانید لایهٔ امنی برای احراز هویت و تبادل اطلاعات در سرویس‌های خود بسازید. برای پروژه‌های تولیدی، نصب با افزونه cryptography و استفاده از کلیدهای مناسب (RSA/EC) معمولاً توصیه می‌شود.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال