Software Engineer Encyclopedia
0%
Domain 05 · Security & Software Testing · Topic 5.2

JWT Authentication: فهم التوقيع والتحقق وRefresh Token Rotation

JWT Authentication — Deep Security Guide

شرح JWT وBearer authentication: structure/signature/claims، issuer/audience/expiry، access/refresh tokens، rotation/revocation، secure storage، OAuth/OIDC/PKCE، JWKS وBFF.

  • Intermediate
  • ~20 min read
  • 13 sections
  • 11 code examples
  • 1 diagrams
  • 5 questions
  • Priority L1 · Essential
  • ASP.NET Core 10 · OAuth 2.1 concepts · OpenID Connect

المتطلبات قبل ما تبدأ

Web API شغال بقاعدة بيانات (المجالات 03 و04).

مستوى التعمق المطلوب

DEEPمهم | Never treat a decoded JWT as trusted unless its signature and claims have been validated.

01

Authentication و Authorization و Bearer Tokens

What JWT is—and what it is not
Deep dive

Authentication تثبت هوية caller؛ Authorization تقرر هل الهوية دي مسموح لها تعمل action على resource معين. JWT format لتمثيل claims داخل token، وغالبًا API تستقبله كـ Bearer access token في Authorization: Bearer .... امتلاك token يعني إن حامله يستطيع استخدامه حتى انتهاء صلاحيته أو إبطاله؛ لذلك bearer token سر حساس.

JWT مش encryption افتراضيًا. الـ payload غالبًا Base64URL-encoded ومقروء لأي شخص يحصل على token. Signature تحمي integrity/authenticity، مش confidentiality. لا تضع password أو secrets أو بيانات شخصية غير لازمة داخل payload. و JWT لا يعني OAuth؛ OAuth/OIDC يحددان flows و roles، بينما JWT مجرد token format قد يستخدم داخلها.

02

JWT Structure: Header و Payload و Signature

Three segments and their meaning
Deep dive

JWT compact serialization غالبًا ثلاثة أجزاء مفصولة بنقطة: Header، Payload، Signature. Header يحدد token type والـ algorithm و key id مثل kid. Payload يحمل registered/public/private claims. Signature تنتج من signing input باستخدام key/algorithm. أي تعديل في header أو payload يغيّر signing input ويفشل التحقق.

TextJWT shape (illustrative only)
BASE64URL(header).BASE64URL(payload).BASE64URL(signature)

Header:  { "typ": "JWT", "alg": "RS256", "kid": "key-2026-02" }
Payload: { "iss": "https://identity.example", "aud": "orders-api",
           "sub": "user-123", "exp": 1794500000, "scope": "orders.read" }
Signature: cryptographic signature over encoded header + "." + encoded payload

لا تثق في claim لمجرد أنك فككت Base64 وشفتها. Decode ليس Validate. لازم signature validation بمفتاح موثوق، issuer/audience/time validation، algorithm restrictions، token type/context validation حسب النظام. لا تستخدم alg=none ولا تسمح للعميل يختار algorithm بحرية.

JWT Validation: التوقيع والـ Claims والـ Trust Boundary

Client Send access token Handler Validate signature API Check issuer + audience Refresh Rotate opaque secret
JWT validation and rotation

JWT عبارة عن format لنقل claims، وليس دليل ثقة بمجرد أن payload قابل للـ Base64URL decode. أي عميل يستطيع قراءة payload في signed JWT؛ التوقيع يثبت أن token لم يتغير وأنه صادر من جهة تملك المفتاح، بعد التحقق من issuer و audience والمدة والخوارزمية. لا تضع password أو secret أو بيانات شخصية غير لازمة داخل payload.

Validation يجب أن يحدد algorithms المسموحة من configuration موثوقة، لا أن يقبل algorithm يختاره token بحرية. تحقق من iss و aud و exp و nbf والتوقيع، مع clock skew محدود. تدوير signing keys يحتاج key identifier ودعم مفاتيح قديمة خلال فترة انتقالية.

C#Practical engineering example
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidIssuer = configuration["Jwt:Issuer"],
            ValidateAudience = true,
            ValidAudience = configuration["Jwt:Audience"],
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = signingKey,
            ValidateLifetime = true,
            ClockSkew = TimeSpan.FromSeconds(30)
        };
    });

