رموز المصادقة وJWKS: التحقق من JWT في Didit

• https://<name>.auth.didit.me لتطبيق في بيئة الإنتاج،
• https://<name>.sandbox.auth.didit.me للتطبيق التجريبي،
• أو نطاقك المخصص، بعد تفعيله.

​

الاكتشاف والمفاتيح

• نوع الاستجابة code ونمط الاستجابة query.
• نوعَي المنح authorization_code وrefresh_token.
• طريقة PKCE S256 فقط. العملاء عامّون: لا يوجد سر للعميل، وclient_id هو معرّف تطبيقك.
• خوارزمية التوقيع ES256 (مفاتيح P-256).
• النطاقات openid وemail وphone وprofile وoffline_access.

​

التخزين المؤقت والتدوير

• لكل مفتاح kid، وتبدأ معرّفات المفاتيح الجديدة بـ k_. ويذكر كل رمز مفتاحه في ترويسة kid.
• تُدوَّر المفاتيح كل 30 يومًا. ينشر Didit المفتاح التالي قبل يوم من بدء توقيعه به، ويُبقي المفتاح السابق منشورًا ليوم بعد توقفه عن التوقيع. لذلك يستمر JWKS المخزّن مؤقتًا لمدة 5 دقائق في التحقق خلال التدوير.
• خزّن المفاتيح مؤقتًا بحسب kid. عندما يذكر رمز kid لا تملكه، فأعد جلب JWKS، مرة واحدة على الأكثر في الدقيقة، وارفض الرمز إذا بقي المفتاح مفقودًا.
• عندما يُبطل Didit مفتاحًا تعرّض للاختراق، يحذفه من JWKS فورًا، وترفض GET /session/ كل رمز وقّعه المفتاح. ويبدأ المفتاح البديل بالتوقيع فورًا، دون يوم النشر المسبق. أما JWKS المخزّن مؤقتًا حتى 5 دقائق قبل ذلك فيظل يقبل المفتاح المُبطل ولا يعرف البديل بعد، لذلك قد تفشل الرموز الجديدة في التحقق دون اتصال إلى أن يتجدد التخزين المؤقت.

​

بدء تسجيل الدخول

{issuer}/sign-in?redirect_uri=...&state=...&code_challenge=...&code_challenge_method=S256

​

استبدال الرمز

curl --fail-with-body "${DIDIT_AUTH_ISSUER}/token/" \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "authorization_code",
    "code": "CODE_FROM_CALLBACK",
    "code_verifier": "YOUR_PKCE_VERIFIER",
    "redirect_uri": "https://app.example.com/auth/callback"
  }'

{
  "access_token": "eyJhbGciOiJFUzI1NiIs...",
  "id_token": "eyJhbGciOiJFUzI1NiIs...",
  "refresh_token": "N4yZTl6y24YKYq77X_SO...",
  "token_type": "Bearer",
  "expires_in": 299,
  "session_id": "c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1"
}

​

مطالبات رمز الوصول

​

التحقق من رمز على الخادم لديك

1. يجب أن تكون alg هي ES256 وأن تكون typ هي at+jwt. ارفض أي خوارزمية أخرى، بما فيها none.
2. يجب أن يكون kid موجودًا في JWKS الخاص بتطبيقك، وأن يتم التحقق من التوقيع.
3. يجب أن تساوي iss جهة الإصدار المُعدّة لديك، وأن تساوي aud معرّف تطبيقك.
4. يجب أن تكون exp وiat صالحتين، مع السماح بفرق في ساعة النظام يصل إلى 60 ثانية، وأن تكون sub وsid وjti موجودة.
5. يجب أن تكون act تساوي null. يُوقَّع رمز وصول وكيل الذكاء الاصطناعي بالمفتاح نفسه، ويحمل typ وiss وaud نفسها، ولا تميّزه إلا act. ارفضه، ما لم تكن endpoint تقبل الوكلاء؛ ففي هذه الحالة اسمح فقط بما تمنحه act.scopes. ترفض GET /session/ دائمًا رمز الوكيل.

// npm install jose
import { createRemoteJWKSet, jwtVerify } from "jose";

const ISSUER = process.env.DIDIT_AUTH_ISSUER; // https://<name>.auth.didit.me
const AUDIENCE = process.env.DIDIT_APPLICATION_ID;
// Cache keys for 5 minutes; refetch an unknown kid at most once a minute.
const jwks = createRemoteJWKSet(new URL(`${ISSUER}/.well-known/jwks.json`), {
  cacheMaxAge: 5 * 60 * 1000,
  cooldownDuration: 60 * 1000,
});

export async function verifyAccessToken(token) {
  const { payload } = await jwtVerify(token, jwks, {
    issuer: ISSUER,
    audience: AUDIENCE,
    algorithms: ["ES256"],
    typ: "at+jwt",
    clockTolerance: 60,
    maxTokenAge: "5m", // also rejects an iat in the future
    requiredClaims: ["sub", "sid", "jti", "exp", "iat"],
  });
  if (payload.act !== null) throw new Error("agent tokens are not accepted");
  return payload; // payload.vendor_data is the person across Didit products
}

# pip install "pyjwt[crypto]"
import os
import threading
import time

import jwt

ISSUER = os.environ["DIDIT_AUTH_ISSUER"]  # https://<name>.auth.didit.me
AUDIENCE = os.environ["DIDIT_APPLICATION_ID"]
jwks = jwt.PyJWKClient(f"{ISSUER}/.well-known/jwks.json", lifespan=300)
refresh_lock = threading.Lock()
last_refresh = 0.0


