JWT सत्यापन और JWKS: Didit प्रमाणीकरण टोकन

• लाइव एप्लिकेशन के लिए https://<name>.auth.didit.me,
• सैंडबॉक्स एप्लिकेशन के लिए https://<name>.sandbox.auth.didit.me,
• या आपका अपना कस्टम डोमेन, जब वह सक्रिय हो जाए।

​

Discovery और कुंजियाँ

• रिस्पॉन्स टाइप code और रिस्पॉन्स मोड query।
• Grant types authorization_code और refresh_token।
• केवल PKCE method S256। क्लाइंट सार्वजनिक हैं: कोई client secret नहीं है, और client_id आपकी एप्लिकेशन ID है।
• साइनिंग एल्गोरिदम ES256 (P-256 कुंजियाँ)।
• Scopes openid, email, phone, profile और offline_access।

​

कैशिंग और रोटेशन

• हर कुंजी का एक kid होता है; नई key IDs k_ से शुरू होते हैं। हर टोकन अपनी कुंजी को kid हेडर में बताता है।
• कुंजियाँ हर 30 दिन में रोटेट होती हैं। Didit अगली कुंजी उसके साइनिंग शुरू करने से एक दिन पहले प्रकाशित करता है, और पिछली कुंजी को साइनिंग बंद करने के बाद एक दिन तक प्रकाशित रखता है। 5 मिनट के लिए कैश किया गया JWKS इसलिए रोटेशन के दौरान भी सत्यापन जारी रखता है।
• कुंजियों को kid से कैश करें। जब कोई टोकन ऐसा kid बताए जो आपके पास नहीं है, तो JWKS को फिर से लाएँ, लेकिन अधिकतम एक बार प्रति मिनट, और यदि कुंजी अब भी न मिले तो टोकन अस्वीकार करें।
• जब Didit किसी समझौता की गई कुंजी को रद्द करता है, तो वह उसे तुरंत JWKS से हटा देता है, और GET /session/ उस कुंजी द्वारा साइन किए गए हर टोकन को अस्वीकार करता है। नई कुंजी तुरंत साइनिंग शुरू करती है, बिना एक दिन की पूर्व-प्रकाशन अवधि के। 5 मिनट तक पुराना कैश किया गया JWKS अब भी रद्द की गई कुंजी को स्वीकार करता है और नई कुंजी को नहीं जानता, इसलिए कैश ताज़ा होने तक नए टोकन ऑफ़लाइन सत्यापन में विफल हो सकते हैं।

​

साइन-इन शुरू करें

{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 आपकी एप्लिकेशन ID के बराबर हो।
4. exp और iat मान्य हों, जिसमें 60 सेकंड तक का क्लॉक अंतर स्वीकार्य है, और sub, sid और jti मौजूद हों।
5. act null हो। किसी AI एजेंट का एक्सेस टोकन उसी कुंजी से साइन होता है और वही 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 प्रति IP पता प्रति मिनट 30 और प्रति घंटे 300 अनुरोधों की अनुमति देता है। इसके अलावा, आपके एप्लिकेशन के हर POST और DELETE साझा बॉट सुरक्षा बकेट का उपयोग करते हैं: इन endpoints पर प्रति IP पता प्रति मिनट 60 अनुरोध, और प्रति डिवाइस प्रति मिनट 30। पूरे एप्लिकेशन के लिए, रिफ़्रेश का बकेट प्रति मिनट 6,000 का है, और बाकी हर POST और DELETE (ब्राउज़र और साइन-इन चरण सहित) का बकेट प्रति मिनट 3,000 का है, ताकि रिफ़्रेश आपके साइन-इन को कभी खत्म न करें।
• 5 मिनट के एक्सेस टोकन के साथ, प्रति घंटे 300 रिफ़्रेश लगभग 25 सक्रिय लोगों के लिए पर्याप्त हैं। यदि आपका सर्वर एक ही पते से कई लोगों के लिए रिफ़्रेश करता है, तो रिफ़्रेश केवल तभी करें जब किसी अनुरोध को नए टोकन की ज़रूरत हो, और जहाँ संभव हो वहाँ ब्राउज़र या ऐप में रिफ़्रेश करें।

​

साइन आउट

• जब वह session_lifetime (डिफ़ॉल्ट 30 दिन) या idle_timeout (डिफ़ॉल्ट 1 दिन) पार कर जाए,
• जब एकाधिक सत्रों की अनुमति न होने पर व्यक्ति फिर से साइन इन करे,
• जब revoke_on_password_change चालू होने पर व्यक्ति अपना पासवर्ड रीसेट करे,
• जब आपकी टीम कंसोल में सत्र रद्द करे या व्यक्ति को ब्लॉक करे,
• जब उपयोग किया जा चुका refresh token दोबारा भेजा जाए।

​

जीवनकाल

​

उद्देश्य के अनुसार क्रेडेंशियल संग्रहीत करें

• सत्यापन API कुंजियाँ और कंसोल टोकन अपने सर्वर पर रखें।
• ब्राउज़र के access token जहाँ संभव हो मेमोरी में रखें। सर्वर-रेंडर्ड ऐप्स के लिए सुरक्षित HttpOnly cookies का उपयोग करें, और cookie से प्रमाणित अनुरोधों को CSRF से बचाएँ।
• मोबाइल के refresh token प्लेटफ़ॉर्म-संरक्षित स्टोरेज में रखें। साइन आउट के बाद स्थानीय स्थिति साफ़ करें।
• टोकन कभी URL या लॉग में न डालें।