حمّل signing key من secret manager أو certificate/key vault، لا من source control. لو تستخدم OpenID Connect provider، فضّل metadata/JWKS الرسمية ودعم key rotation بدل نسخ public key يدويًا إلى إعداد ثابت. اختبر رفض token بتوقيع خاطئ، issuer مختلف، audience مختلف، expired، و not-yet-valid.

03

Claims: iss و aud و sub و exp و iat و jti

Token semantics and trust boundaries
Deep dive
  • iss: الجهة التي أصدرت token؛ لازم تطابق trusted issuer.
  • aud: resource/API المقصودة؛ API ترفض token الموجهة لخدمة أخرى.
  • sub: subject identity، غالبًا user/client identifier وفق issuer contract.
  • exp: وقت انتهاء الصلاحية.
  • nbf: قبل هذا الوقت token غير صالحة.
  • iat: وقت الإصدار.
  • jti: معرف token، يمكن استخدامه في revocation/audit.

Claims names والـ semantics لازم تكون متفقًا عليها بين issuer و API. لا تخلط user id مع client id؛ user-delegated token و application token لهما معنى مختلف. لا تعتمد على claim مثل role=Admin إلا لو issuer موثوق والـ claim contract واضح وتم التحقق من token كاملًا.

04

Signing Algorithms و Key Management

Symmetric versus asymmetric signatures
Deep dive

في symmetric signing مثل HMAC، نفس secret يستخدم للتوقيع والتحقق؛ كل API تملك secret قادرة نظريًا على إصدار tokens أيضًا. في asymmetric signing مثل RSA/ECDSA، issuer يحتفظ private key، و APIs تتحقق باستخدام public key. ده يقلل انتشار قدرة إصدار tokens ويكون مناسبًا للأنظمة متعددة APIs.

استخدم standards و identity provider موثوقًا في production بدل بناء token issuer يدويًا. لو عندك signing keys، خزّنها في Key Vault/HSM/secret manager، حدّد access policies، خطط rotation، وراقب key usage. لا تضع secret في appsettings.json أو Git أو container image.

JWKS endpoint ينشر public signing keys مع key IDs؛ API تستخدم metadata/JWKS لتحديد المفتاح المناسب والتحقق من signature. عند rotation، issuer قد ينشر key جديدًا قبل استخدامه، ويبقي القديم مدة تكفي للتحقق من tokens الصادرة به. تعامل مع unknown kid وإعادة جلب metadata وفق library behavior، ولا تقبل key من URL يحدده token نفسه.

Signing Keys: Rotation و Compromise Response

حدد algorithm ثابتًا ومسموحًا (مثل asymmetric signing عندما عدة APIs تحتاج verify دون امتلاك private signing key). خزّن private key في Key Vault/KMS أو secret store مناسب، وامنح issuer فقط صلاحية signing بينما APIs تملك public keys للتحقق. استخدم key IDs لتحديد key من trusted JWKS/configuration، ولا تسمح بـ jku أو x5u غير موثوق يحدد remote key URL.

عند rotation طبيعي: انشر public key الجديد أولًا، ابدأ توقيع tokens به، احتفظ بالقديم للتحقق حتى انتهاء كل tokens القديمة مع clock skew، ثم احذفه. عند compromise: revoke key فورًا، أوقف قبول tokens الموقعة به، أعد إصدار credentials/session، وراجع logs. هذا قد يقطع sessions؛ وثّق emergency procedure قبل وقوعه.

05

التحقق في ASP.NET Core JwtBearer

Validate before trusting claims
Deep dive

API resource يجب أن تتحقق من signature و issuer و audience و expiration. استخدم authority/metadata provider عندما يكون عندك identity provider متوافق، أو TokenValidationParameters مضبوطة وفق issuer contract. لا تعطّل ValidateIssuerSigningKey أو ValidateIssuer/Audience لتجاوز error في development ثم تنسى إعادتها.

C#JwtBearer with trusted authority and audience
using Microsoft.AspNetCore.Authentication.JwtBearer;

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = builder.Configuration["Authentication:Authority"];
        options.Audience = builder.Configuration["Authentication:Audience"];
        options.RequireHttpsMetadata = true;
        options.MapInboundClaims = false;
    });

builder.Services.AddAuthorization();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();

الـ middleware ordering مهم: Authentication يكوّن HttpContext.User، ثم Authorization يطبق policy. استخدم HTTPS في metadata/token acquisition. راجع claim mapping لأن بعض handlers قد تحول claim names إلى URI-style names؛ MapInboundClaims=false يخلي التعامل أقرب للأسماء الأصلية إذا ده مناسب للـ issuer contract.

