OAuth 2.0

Authorization Framework & Grant Types

OAuth 2.0 هو إطار عمل تفويض يمنح التطبيقات إمكانية الوصول المحدود إلى حسابات المستخدمين على خدمات HTTP — دون مشاركة كلمات المرور.

جدول المحتويات

نظرة عامة

OAuth 2.0 (RFC 6749) يتيح لتطبيق "العميل" (client application) الحصول على وصول محدود إلى "مورد محمي" (protected resource) على behalf of المالك (user) — بدون أن يعرف كلمة مروره.

⚠️ ملاحظة: OAuth 2.0 وحده لا يوفر هوية مستخدم. إذا كنت تحتاج هوية مستخدم (user authentication)، استخدم OpenID Connect الذي يبني على OAuth 2.0.

الأدوار الأربعة

Resource Owner (مالك المورد)

الشخص أو entity يمنح الوصول — عادة المستخدم. يمكنه تفويض أو سحب الوصول.

Client (العميل)

التطبيق الذي يريد الوصول إلى المورد. يجب تسجيله مسبقاً لدى Authorization Server.

Authorization Server (خادم التفويض)

ميثاق يعمل كـ Authorization Server. يصدر access tokens بعد موافقة المستخدم.

Resource Server (خادم الموارد)

الخدمة التي تحمي الموارد — تتحقق من access token قبل السماح بالوصول.

أنواع Grant

1. Authorization Code Grant

الأكثر أماناً وتوافقاً — مناسب لجميع أنواع العملاء. يمرر التفويض عبر redirect.

# Step 1: Authorization Request
GET /authorize
  ?response_type=code
  &client_id=my-client
  &redirect_uri=https://client.com/callback
  &scope=read write
  &state=xyz
# Step 2: Token Request
POST /token
grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://client.com/callback
&client_id=my-client
&client_secret=CLIENT_SECRET

2. Client Credentials Grant

للآلات (M2M) — عندما لا يكون هناك مستخدم بشري. العميل يطلب token باسمه الخاص.

POST /token
grant_type=client_credentials
&client_id=my-service
&client_secret=CLIENT_SECRET
&scope=read
# Response
{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 300
}

3. Device Code Grant

للأجهزة المحدودة (Smart TVs, CLI tools). الجهاز يعرض رمزاً المستخدم يزوره في متصفح آخر.

# Device requests code
POST /token
grant_type=urn:ietf:params:oauth:grant-type:device_code
&client_id=MY_DEVICE
&device_code=VmCcJ1yIXxu0qM3Z...

4. Refresh Token Grant

لتجديد access token منتهي الصلاحية بدون إعادة المستخدم.

POST /token
grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=my-client
&client_secret=CLIENT_SECRET

أنواع العملاء

النوعالوصفأمثلة
Confidentialعميل قادر على حفظ secret — يعمل على خادم آمنBackend APIs, Node.js servers
Publicعميل لا يستطيع حفظ secret — يعتمد على PKCESPA, Mobile apps, Desktop apps

Client Authentication Methods

# 1. client_secret_basic (HTTP Basic Auth header)
Authorization: Basic base64(client_id:client_secret)

# 2. client_secret_post (in request body)
POST /token
client_id=my-app
client_secret=MY_SECRET
grant_type=client_credentials

# 3. private_key_jwt (JWT assertion — recommended for modern apps)
POST /token
grant_type=client_credentials
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbG...(signed JWT)

PKCE — Proof Key for Code Exchange

PKCE (RFC 7636) يحمي من intercept attacks على Authorization Code flow — يصبح إلزامياً لـ public clients.

1

إنشاء code_verifier

سلسلة عشوائية بطول 43-128 حرف (A-Z, a-z, 0-9, -, ., _, ~)

2

إنشاء code_challenge

BASE64URL(SHA256(code_verifier))

3

إرسال code_challenge مع Authorization Request

مرر code_challenge و code_challenge_method=S256

4

إرسال code_verifier مع Token Request

Authorization Server يتحقق من تطابق SHA256(code_verifier) مع code_challenge

Token Introspection

allows a resource server to query the authorization server to determine the active state of a token and get metadata about it.

POST /realms/{realm}/protocol/openid-connect/token/introspect
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/x-www-form-urlencoded

token=RECEIVED_ACCESS_TOKEN
token_type_hint=access_token
# Response (active token)
{
  "active": true,
  "scope": "read write",
  "client_id": "my-app",
  "username": "johndoe",
  "exp": 1713000000,
  "iat": 1712996400,
  "sub": "user-uuid",
  "iss": "https://your-methaq-server/realms/methaq"
}

# Response (inactive/expired token)
{ "active": false }