> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# مصادقة MCP في Didit: تسجيل الدخول عبر OAuth

> مصادقة Didit MCP عبر OAuth 2.1 وPKCE والتسجيل الديناميكي للعميل وبيانات تعريف المورد والنطاقات والأدوار، مع طريقة الاتصال من كل عميل.

يُجري Didit MCP المصادقة باستخدام **تسجيل الدخول باستخدام Didit** (OAuth 2.1). ويعمل بصفته **مستخدمًا** لدى Didit، بصلاحيات دورك في وحدة التحكم، **ولا يوجد وضع لاستخدام مفتاح API**.

***

## تسجيل الدخول باستخدام Didit

يعمل الخادم المستضاف (`https://mcp.didit.me/mcp`) كـ**خادم موارد** وفق OAuth 2.1. أما **Didit Business Console** (`business.didit.me`) فهو **خادم التفويض** الذي يستضيف شاشة الموافقة ويصدر الرموز. يتولى عميل MCP لديك تنفيذ التدفق القياسي تلقائياً:

**1. الاكتشاف**

يرسل العميل طلباً إلى `/mcp` دون رمز، فيتلقى الاستجابة `401` مع ترويسة `WWW-Authenticate: Bearer` يشير حقل `resource_metadata` فيها إلى بيانات وصف المورد المحمي (RFC 9728):

```text theme={null}
https://mcp.didit.me/.well-known/oauth-protected-resource/mcp
```

يحدد هذا المستند المورد (`https://mcp.didit.me/mcp`) وخادم التفويض (`https://business.didit.me`) والنطاقات المدعومة. ويُقدَّم المستند نفسه أيضاً في جذر النطاق `https://mcp.didit.me/.well-known/oauth-protected-resource`، للعملاء الذين يتحققون من هذا المسار أولاً.

**2. التسجيل (تسجيل العميل الديناميكي)**

يقرأ العميل بيانات وصف خادم التفويض من `https://business.didit.me/.well-known/oauth-authorization-server`، وإذا لم يكن لديه معرّف عميل بعد، يسجّل نفسه عند `registration_endpoint` (RFC 7591). لا يلزمك تهيئة أي شيء مسبقاً: يسجّل بهذه الطريقة العملاء المحليون الذين يستخدمون رابط استدعاء محلياً (loopback) أو أصلياً (Claude Code وCursor وMCP Inspector)، والعملاء المستضافون على السحابة الذين يستخدمون رابط استدعاء مُراجَعاً (Claude). يُرفض رابط الاستدعاء البعيد الذي لم تراجعه Didit مع الخطأ `invalid_redirect_uri`، ويحتاج ذلك العميل إلى أن يسجّله المشغّل أولاً.

**3. التفويض (PKCE)**

يفتح العميل `https://business.didit.me/authorize` مع تحدي PKCE بطريقة S256. تسجّل دخولك (أو تنشئ حساباً) وترى بدقة الأذونات المطلوبة. العملاء عموميون: نقطة endpoint الخاصة بالرموز لا تقبل سرّ عميل (قيمة `token_endpoint_auth_methods_supported` هي `none`)، لذلك فإن PKCE هو ما يربط الرمز بالعميل.

**4. الموافقة**

توافق. يُنشئ الكونسول جلسة لهذا التطبيق مرتبطة بالنطاقات التي وافقت عليها، ويعيد رمز تفويض يستبدله العميل عند `token_endpoint` برمز وصول ورمز تحديث.

**5. استدعاء الأدوات**

يرسل العميل رمز الوصول مع كل طلب. يتحقق MCP منه عبر فحص الرمز وفق RFC 7662 لدى خدمة المصادقة في Didit (الرموز غير شفافة، وليست JWT)، ويقرأ أذونات مؤسستك من استجابة الفحص، ويعمل **نيابةً عنك** طوال مدة ذلك الطلب.

### النطاقات

تعلن بيانات وصف المورد عن ثلاثة نطاقات. تعرض شاشة الموافقة النطاقات التي يطلبها العميل بلغة واضحة:

| النطاق | يمنح |
| - | - |
| `didit:management` | إدارة مساحة عملك: `organization`، و`members`، و`subscription`، و`users`، و`applications`، و`workflows`، و`customization`، و`questionnaires`، و`lists`، و`webhooks`، و`integrations`، و`api-keys`، و`audit-logs`، و`roles`، و`saml`، و`analytics`. |
| `didit:verification` | تشغيل الفحوصات ومراجعتها: `sessions`، و`businesses`، و`cases`، و`networks`، و`transactions`، و`blocklist`، و`analytics`. |
| `didit:staff` | محجوز لحسابات موظفي Didit. لا يفتح أي شيء لحساب عادي، ولا تعرّف النسخة مفتوحة المصدر أي أدوات مخصصة للموظفين فقط. |

يتضمّن النطاقان `analytics`. إدارة `lists` تتطلب `didit:management`، والوصول إلى `blocklist` يتطلب `didit:verification`.