401 عادة تعني credential مفقودة أو invalid؛ 403 تعني authentication نجح لكن access غير مسموح. لا ترجع تفاصيل cryptographic failure للعميل، لكن سجل reason آمن داخليًا. واختبر expired token و wrong issuer/audience و bad signature و wrong token type.

Validation Failure Matrix

Failureالسبب المحتملما تراجعه
Invalid signatureKey mismatch أو tampering أو algorithm mismatchissuer metadata، kid، key rotation، signing algorithm
Invalid issuertoken من authority غير موثوقةAuthority/iss exact match
Invalid audiencetoken موجهة إلى API/client آخرaudience/resource identifier
Expired / not yet validexp/nbf خارج الوقتclock sync، lifetime، clock skew
Missing scope/claimtoken valid لكن contract ناقص أو permission غير ممنوحةissuer scopes، claim mapping، authorization policy
Unknown kidkey rotated أو metadata stale أو token forgedJWKS refresh behavior، trusted metadata endpoint

لا تحاول إصلاح كل validation failure بتعطيل validation flags. ابدأ بالـ exact token issuer metadata و API audience. في production لا تسجل raw token؛ سجل scheme، issuer identifier sanitized، failure category و correlation ID.

TokenValidationParameters: ماذا تعني كل Flag؟

في بعض الأنظمة الداخلية لا يوجد Authority metadata endpoint، وتحتاج ضبط validation صراحة. لا تستخدم هذا إلا عندما تملك trusted issuer/key contract واضحًا. ValidateIssuerSigningKey يتحقق من signature key، ValidateIssuer يقارن iss، ValidateAudience يقارن aud، و ValidateLifetime يتحقق من exp/nbf. لا تضع كل flags false لتجاوز مشكلة configuration.

C#Explicit validation — only with a trusted configured key
var signingKey = new X509SecurityKey(
    new X509Certificate2(builder.Configuration["Jwt:PublicCertificatePath"]!));

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = signingKey,
            ValidateIssuer = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidateAudience = true,
            ValidAudience = builder.Configuration["Jwt:Audience"],
            ValidateLifetime = true,
            RequireExpirationTime = true,
            ClockSkew = TimeSpan.FromSeconds(60)
        };
    });

في production، public key/certificate يجب أن تأتي من trusted deployment configuration أو metadata/JWKS، وليس من request. لا تستخدم private signing certificate في API validator إذا API تحتاج التحقق فقط. راجع certificate rotation/expiry و key id mapping. ClockSkew يجب أن يكون صغيرًا ومبررًا، ومزامنة الوقت على servers أفضل من توسيع السماح.

ClaimsPrincipal و Claim Mapping داخل API

بعد نجاح validation، handler ينشئ ClaimsPrincipal يحتوي identities/claims. HttpContext.User هو principal للطلب. claim type mapping قد يغير أسماء بعض claims حسب handler settings. اتفق على claim contract مع issuer: subject identifier، tenant، scope/roles، client identity. لا تعتمد على claim type غير موثق مثل name كـ stable user ID.

C#Read a stable subject and scope claims
app.MapGet("/me", (ClaimsPrincipal user) =>
{
    var subject = user.FindFirst("sub")?.Value;
    var scopes = user.FindAll("scope").Select(x => x.Value).ToArray();
    if (subject is null) return Results.Unauthorized();
    return Results.Ok(new { subject, scopes });
}).RequireAuthorization();

الكود لا يقرر permissions من مجرد وجود scope؛ يجب تحويل claims إلى authorization requirements/permissions واضحة. لا تقبل tenant id من route وتستبدل به claim موثوقة من غير membership check.

JWT Validation: Signature و Issuer و Audience و Clock Skew

JWT validation يجب تتحقق من signature باستخدام trusted key، algorithm allow-list، issuer، audience، expiration/not-before، و token type حسب النظام. لا تقبل algorithm من token header بلا policy. لا تستخدم decode كأنه validation؛ Base64 decoding لا يثبت authenticity. aud يمنع token موجهًا إلى API من أن يُقبل في API أخرى بلا قصد.

Clock skew يسمح بهامش زمني محدود لتفاوت clocks؛ قيمة كبيرة توسع صلاحية token فعليًا. راقب key rotation: أصدر tokens بمفتاح جديد، واحتفظ بالمفتاح القديم للتحقق حتى تنتهي tokens القديمة، ثم أزله. لا تضع signing key في source control أو appsettings committed. استخدم secret/key vault و rotation procedure.