def signing_key(kid: str | None) -> jwt.PyJWK:
    # PyJWKClient refetches for every unknown kid: limit it to once a minute.
    global last_refresh
    keys = {key.key_id: key for key in jwks.get_signing_keys()}
    if kid not in keys:
        with refresh_lock:
            if time.monotonic() - last_refresh >= 60:
                last_refresh = time.monotonic()
                fresh = jwks.get_signing_keys(refresh=True)
                keys = {key.key_id: key for key in fresh}
    if kid not in keys:
        raise jwt.InvalidTokenError("unknown signing key")
    return keys[kid]


def verify_access_token(token: str) -> dict:
    header = jwt.get_unverified_header(token)
    if header.get("typ") != "at+jwt":
        raise jwt.InvalidTokenError("not an access token")
    claims = jwt.decode(
        token,
        signing_key(header.get("kid")).key,
        algorithms=["ES256"],
        audience=AUDIENCE,
        issuer=ISSUER,
        leeway=60,
        options={"require": ["iss", "aud", "sub", "sid", "jti", "exp", "iat"]},
    )
    if "act" not in claims or claims["act"] is not None:
        raise jwt.InvalidTokenError("agent tokens are not accepted")
    return claims

​

التحقق من الجلسة

curl --fail-with-body "${DIDIT_AUTH_ISSUER}/session/" \
  -H "Authorization: Bearer $DIDIT_ACCESS_TOKEN"

​

تحديث الرموز

curl --fail-with-body "${DIDIT_AUTH_ISSUER}/token/" \
  -H 'Content-Type: application/json' \
  -d '{"grant_type": "refresh_token", "refresh_token": "YOUR_REFRESH_TOKEN"}'

• رمز التحديث سلسلة عشوائية، وصالح حتى تنتهي الجلسة.
• إعادة الاستخدام تُنهي الجلسة. عندما يصل رمز تحديث سبق استخدامه مرة أخرى، تعامله Didit بوصفه علامة على السرقة: فتُلغي الجلسة وتعيد 400 {"error": "invalid_grant"}. تتوقف رموز الجلسة عن العمل أيضًا، بما فيها الرموز الناتجة عن التحديث السابق: يفشل رمز التحديث الخاص بها، ويفشل رمز الوصول في GET /session/ فورًا، مع أنه يبقى قابلًا للتحقق دون اتصال حتى انتهاء صلاحيته، في غضون 5 دقائق.
• نفّذ تحديثًا واحدًا في كل مرة لكل جلسة، عبر علامات التبويب والأجهزة ومثيلات الخادم، واستبدل الرموز الثلاثة معًا.
• إذا فشل التحديث بالرمز 400 أو لم يتلقَّ ردًا، فابدأ تسجيل الدخول من جديد. لا تُعِد المحاولة بشكل أعمى: فإعادة المحاولة بعد تحديث نجح تُعد إعادة استخدام.
• يعني 503 {"error": "temporarily_unavailable"} أن التحديث لم يحدث، وأن رمز التحديث ما زال يعمل. أعد المحاولة مع التراجع التدريجي.
• ترد Didit بـ 429 قبل تشغيل التحديث، لذا أعد المحاولة بعد Retry-After. تسمح endpoint الرموز بـ 30 طلبًا في الدقيقة و300 طلب في الساعة لكل عنوان IP. وإضافةً إلى ذلك، تتشارك كل طلبات POST وDELETE في تطبيقك حصص حماية من البوتات: 60 طلبًا في الدقيقة لكل عنوان IP عبر تلك الـendpoints، و30 طلبًا في الدقيقة لكل جهاز. وعلى مستوى التطبيق كله، للتحديثات حصة قدرها 6,000 في الدقيقة، ولطلبات POST وDELETE الأخرى (بما في ذلك المتصفحات وخطوات تسجيل الدخول) حصة واحدة قدرها 3,000 في الدقيقة، بحيث لا تستنفد التحديثات عمليات تسجيل الدخول أبدًا.
• مع رموز وصول مدتها 5 دقائق، تكفي 300 عملية تحديث في الساعة تقريبًا لـ25 شخصًا يبقون نشطين. وإذا كان خادمك يجري التحديث لأشخاص كثيرين من عنوان واحد، فحدّث فقط عندما يحتاج طلب إلى رمز جديد، وحدّث في المتصفح أو التطبيق حيثما أمكن.

​

تسجيل الخروج

• عند تجاوز session_lifetime (الافتراضي 30 يوماً) أو idle_timeout (الافتراضي يوم واحد)،
• إذا سجّل الشخص الدخول مرة أخرى وكانت الجلسات المتعددة معطلة،
• إذا أعاد الشخص تعيين كلمة المرور وكان revoke_on_password_change مفعّلاً،
• إذا ألغى فريقك الجلسة أو حظر الشخص من وحدة التحكم،
• إذا أُرسل refresh token سبق استخدامه مرة أخرى.

​

مدد الصلاحية

​

تخزين بيانات الاعتماد حسب الغرض

• احتفظ بمفاتيح API الخاصة بالتحقق ورموز وحدة التحكم على خادمك.
• احتفظ بـ access tokens الخاصة بالمتصفح في الذاكرة كلما أمكن ذلك. بالنسبة للتطبيقات التي تُعرض من جهة الخادم، استخدم ملفات تعريف الارتباط الآمنة HttpOnly، واحمِ الطلبات المصادَق عليها بملفات تعريف الارتباط من هجمات CSRF.
• خزّن refresh tokens الخاصة بالتطبيقات المحمولة في وحدة التخزين المحمية من قِبل النظام. امسح الحالة المحلية بعد تسجيل الخروج.
• لا تضع الرموز أبداً في عناوين URL أو في السجلات.