Social Login (OAuth 2.0)

Ithbat IAM يربط OAuth 2.0 Providers خارجيين بدليل المستخدمين لديك. المستخدم يمكنه تسجيل الدخول بحسابه الحالي على Google أو GitHub أو Microsoft أو Apple دون أن يحتاج كلمة مرور منفصلة.

الـ Providers المدعومين

Provider	المعرّف
Google	google
GitHub	github
Microsoft (Azure AD / Entra ID)	microsoft
Apple	apple

يمكنك إضافة OAuth 2.0 Providers مخصصين عبر Identity Provider (IdP) configuration API.

---

آلية العمل

Social Login يستخدم OAuth 2.0 Authorization Code flow. Ithbat IAM يعمل كـ OAuth client نيابة عنك.

1. تطبيقك يعمل Redirect للمستخدم على Ithbat IAM social login Endpoint.
2. Ithbat IAM يعمل Redirect للمستخدم على صفحة Authorization الخاصة بالـ Provider.
3. المستخدم يعمل مصادقة عند الـ Provider ويمنح consent.
4. الـ Provider يعمل Redirect على Callback URL في Ithbat IAM مع authorization code.
5. Ithbat IAM يستبدل الكود بـ Provider Tokens، يجلب بيانات المستخدم، وينشئ أو يربط الحساب.
6. Ithbat IAM يُعيد Ithbat Tokens (Access, Refresh, ID) إلى تطبيقك.

sequenceDiagram
    participant User
    participant App as Your App
    participant Ithbat as Ithbat IAM
    participant Provider as OAuth Provider (Google etc.)

    User->>App: Click "Sign in with Google"
    App->>Ithbat: GET /api/v1/auth/social/google/login?redirect_uri=...
    Ithbat->>Ithbat: Generate state parameter, build auth URL
    Ithbat-->>App: 302 Redirect to provider auth URL
    App-->>User: Browser follows redirect

    User->>Provider: Authenticate and grant consent
    Provider-->>Ithbat: 302 Redirect to /api/v1/auth/social/google/callback?code=...&state=...

    Ithbat->>Provider: Exchange code for access token
    Provider-->>Ithbat: Provider access token + user profile
    Ithbat->>Ithbat: Create or link user account
    Ithbat-->>App: 200 { accessToken, refreshToken, idToken, user }

---

إعداد الـ Providers في لوحة تحكم المسؤول

قبل استخدام Social Login، يجب إعداد بيانات اعتماد الـ Provider في لوحة تحكم المسؤول:

1. انتقل إلى الإعدادات ← Identity Providers في لوحة تحكم المسؤول.
2. اختر الـ Provider (مثلًا: Google).
3. أدخل بيانات OAuth application:
   • Client ID — من developer console الخاص بالـ Provider
   • Client Secret — من developer console الخاص بالـ Provider
4. حدد Scopes (القيم الافتراضية تتعبأ تلقائيًا لكل Provider).
5. انسخ Callback URL وسجّله في developer console الخاص بالـ Provider.
6. فعّل Enabled واحفظ.

عبر الـ API

POST /api/v1/tenant/idp-configs

Header مطلوب: Authorization: Bearer <adminToken>

{
  "provider": "google",
  "name": "Google",
  "clientId": "123456789-abc.apps.googleusercontent.com",
  "clientSecret": "GOCSPX-...",
  "scopes": ["openid", "email", "profile"],
  "enabled": true
}

الـ Response — 201 Created

{
  "id": "idp_01J8X...",
  "provider": "google",
  "name": "Google",
  "clientId": "123456789-abc.apps.googleusercontent.com",
  "scopes": ["openid", "email", "profile"],
  "enabled": true,
  "createdAt": "2026-02-24T10:00:00Z",
  "updatedAt": "2026-02-24T10:00:00Z"
}

---

بدء Social Login

عرض الـ Providers المفعّلين

GET /api/v1/auth/social/providers

Header مطلوب: X-Tenant-ID: <tenant-uuid>

الـ Response — 200 OK

[
  { "provider": "google", "name": "Google", "enabled": true },
  { "provider": "github", "name": "GitHub", "enabled": true }
]

بدء OAuth Flow

GET /api/v1/auth/social/{provider}/login

Header مطلوب: X-Tenant-ID: <tenant-uuid>

Query parameter: redirect_uri — الـ URL في تطبيقك الذي المستخدم يرجع عليه بعد المصادقة

GET /api/v1/auth/social/google/login?redirect_uri=https://app.example.com/auth/callback
X-Tenant-ID: ten_01J8X...

هذا الـ Endpoint يرجع 302 Found Redirect على صفحة Authorization عند الـ Provider. تطبيقك يجب يتبع الـ Redirect (أو يوجه browser المستخدم لهذا الـ URL).

الـ Provider بالنهاية يرجع Redirect على Callback URL في Ithbat IAM:

GET /api/v1/auth/social/{provider}/callback?code=...&state=...

Ithbat IAM يعالج الـ Callback ويرجع Token Response.

---

الـ Callback Response

إذا المصادقة نجحت، Callback Endpoint يرجع 200 OK مع Token Response القياسي:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "user": {
    "id": "usr_01J8X...",
    "tenantId": "ten_01J8X...",
    "email": "[email protected]",
    "firstName": "Sara",
    "familyName": "Al-Rashidi",
    "displayName": "Sara Al-Rashidi",
    "roles": ["member"],
    "permissions": ["profile:read"]
  }
}

---

ربط الحسابات

الربط التلقائي (مطابقة البريد الإلكتروني)

إذا مستخدم بنفس البريد الإلكتروني المُتحقق منه موجود بالفعل عند المستفيد، Ithbat IAM يربط الـ social identity تلقائيًا بالحساب الحالي بدلاً من أن ينشئ duplicate. المستخدم يسجل دخول لحسابه الحالي.

هذا السلوك يتطلب أن يُرجع الـ Provider بريدًا إلكترونيًا متحققًا منه.

الربط اليدوي (مستخدم مسجل دخول)

المستخدم المسجل دخوله يمكنه ربط Providers إضافيين بحسابه دون أن يمر بالـ OAuth flow الكامل من البداية.

الخطوة 1 — بدء الربط (نفس Social Login العادي، فقط يحدث والمستخدم مسجل دخول أصلاً)

POST /api/v1/users/me/identities/{provider}

Header مطلوب: Authorization: Bearer <accessToken>

{
  "code": "4/0AX4XfWh...",
  "redirectUrl": "https://app.example.com/settings/accounts"
}

الـ Response — 200 OK

{
  "message": "Identity linked successfully"
}

عرض الـ Identities المرتبطة

GET /api/v1/users/me/identities

Header مطلوب: Authorization: Bearer <accessToken>

الـ Response — 200 OK

[
  {
    "id": "fed_01J8X...",
    "provider": "google",
    "providerUserId": "1078239012...",
    "email": "[email protected]",
    "name": "Sara Al-Rashidi",
    "avatarUrl": "https://lh3.googleusercontent.com/...",
    "linkedAt": "2026-02-20T08:30:00Z"
  }
]

إلغاء ربط Identity

DELETE /api/v1/users/me/identities/{provider}

Header مطلوب: Authorization: Bearer <accessToken>

{
  "message": "Identity unlinked successfully"
}

تحذير

لا يمكن للمستخدم إلغاء ربط آخر Social Identity لديه إذا لم يكن لديه كلمة مرور. سيُقفل خارج الحساب. Ithbat IAM يمنع هذا تلقائيًا.

---

أمثلة الكود

cURL — عرض الـ Providers

curl https://api.ithbat.io/api/v1/auth/social/providers \
  -H "X-Tenant-ID: ten_01J8X..."

cURL — بدء Social Login

وجّه browser المستخدم لهذا الـ URL:

curl -L "https://api.ithbat.io/api/v1/auth/social/google/login?redirect_uri=https://app.example.com/callback" \
  -H "X-Tenant-ID: ten_01J8X..."

JavaScript SDK

import { IthbatSDK } from '@ithbatiam/sdk';

const ithbat = new IthbatSDK({
  tenantId: 'ten_01J8X...',
  baseUrl: 'https://api.ithbat.io',
});

// Get available providers
const providers = await ithbat.auth.listSocialProviders();
// [{ provider: 'google', name: 'Google', enabled: true }, ...]

// Start OAuth flow — this redirects the browser
ithbat.auth.startSocialLogin('google', {
  redirectUri: 'https://app.example.com/auth/callback',
});

// Link a social identity to the current user
await ithbat.auth.linkIdentity('github', {
  code: '4/0AX4XfWh...',
  redirectUrl: 'https://app.example.com/settings',
});

// List linked identities
const identities = await ithbat.auth.listIdentities();

// Unlink a provider
await ithbat.auth.unlinkIdentity('github');

---

معالجة الأخطاء

HTTP Status	Error Code	السبب
400	VALIDATION_ERROR	redirect_uri أو X-Tenant-ID ناقص
400	VALIDATION_ERROR	state أو code ناقص في الـ Callback
401	UNAUTHORIZED	الـ Provider رجع خطأ أو رفض الوصول
404	NOT_FOUND	الـ Provider غير مُعد لهذا المستفيد
409	CONFLICT	الـ Social Identity مرتبطة بحساب ثاني

---

الخطوات التالية

• البريد وكلمة المرور — دمج مع تسجيل دخول بكلمة المرور لتجربة هجينة
• Token Lifecycle — فهم الـ Tokens الذي ترجع بعد Social Login
• MFA — طلب عامل ثانٍ حتى لمستخدمي Social Login