06

Access Tokens و Refresh Tokens

Short-lived access, controlled renewal
Deep dive

Access token قصيرة العمر تُرسل إلى API لحمل authorization context. Refresh token أطول عمرًا وتستخدم فقط مع authorization server للحصول على access token جديدة؛ لا ترسلها إلى resource API. قلل access-token lifetime حسب UX/risk. Refresh token ليست مجرد JWT ثانية؛ غالبًا opaque random secret مخزّن hash في server-side store مع metadata.

Refresh rotation: عند استخدام refresh token، يصدر server access token جديدة و refresh token جديدة، ويبطل القديمة. لو ظهرت القديمة مرة أخرى، قد يشير ذلك إلى token theft/replay؛ يمكن revoke token family/session. لازم rotation تكون atomic لتجنب race condition بين جهازين أو requests متزامنة.

TextRefresh token family state
SessionId: 8f...
Token A: hash(A), active -> consumed at T1
Token B: hash(B), active -> issued at T1, replaces A
Token C: hash(C), active -> issued at T2, replaces B

If consumed token A is replayed after rotation:
- detect reuse
- revoke the related token family/session according to policy
- require re-authentication

لا تخزن raw refresh token في DB؛ خزن hash قوي/one-way representation، و metadata: user/client/session، issued/expiry/revoked/replaced time، device info عند الحاجة. لا تعتمد على IP/device fingerprint كدليل هوية وحيد. راجع logout/password change/account disable flows لإبطال refresh sessions.

إصدار JWT: لماذا لا تبنِ Identity Provider بنفسك؟

إصدار access token في production مسؤولية security-sensitive: key custody، algorithm selection، issuer/audience contract، claims mapping، lifetime، metadata/JWKS، rotation، revocation، client registration، consent/scopes، audit و incident response. كتابة new JwtSecurityToken(...) لا تعني أنك بنيت authorization server آمنًا.

الأفضل غالبًا استخدام Identity Provider يدعم OAuth/OIDC، وتدع API تعمل validation فقط. لو عندك سبب قوي لبناء issuer داخلي، لازم security review متخصص، threat model، key management خارج app، standards conformance tests، rotation plan و operational runbooks. لا تخترع protocol خاصًا.

Asymmetric signing يحد من انتشار private signing key: issuer فقط يوقع، APIs تملك public keys للتحقق. في symmetric signing، كل API معها secret تقدر تصدر tokens، ما يوسع blast radius. algorithm/key type يجب أن يأتي من trusted configuration/metadata وليس من اختيار client.

Refresh Token Rotation: تصميم Server-Side Store

Refresh token عادة random high-entropy opaque value. خزن hash token، user/client/session identifiers، issued/expiry/revoked/replaced timestamps، family id، ومعلومات device آمنة حسب policy. عند refresh، نفذ عملية ذرية: تحقق token active وغير منتهية، علّمها consumed، أنشئ successor، واربط successor بنفس family. لو token مستهلكة ظهرت مرة أخرى، اعتبرها replay signal وطبّق revoke family/re-authentication وفق policy.

C#Refresh rotation — transactional pseudocode
public async Task<TokenPair> RotateAsync(string rawToken, CancellationToken ct)
{
    var tokenHash = HashRefreshToken(rawToken);
    await using var tx = await db.Database.BeginTransactionAsync(ct);

    var current = await db.RefreshTokens
        .SingleOrDefaultAsync(x => x.TokenHash == tokenHash, ct);

    if (current is null || current.RevokedAt is not null ||
        current.ExpiresAt <= clock.UtcNow)
        throw new InvalidRefreshTokenException();

    if (current.ConsumedAt is not null)
    {
        await RevokeFamilyAsync(current.FamilyId, ct);
        await db.SaveChangesAsync(ct);
        await tx.CommitAsync(ct);
        throw new RefreshTokenReplayException();
    }

    current.ConsumedAt = clock.UtcNow;
    var newRawRefreshToken = CreateRandomSecret();
    var replacement = RefreshToken.Create(current.UserId, current.FamilyId,
        HashRefreshToken(newRawRefreshToken), clock.UtcNow.AddDays(14));
    db.RefreshTokens.Add(replacement);
    await db.SaveChangesAsync(ct);
    await tx.CommitAsync(ct);
    return IssueTokenPair(current.UserId, replacement, newRawRefreshToken);
}