يذكر [مرجع الأدوات](https://docs.didit.me/ar/integration/mcp/tools.md) النطاق الذي تنتمي إليه كل أداة. تُدمج النطاقات التي توافق عليها ضمن الرمز، وتُفرض على الخادم، لذلك يُرفض التطبيق المتصل بـ`didit:verification` وحده على واجهة الإدارة حتى لو كان دورك يسمح بذلك. كما يعرف خادم التفويض نطاقات OpenID (`openid profile email`)؛ والاتصال الذي يطلب هذه النطاقات فقط يستطيع أن يعرف هويتك ولا شيء آخر.

الأذونات الفعلية للتطبيق هي **تقاطع** النطاقات المعتمدة مع دورك في الكونسول، ولا تكون أبداً أوسع من أيٍّ منهما.

لإنشاء جلسة تحقق باستخدام `didit_session_create` تحتاج إلى النطاق `didit:verification` **و** دور يتضمن `create:sessions` أو `write:sessions`. يتضمن الدور **المطوّر** الإذن `create:sessions`. الموافقة على `didit:management` وحده لا تتيح إنشاء الجلسات، حتى لو كان دورك يملك الإذن المطلوب.

### الأدوار والأذونات

يمثّل الرمز المستضاف إياك، لذلك يستطيع الوكيل العمل عبر **كل مؤسسة تنتمي إليها** في اتصال واحد؛ إذ تجمع الأدوات العابرة للتطبيقات (`didit_session_search`، و`didit_analytics`، و`didit_context_get`، وبقية أدوات `*_search`) النتائج من جميعها تلقائياً.

تفرض **الواجهة الخلفية لـDidit دورك دائماً**، لكل مؤسسة على حدة. تقابل كل أداة سلسلة إذن واحدة في الخلفية (مثلاً `write:sessions` للأداة `didit_session_update_status`، و`delete:sessions` للأداة `didit_session_delete`)، ويعرض [مرجع الأدوات](https://docs.didit.me/ar/integration/mcp/tools.md) الإذن الخاص بكل أداة. ويتحقق الخادم أيضاً من هذا الإذن قبل إرسال الطلب، مستخدماً الأذونات التي تحملها استجابة الفحص لمؤسستك:

* في وضع `enforce` تُستبعد من `tools/list` الأداةُ التي لا يستطيع دورك تشغيلها، وإذا استُدعيت رغم ذلك يُعاد خطأ `missing_scope` يذكر الإذن (`"Your role in this organization does not include the permission 'delete:sessions' that didit_session_delete requires."`).
* في وضع `shadow` (وهو الوضع الافتراضي للخادم) تُدرج كل الأدوات في القائمة، ويُمرَّر الاستدعاء إلى الواجهة الخلفية، فتجيب بـ`403` إذا كان الدور يفتقر إلى الإذن؛ ولا يُسجَّل الحكم إلا في سجل التدقيق الخاص بالخادم.

وفي الحالتين لا يمنح MCP أكثر مما يسمح به دورك في الكونسول أصلاً. يستطيع `READER` أن يعرض ويقرأ، أما `OWNER` أو `ADMIN` فيستطيعان الكتابة والحذف.

### مدة صلاحية الرمز

يحصل التطبيق المعتمد على جلسة خاصة به، منفصلة عن جلسة المتصفح التي وافقت عبرها. رموز الوصول قصيرة الأجل؛ ويجدّدها العميل بصمت باستخدام رمز التحديث (يتضمن `grant_types_supported` القيمة `refresh_token`)، ويحتفظ التجديد بنطاقات التطبيق ويبقى مرتبطاً بذلك التطبيق. وإذا فشل التجديد (مثلاً بعد أن تفصل التطبيق)، يعيد العميل تشغيل **تسجيل الدخول باستخدام Didit** عند الاستدعاء التالي.

تسجيل الخروج من وحدة التحكم لا يسجّل الخروج من التطبيقات المتصلة، وقطع اتصال أي تطبيق لا يسجّل خروجك في أي مكان.

### قطع اتصال تطبيق

**1. من وحدة التحكم**

**Settings → Authentication → Connected apps** تعرض كل تطبيق وافقت عليه، مع اسمه المسجّل والأذونات التي مُنحت له. **قطع الاتصال** ينهي وصول ذلك التطبيق فورًا: يتوقف عن العمل كلٌّ من رمز الوصول ورمز التحديث، ولا يتأثر أي شيء آخر.

**2. من التطبيق (RFC 7009)**

يمكن للعميل أن يتخلى عن وصوله بإرسال الـ token إلى `revocation_endpoint` الخاص بخادم التفويض، المنشور في البيانات الوصفية عند `https://business.didit.me/.well-known/oauth-authorization-server`. وكما يقتضي RFC 7009، يُرجع الاستدعاء الناجح الاستجابة `200` سواء كان الـ token ما زال فعالًا أم لا، لذلك لا تكشف الاستجابة أبدًا إن كان الـ token صالحًا. تعني الاستجابة `503` أن الإلغاء لم يُطبَّق: اعتبر الـ token ما زال صالحًا وأعد المحاولة.

```bash theme={null}
curl -X POST https://business.didit.me/api/auth/oauth-revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "<refresh-or-access-token>", "token_type_hint": "refresh_token", "client_id": "<your-client-id>"}'
```

> [!NOTE]
>
> **لماذا لا يوجد مفتاح API؟** تستدعي كل أداة MCP نقاط نهاية وحدة التحكم المخصّصة لنطاق المستخدم (`/organization/{org}/application/{app}/…`)، والتي تُصادق على Bearer token مع صلاحيات لكل دور، و**ترفض `x-api-key`**. مفتاح API الخاص بالتطبيق مخصص لاستدعاء [REST API](https://docs.didit.me/openapi-25.json) مباشرةً من الخادم الخلفي الخاص بك (مثل إنشاء الجلسات)، وليس لهذا الـ MCP. تعرض `didit_org_list_api_keys` بيانات المفاتيح مع إخفاء قيمها، والأداة التي تكشف المفتاح الخام مخفية على الموصل المستضاف.

***

## الربط من كل عميل

يتبع كل عميل التدفق نفسه، والفرق الوحيد هو الطريقة التي تمرّر بها الرابط إليه.

> [tab] Claude
>
> استخدم الرابط المباشر الذي تعرضه وحدة التحكم للشركات في صفحة التكامل. يفتح claude.ai مع نافذة **Add custom connector** معبّأة مسبقًا:
>
> ```text theme={null}
> https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp
> ```
>
> أكّد، ثم أكمل **تسجيل الدخول باستخدام Didit**. يستخدم Claude Desktop الرابط نفسه تحت **Settings → Connectors → Add custom connector**. التفاصيل في [ربط Claude](https://docs.didit.me/ar/integration/mcp/claude.md).

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http didit https://mcp.didit.me/mcp
> ```
>
> ثم شغّل `/mcp` داخل Claude Code لبدء تسجيل الدخول عبر المتصفح.

> [tab] Cursor
>
> `~/.cursor/mcp.json`:
>
> ```json theme={null}
> { "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }
> ```
>
> يسجّل Cursor نفسه ويفتح المتصفح عند أول استخدام.

> [tab] عميل عام
>
> وجّه أي عميل Streamable HTTP يدعم OAuth 2.1 إلى `https://mcp.didit.me/mcp`. ينبغي أن يقوم بالخطوات التالية:
>
> 1. أرسل `POST /mcp` فيستلم `401` ويقرأ `resource_metadata` من `WWW-Authenticate`.
> 2. اجلب `https://mcp.didit.me/.well-known/oauth-protected-resource/mcp`، ثم البيانات الوصفية لخادم التفويض على `https://business.didit.me/.well-known/oauth-authorization-server`.
> 3. سجّل عند `registration_endpoint` إذا لم يكن لديه معرّف عميل.
> 4. نفّذ تدفق رمز التفويض مع PKCE (S256) عند `authorization_endpoint`، ثم استبدل رمز التفويض عند `token_endpoint`.
> 5. أرسل `Authorization: Bearer <access_token>` مع كل `POST /mcp`.
>
> يمكن للعملاء الذين لا يدعمون OAuth العمل خلف `npx -y mcp-remote@latest https://mcp.didit.me/mcp`، الذي ينفّذ الخطوات من 1 إلى 5 نيابةً عنهم.

***

## أخطاء المصادقة

```text theme={null}
HTTP 401
WWW-Authenticate: Bearer error="invalid_token", error_description="Missing Authorization header", resource_metadata="https://mcp.didit.me/.well-known/oauth-protected-resource/mcp"
```

يعني الرد `401` من `/mcp` أن الـ token مفقود أو منتهي الصلاحية أو تم إلغاؤه، وينبغي للعميل حينها أن يجدّد الـ token أو يعيد تشغيل **تسجيل الدخول باستخدام Didit**.

الرد `403` أو خطأ `missing_scope` على أداة *محددة* يعني غالبًا أحد أمرين: إما أن **دورك** لا يملك الإذن المطلوب لتلك الأداة (مثل أن يحاول `READER` تنفيذ عملية كتابة)، أو أن الاتصال وُوفق عليه **دون النطاق** الذي تحتاجه تلك الأداة، وليس أن الاتصال كله معطّل. إعادة الاتصال والموافقة على النطاقين تحل الحالة الثانية، أما الحالة الأولى فتحتاج إلى تغيير الدور.

إذا فشلت كل الأدوات، تحقق من **Settings → Authentication → Connected apps** في وحدة التحكم: التطبيق الذي قُطع اتصاله هناك يجب أن يُوافَق عليه من جديد.

***

> [card] [مرجع الأدوات](https://docs.didit.me/ar/integration/mcp/tools.md)
>
> ما تفعله كل أداة، ونطاقها، وإذن الدور الخاص بها.

> [card] [متقدم](https://docs.didit.me/ar/integration/mcp/advanced.md)
>
> الأدوار، والسلوك بين التطبيقات، والاستضافة الذاتية.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.