ده pseudocode يحتاج تعديل ordering في حالة replay: لا ترمي exception قبل commit إذا تريد حفظ family revocation؛ transaction commit أولًا ثم ارجع error. كما يجب أن تمنع race بين refresh requests عبر concurrency token/conditional update/unique constraints. لا تستخدم raw refresh token في database أو logs، ولا تسمح token family تنمو بلا retention cleanup.

Refresh Token Rotation و Reuse Detection

Refresh token طويل العمر نسبيًا ويستخدم لإصدار access token جديد؛ لذلك يجب أن يكون random opaque secret عالي entropy، ويخزن server-side hash له، مع user/session/family/device metadata و expiry و revocation. عند refresh، transaction واحدة تستهلك token الحالي وتصدر replacement. لو ظهر token مستهلك مرة أخرى، قد يكون replay؛ ألغِ family أو session وفق threat policy وسجل security event.

لا تخزن raw refresh token في database. لا تسمح بتحديث token بلا atomic compare-and-swap/transaction؛ طلبان متزامنان قد يحاولان تدوير نفس token. حدد client behavior عند refresh race، وامنع infinite retry. Access token قصير العمر، refresh token له idle/absolute expiry، و logout/revocation يجب أن يصل إلى server-side state.

Refresh Token Rotation و Replay Detection

Access token قصير العمر يرسل مع كل API request، أما refresh token فيستخدم للحصول على access token جديد. غالبًا الأفضل أن يكون refresh token opaque random secret عالي entropy، وتخزن hash له في database مع user/session/device, expiry, revokedAt, replacedBy, token family. عند refresh ناجح، ألغِ القديم واصدر واحدًا جديدًا داخل transaction.

لو استُخدم refresh token قديم مرة ثانية بعد rotation، فهذا مؤشر replay أو سرقة. ألغِ token family أو session وفق سياسة واضحة، وسجل security event دون تسجيل raw token. لا تخزن refresh token plaintext، ولا تضعه في localStorage إذا كان threat model يتطلب حمايته من XSS.

C#Practical engineering example
// Pseudocode for a rotation transaction:
await using var tx = await db.Database.BeginTransactionAsync(ct);
var stored = await db.RefreshTokens
    .SingleOrDefaultAsync(x => x.TokenHash == tokenHash, ct);
if (stored is null || stored.RevokedAt != null || stored.ExpiresAt <= clock.UtcNow)
    return Unauthorized();

stored.RevokedAt = clock.UtcNow;
var replacement = CreateRandomRefreshToken(stored.UserId, stored.FamilyId);
stored.ReplacedByTokenId = replacement.Id;
db.RefreshTokens.Add(replacement);
await db.SaveChangesAsync(ct);
await tx.CommitAsync(ct);

التنفيذ production يحتاج concurrency protection لمنع طلبين متزامنين من تدوير نفس token؛ استخدم conditional update/rowversion أو unique constraints، وتأكد أن tokenHash lookup لا يسمح باستخدام token ملغي. إذا كان token ملغيًا قديمًا يُستخدم مجددًا، لا تعامله كـ login عادي؛ نفّذ replay response policy.

Refresh Token Database Model و Unique Constraints

خزن refresh token كـ hash مع metadata، وليس raw secret. اجعل token hash unique، واربط كل token بـ family/session و client. استخدم conditional update أو rowversion لمنع refresh race. إذا تم استهلاك token مرتين بسبب simultaneous requests، يجب أن يكون سلوكك واضحًا: قبول successor واحد فقط، ورفض/revoke عند replay.

SQLRefresh token table sketch
CREATE TABLE dbo.RefreshTokens
(
    Id uniqueidentifier NOT NULL PRIMARY KEY,
    UserId uniqueidentifier NOT NULL,
    ClientId nvarchar(100) NOT NULL,
    FamilyId uniqueidentifier NOT NULL,
    TokenHash varbinary(32) NOT NULL,
    IssuedAt datetime2 NOT NULL,
    ExpiresAt datetime2 NOT NULL,
    ConsumedAt datetime2 NULL,
    RevokedAt datetime2 NULL,
    ReplacedById uniqueidentifier NULL,
    CONSTRAINT UQ_RefreshTokens_TokenHash UNIQUE(TokenHash)
);
CREATE INDEX IX_RefreshTokens_FamilyId ON dbo.RefreshTokens(FamilyId);

حدد retention cleanup للـ expired/revoked rows، لكن احتفظ بمعلومات كافية لاكتشاف replay خلال window المطلوبة. لو تخزن client/device metadata، قللها واحمها. لا تجعل refresh endpoint يسمح بتغيير user/client identity من body.

07

Revocation و Logout و Clock Skew

What happens before exp?
Deep dive

JWT access token الموقعة self-contained، لذلك API تستطيع التحقق منها دون database lookup. لكن ده يجعل immediate revocation أصعب. الخيارات: short access-token lifetime، denylist لـ jti حتى expiry، token version/user security stamp lookup، introspection مع opaque tokens، أو gateway/session strategy. كل خيار trade-off بين latency و central state و revocation speed.

Clock skew يسمح بهامش صغير بين ساعات servers عند مقارنة exp/nbf. لا ترفع الهامش كثيرًا؛ ده يطيل صلاحية token فعليًا. مزامنة clocks عبر NTP أفضل من إخفاء مشاكل الوقت. اختبر اختلاف الساعة وانتهاء token عند الحدود.

08

Secure Token Storage: Cookie ولا Browser Storage؟

Reduce token theft and CSRF risk
Deep dive

Browser localStorage/sessionStorage accessible to JavaScript؛ XSS قد يسرق access/refresh tokens. HttpOnly cookie لا تستطيع JavaScript قراءتها، لكنها تُرسل تلقائيًا مع requests المطابقة، لذلك CSRF لازم يدخل في threat model. استخدم Secure و HttpOnly و SameSite مناسبًا، و anti-forgery/origin defenses حسب architecture.

في server-rendered web app، cookie authentication غالبًا أبسط وأأمن من تخزين JWT في browser. في SPA مع separate API، لا تعتبر localStorage الاختيار الافتراضي. BFF pattern يخلي browser يتعامل مع session cookie، والـ backend يحتفظ access tokens ويتصل بالـ APIs نيابة عن المستخدم، فيقلل token exposure في JavaScript.

C#Cookie security configuration (illustrative)
builder.Services.AddAuthentication("AppCookie")
    .AddCookie("AppCookie", options =>
    {
        options.Cookie.Name = "__Host-MyShop.Session";
        options.Cookie.HttpOnly = true;
        options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
        options.Cookie.SameSite = SameSiteMode.Lax;
        options.Cookie.Path = "/";
        options.SlidingExpiration = true;
    });

__Host- prefix له متطلبات خاصة: Secure، Path=/، وعدم Domain attribute. اختر SameSite وفق cross-site login/callback needs؛ Strict قد يكسر بعض flows. Cookie auth تحتاج CSRF defenses عند state-changing requests، ولا تعتمد على CORS كبديل عن CSRF protection.

Browser Storage: LocalStorage vs HttpOnly Cookie vs BFF

LocalStorage سهل الوصول من JavaScript، لذلك XSS يستطيع قراءة bearer token. SessionStorage له نفس المشكلة داخل tab lifetime. HttpOnly cookie تمنع JavaScript من قراءة cookie، لكنها تُرسل تلقائيًا وتحتاج CSRF protection. BFF يحتفظ access/refresh tokens server-side ويعطي browser session cookie؛ يقلل exposure لكنه يحتاج session store و CSRF/origin defenses و backend availability.

لا يوجد تخزين «آمن مطلقًا». قيّم هل client SPA/mobile/server-rendered، هل عندك cross-site API، ما نوع XSS/CSRF exposure، هل تستطيع server-side token storage، وكيف يتم logout/revocation. لا تضع refresh token في localStorage لمجرد سهولة implementation.

JWT مع Browser Cookies: Access و Refresh و CSRF

لو access/refresh tokens في cookies، استخدم HttpOnly و Secure و SameSite المناسب، وقلل Domain/Path. HttpOnly يمنع القراءة من JavaScript لكنه لا يمنع XSS من تنفيذ authenticated requests. بما أن browser يرسل cookie تلقائيًا، قيّم CSRF: anti-forgery token أو double-submit pattern/Origin validation وفق architecture، مع CORS allow-list دقيقة. لا تستخدم wildcard origin مع credentials.

Access cookie قصيرة العمر و refresh cookie أطول عمرًا، لكن يجب أن يكون لكل منهما purpose واضح. لا تضع refresh token في response body ثم تخزنه localStorage إذا اخترت cookie architecture. Logout يجب يمسح cookie بنفس Path/Domain/SameSite attributes ويلغي server-side refresh session؛ مسح cookie وحده لا يبطل token مسروقًا.

09

OAuth 2.0 و OpenID Connect و PKCE

Token acquisition protocols
Deep dive

OAuth 2.0 authorization framework لتفويض الوصول إلى resource، وليس بروتوكول authentication بحد ذاته. OpenID Connect layer فوق OAuth تضيف authentication و ID Token. Access token موجهة إلى API؛ ID token موجهة إلى client لتأكيد authentication، ولا تستخدم ID token بدل access token للوصول إلى API.

Authorization Code Flow مع PKCE مناسب لتطبيقات user-facing؛ PKCE تربط code exchange بـ verifier/challenge وتقلل authorization-code interception. Confidential web apps تحتفظ client secret بأمان على server، و public clients مثل mobile/SPA لا تستطيع حماية secret ثابت. تجنب Resource Owner Password Credentials flow؛ استخدم standards-based flows و identity provider موثوق.

OAuth scopes تحدد delegated permissions على resource، و OIDC scopes مثل openid/profile/email تطلب identity claims. لا تخلط scope مع application role أو database permission؛ API policy هي التي تقرر ما يسمح به token على resource.

PKCE خطوة بخطوة و Client Types

Authorization Code + PKCE flow: client ينشئ random code_verifier، يحسب code_challenge (عادة S256)، يرسل user إلى authorization endpoint مع challenge/state/nonce، المستخدم يصادق ويوافق، authorization server يرجع short-lived code إلى redirect URI، client يبادل code + verifier على token endpoint. server يتحقق أن verifier يطابق challenge. state يربط response بالطلب ويقاوم CSRF في authorization flow؛ nonce يستخدم في OIDC لربط ID token بالـ authentication request.

Public client (SPA/mobile) لا يستطيع حماية client secret ثابت داخل app package؛ PKCE ضرورية. Confidential client (server-side web app) يستطيع حفظ secret/certificate في server-side secure storage، ومع ذلك يستخدم Authorization Code + PKCE وفق modern guidance. Client Credentials مخصص machine-to-machine بلا user context؛ لا تستخدمه لتقمص user.

Redirect URI لازم exact allow-list؛ wildcard واسع أو open redirect قد يسمح code/token leakage. لا تمرر access token في query string. استخدم system browser على mobile بدل embedded webview في كثير من flows حتى يستفيد المستخدم من SSO/security controls.

Multiple APIs و Delegated Tokens

لو API A تنادي API B نيابة عن user، لا تمرر token موجهة لـ API A إلى API B إلا لو audience/scopes تسمح بذلك. استخدم on-behalf-of/delegated token flow وفق identity provider. لو service تنادي service بلا user، استخدم client credentials بهوية service وصلاحيات أقل ما يمكن.

لا تخلط user identity مع service identity: audit يجب يوضح actor الأصلي وال service التي نفذت call. token application-wide قد تمنح service صلاحيات عامة، بينما delegated token تحمل user context. اختَر حسب business requirement وليس سهولة implementation.

10

Identity Providers و BFF

Delegate issuance and protect browser sessions
Practical

Identity provider مثل Microsoft Entra ID أو Keycloak أو Auth0 يدير user authentication و token issuance و metadata/JWKS. API تثق في issuer محدد وتتحقق من audience/claims. لا تضع كل APIs على issuer/audience واحد بلا حاجة؛ افصل resource audiences لتقليل token substitution.

BFF (Backend for Frontend) نمط يضع server-side component بين browser و APIs. Browser يحمل session cookie فقط؛ BFF يحتفظ access/refresh tokens في server-side storage أو protected session، ويتصل بالـ APIs. ده يقلل token exposure للـ JS لكنه يزيد backend hop ويتطلب CSRF/session security وتوسيع capacity.

11

Common JWT Vulnerabilities

Threats and defensive checks
Deep dive
  • Accepting token without signature validation أو قبول alg=none.
  • عدم التحقق من issuer/audience/expiry.
  • قبول ID token في مكان access token أو قبول token موجهة لخدمة أخرى.
  • تخزين access/refresh token في localStorage مع XSS exposure.
  • Long-lived access token بلا revocation strategy.
  • Hard-coded signing secret أو key rotation غير موجود.
  • ضعف refresh rotation أو عدم اكتشاف replay.
  • الاعتماد على claims قديمة لصلاحيات تتغير بسرعة.
  • تسجيل bearer token في logs/APM.
  • استخدام JWT كبديل عن authorization checks على resource ownership.

Security review اسأل: مين issuer؟ مين audience؟ أي key؟ أي algorithm؟ token type إيه؟ lifetime قد إيه؟ أين تخزن؟ كيف revoke؟ كيف rotate؟ هل permissions snapshot مقبولة؟ كيف تتعامل مع clock skew؟ هل API ترفض malformed/oversized tokens؟

12

اختبار JWT Flow

Positive and negative security tests
Practical

اختبر happy path و negative paths: token valid، expired، signature tampered، issuer wrong، audience wrong، missing required claim، nbf future، unknown kid، key rotation، refresh replay، revoked session، logout، password reset، و token من client آخر. اختبر clock skew والـ multiple issuers لو النظام يدعمهم.

لا تكتفِ باختبار decode. اختبر endpoint فعليًا مع authentication handler؛ استخدم test signing keys و test issuer أو test server. في integration tests، تأكد أن 401 و403 مميزان وأن endpoint لا ينفذ side effect قبل authorization.

اختبارات Security للـ JWT على مستوى API

اكتب tests تبني tokens مختلفة عمدًا: signature valid/invalid، issuer wrong، audience wrong، exp past، nbf future، missing subject، scope absent، unknown key id، token من test issuer آخر، ID token بدل access token. تأكد أن API ترفض قبل تنفيذ endpoint side effects. اختبر key rotation بحيث token قديمة تظل مقبولة فقط خلال overlap policy.

C#Integration test: wrong audience is rejected
[Fact]
public async Task Token_for_another_api_is_rejected()
{
    var token = TestTokens.Create(
        issuer: "https://issuer.test",
        audience: "billing-api",
        subject: "user-17");
    using var client = factory.CreateClient();
    client.DefaultRequestHeaders.Authorization =
        new AuthenticationHeaderValue("Bearer", token);

    var response = await client.GetAsync("/orders");
    Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);
    Assert.Equal(0, await testDatabase.CountOrderReadsAsync());
}

Test token issuer يجب أن يستخدم مفاتيح test فقط. لا تضع production private key في tests أو CI. اختبر كذلك oversized/malformed tokens و multiple authentication schemes إن كانت مدعومة.

13

اختبر فهمك

Knowledge check
Practical
هل JWT payload مشفرة؟
غالبًا لا؛ Base64URL encoding فقط. لا تضع secrets أو بيانات حساسة فيها.
ما الفرق بين ID Token و Access Token؟
ID Token تؤكد authentication للـ client في OIDC؛ Access Token موجهة إلى resource API. لا تستخدم ID token للوصول إلى API.
لماذا نتحقق من audience؟
لمنع استخدام token موجهة إلى API أخرى على هذا الـ resource server.
لماذا refresh token rotation مهمة؟
تحد من replay وتسمح باكتشاف استخدام refresh token قديمة بعد استبدالها، مع إمكانية revoke session family.
هل logout يمحو JWT من server؟
لا؛ client قد يتوقف عن إرسالها، لكن token الموقعة تظل صالحة حتى expiry ما لم توجد revocation/version check.
↗

المراجع والقراءة الإضافية

References & further reading

الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)

خريطة التغطية: 21 عنصر من الـ Roadmap ومكان شرحه في الدرس
RoadmapAuthentication vs Authorization§01
RoadmapJWT Structure: Header, Payload, and Signature§02
RoadmapClaims§02
RoadmapSigning Algorithms§04
RoadmapIssuer and Audience Validation§03
RoadmapToken Expiration§03
RoadmapAccess Tokens§04
RoadmapRefresh Tokens§04
RoadmapRefresh Token Rotation§04
RoadmapToken Revocation§04
RoadmapSecure Token Storage§04
RoadmapKey Management§04
RoadmapClock Skew§03
RoadmapCommon Vulnerabilities§04
RoadmapJWT vs Cookies§04
RoadmapOAuth 2.0 Concepts§04
RoadmapOpenID Connect Concepts§04
SuggestedOAuth 2.1 and PKCE§04
SuggestedJWKS and signing-key rotation§04
SuggestedIdentity providers: Entra ID, Keycloak, Auth0 (awareness)§04
SuggestedBackend-for-Frontend (BFF) pattern§04

خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.

محتويات الدرس