الاتصال باستخدام OAuth

فوّض عملاء MCP وواجهة سطر الأوامر لـ ThunderPhone دون مشاركة مفتاح API.

يتيح OAuth لتطبيق ما الاتصال بمؤسسة ThunderPhone واحدة باستخدام الأذونات التي توافق عليها. يجب أن تستخدم عملاء الدليل OAuth افتراضيًا. تظل مفاتيح API الخاصة بالمؤسسة متاحة للعملاء الذين يتطلبون رمز Bearer مهيأً يدويًا.

الموافقة على اتصال#

ابدأ الاتصال في عميل MCP لديك. سجّل الدخول إلى ThunderPhone، وتحقق من اسم التطبيق والأذونات المطلوبة، واختر مؤسسة، ثم حدّد موافقة. حدّد رفض إذا لم تكن قد بدأت الاتصال أو إذا كنت لا تثق بالتطبيق. يوفّر المطورون أسماء التطبيقات، وهي ليست شارة تحقق.

تكشف أذونات القراءة البيانات المُسمّاة، بما في ذلك التسجيلات والنصوص المفرغة عند طلب calls:read. يمكن لأذونات الكتابة تغيير الموارد أو حذفها؛ وقد تؤدي المكالمات والحملات وشراء أرقام الهاتف وعمليات النشر إلى تكاليف أو تؤثر في بيئة الإنتاج. يظل دورك في المؤسسة ساريًا.

لاتصال CLI، افتح رابط التحقق الظاهر في الطرفية، وقارن الرمز المكوّن من ثمانية أحرف، واختر مؤسستك، ثم وافق. لا يمنح مجرد فتح الرابط إمكانية الوصول. تنتهي صلاحية الرموز بعد 15 دقيقة.

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

افتح المؤسسة → مفاتيح API → التطبيقات المصرح بها في لوحة التحكم واختر إلغاء التفويض. يؤدي ذلك إلى إلغاء التفويض الذي حددته للمؤسسة الحالية، بما في ذلك رموز الوصول والتحديث الخاصة به. أعد الاتصال من التطبيق إذا أردت تفويضه مرة أخرى.

الاكتشاف لعملاء MCP#

استخدم عنوان URL للخادم https://api.thunderphone.com/v1/mcp. يتلقى الطلب دون مصادقة صالحة الرمز 401 مع:

WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource"

اجلب هذا المستند، ثم اجلب بيانات تعريف خادم التفويض من https://api.thunderphone.com/.well-known/oauth-authorization-server. تتوفر بيانات تعريف المورد أيضاً في /.well-known/oauth-protected-resource/v1/mcp. استخدم نقاط النهاية المُعادة بدلاً من إنشائها. معرّف المورد هو https://api.thunderphone.com/v1/mcp.

يدعم الخادم تدفق رمز التفويض مع S256 PKCE، ورموز التحديث الدوّارة، وتسجيل العملاء العام الديناميكي، والإلغاء، ومنح تفويض الجهاز. لا توجد أسرار عملاء أو منح ضمنية. يتوفر اكتشاف OpenID أيضاً في /.well-known/openid-configuration؛ ويتضمن حقول خادم التفويض نفسها بالإضافة إلى subject_types_supported: ["public"] ونقطة نهاية معلومات المستخدم. لا يتم دعم رموز المعرّف ومستندات بيانات تعريف معرّف العميل (CIMD).

تسجيل عميل عام#

أرسل JSON إلى POST /v1/oauth/register:

{
  "client_name": "My MCP client",
  "redirect_uris": ["http://127.0.0.1:8765/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"]
}

احفظ client_id المُعاد. يجب أن تستخدم عمليات إعادة التوجيه HTTPS، أو HTTP على 127.0.0.1 أو localhost. سجّل عنوان URI الدقيق لرد الاتصال، بما في ذلك منفذه ومساره. تُرفض الأجزاء وبيانات الاعتماد المضمّنة. يجب أن يستخدم client_uri وlogo_uri الاختياريان HTTPS؛ ولا يجلبهما ThunderPhone أثناء التسجيل. يخضع التسجيل لتحديد المعدل. لا تنتهي صلاحية العملاء المسجلين، ويظلون مسجلين عند إلغاء اتصال. تتضمن عمليات رد الاتصال عبر HTTPS كلاً من https://chatgpt.com/connector/oauth/<id> وhttps://chatgpt.com/connector_platform_oauth_redirect. يمكن لكل اتصال تسجيل عميله الخاص.

رمز التفويض#

افتح نقطة نهاية التفويض المكتشفة باستخدام client_id، وredirect_uri المسجل بدقة، وresponse_type=code، وstate عشوائي، وscope، وcode_challenge، وcode_challenge_method=S256، وresource=https://api.thunderphone.com/v1/mcp. احسب التحدي على أنه ملخص SHA-256 بترميز base64url دون حشو لمتحقق PKCE جديد وعالي الإنتروبيا. تحقق من state وiss المُعادين قبل استبدال الرمز. تحدد كل استجابة تفويض، بما فيها الرفض وأخطاء البروتوكول، جهة الإصدار باستخدام iss، المطابق تماماً لـ issuer المكتشف. تُعاد أخطاء العميل أو رد الاتصال غير الصالحين محلياً دون إعادة التوجيه إلى رد الاتصال ذلك.

استبدل الرمز عند POST /v1/oauth/token باستخدام ترميز النماذج، مع قبول JSON أيضاً:

grant_type=authorization_code
client_id=<your client id>
code=<single-use authorization code>
redirect_uri=<exact registered redirect URI>
code_verifier=<original PKCE verifier>
resource=https://api.thunderphone.com/v1/mcp

يُقبل المعلَمة resource الاختيارية في طلبيات التفويض والرمز كليهما، بما في ذلك عمليات التحديث وتبادل رموز الأجهزة. عند حذفها، تكون افتراضياً مورد MCP المكتشف. عند وجودها، يجب أن تطابق ذلك المورد تماماً؛ وتُرجع القيم الأخرى invalid_target. تحمل رموز الوصول ذلك الجمهور، ويرفض MCP الرموز التي تفتقد إلى جمهور أو تحمل جمهوراً مختلفاً باستخدام 401 وتحدي اكتشاف.

تنتهي صلاحية طلبات التفويض والرموز بعد 10 دقائق. تحتوي كل استجابة رمز على access_token، وtoken_type (Bearer)، وexpires_in (3600 ثانية افتراضياً)، وrefresh_token، وscope، وorganization_id، وorganization_name. أرسل رموز الوصول عبر رأس Authorization: Bearer فقط. لا تضع الرموز مطلقاً في عناوين URL أو السجلات أو التحكم بالمصادر أو المحادثات.

التحديث والإلغاء#

حدّث باستخدام grant_type=refresh_token وclient_id وrefresh_token وresource عند نقطة نهاية الرمز. احفظ رمز التحديث الجديد بصورة ذرية وتوقف عن استخدام القديم. تنتهي صلاحية رموز التحديث بعد 30 يوماً دون تحديث ناجح. يمكن أن يضيّق scope اختياري الأذونات الممنوحة. يتم تضمين offline_access دائماً، وتُصدر رموز التحديث دائماً. يمنح الطلب الأولي دون scope صلاحية offline_access فقط، لذا ينبغي للعملاء طلب الأذونات التي يحتاجونها.

يؤدي إعادة استخدام الرمز وإعادة استخدام رمز تحديث دوّار إلى إلغاء التفويض بالكامل. نفّذ عمليات التحديث بشكل متسلسل ضمن العميل؛ إذ إن إعادة تشغيل بيانات اعتماد تم استبدالها بنجاح ليست استراتيجية إعادة محاولة آمنة.

لقطع الاتصال، أرسل token وclient_id إلى POST /v1/oauth/revoke. يؤدي إلغاء أي من الرمزين إلى إلغاء تفويضه، بما في ذلك جميع الرموز الصادرة منه. يعيد الرمز غير المعروف نجاحاً دون الإفصاح عما إذا كان موجوداً. يمكن لجلسات لوحة التحكم إدراج تفويضاتها الخاصة عند GET /v1/oauth/grants وإلغاء أحدها عند DELETE /v1/oauth/grants/<id>، مع استخدام X-ThunderPhone-Org لاختيار المؤسسة.

تفويض الجهاز#

يقتصر تفويض الجهاز على العملاء المسجلين مسبقاً؛ ويتلقى العملاء المسجلون ديناميكياً unauthorized_client. يدعم العميل العام المسجل مسبقاً thunderphone-cli تفويض الجهاز والتحديث. أرسل client_id=thunderphone-cli وscope إلى POST /v1/oauth/device/code. اعرض user_code وverification_uri للمستخدم، أو افتح verification_uri_complete.

استطلع نقطة نهاية الرمز باستخدام grant_type=urn:ietf:params:oauth:grant-type:device_code وclient_id وdevice_code، مع الانتظار لمدة لا تقل عن interval المُعاد، وهي 5 ثوانٍ. تابع عند authorization_pending. عند slow_down، استخدم interval الجديد المُعاد في الاستجابة، والذي يزيد بمقدار 5 ثوانٍ، لكل طلب لاحق. توقف عند access_denied أو expired_token أو أي خطأ آخر. لا توافق على رمز جهاز تلقائياً مطلقاً.

يقبل العميل المسجل مسبقاً thunderphone-mcp كلاً من http://127.0.0.1/callback وhttp://localhost/callback على أي منفذ. يجب أن يتطابق المخطط والمضيف والمسار والاستعلام؛ ويجب أن يستخدم استبدال الرمز عنوان URI الدقيق لإعادة التوجيه، بما في ذلك المنفذ، من التفويض. يتطلب العملاء المسجلون ديناميكياً مطابقة دقيقة لعنوان URI لإعادة التوجيه، بما في ذلك المنفذ. سجّل رد اتصال مختلفاً ديناميكياً إذا احتجت إلى مسار آخر.

التحقق من هوية الحساب ونطاق مساحة العمل#

اطلب كلاً من openid email إلى جانب نطاقات العملية التي يحتاجها عميلك. استدعِ userinfo_endpoint المكتشفة (GET /v1/oauth/userinfo) باستخدام رمز الوصول في رأس Bearer. تحتوي الاستجابة الناجحة على:

{
  "sub": "123",
  "email": "person@example.com",
  "email_verified": true,
  "name": "Example User",
  "org_id": 456
}

sub هو معرّف المستخدم الثابت؛ وorg_id هي المؤسسة المحددة أثناء الموافقة. تتطلب نقطة النهاية نطاقي الهوية كليهما وتعيد 403 إذا كان أحدهما مفقوداً. تعيد 403 مع error=access_denied إذا لم يكن للحساب ملف بريد إلكتروني موثّق، بدلاً من تأكيد أن بريداً إلكترونياً غير موثّق موثوق به. تعيد الرموز غير الصالحة أو منتهية الصلاحية أو الملغاة أو ذات الجمهور الخاطئ 401. لا تستطيع رموز جلسات المستخدم ومفاتيح واجهة برمجة التطبيقات الخاصة بالمؤسسة استدعاء معلومات المستخدم. لا يتم إصدار رمز معرّف.

الأذونات المتاحة#

تستخدم طلبات GET وHEAD وOPTIONS نطاقات القراءة؛ وتستخدم الطرق الأخرى نطاقات الكتابة. لا تتوفر تعديلات الأصوات والفوترة عبر OAuth؛ يستخدم POST /v1/voices/preview النطاق voices:read لأنه يعاين صوتًا دون تغيير إعداداته. تفرض أدوات MCP نطاق عملية REST الأساسية الخاصة بها. تُرفض عمليات النقل بين المؤسسات حتى عندما ينتمي المستخدم الذي يمنح التفويض إلى كلتا المؤسستين. لا تتوفر عبر OAuth عائلات API الأخرى، بما في ذلك إدارة مفاتيح API وإعدادات الحساب البشري. يؤدي غياب إذن لعملية REST إلى إرجاع 403 مع WWW-Authenticate: Bearer error="insufficient_scope", scope="...". تُرجع رموز الوصول غير الصالحة أو منتهية الصلاحية 401.

إشارات مصادقة أدوات MCP#

تتضمن كل أداة في tools/list القيمة securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]، مع نطاق عملية REST الخاصة بتلك الأداة. تستخدم أدوات الوثائق العامة قائمة نطاقات فارغة، ولا تزال تتطلب اتصالًا موثّقًا.

يتلقى الرمز المميز الصالح الذي يفتقد نطاق أداة ما HTTP 200 مع result بصيغة JSON-RPC يحتوي على isError: true، ونص توضيحي في content، و_meta["mcp/www_authenticate"]. الأخيرة مصفوفة تحتوي على تحدي Bearer مع resource_metadata وerror="insufficient_scope" وerror_description والنطاق scope المطلوب. لا تُنفذ الأداة. استخدم هذا التحدي لطلب موافقة موسعة. تستمر المصادقة المفقودة أو غير الصالحة في إرجاع HTTP 401 مع WWW-Authenticate؛ وتستمر حالات فشل نطاق REST في إرجاع HTTP 403.

الاحتفاظ ببيانات الاعتماد#

تشغّل API الأمر python manage.py oauth_cleanup كل ساعة في بيئتي الاختبار المرحلي والإنتاج. يزيل طلبات التفويض ورموز الأجهزة منتهية الصلاحية. لا تُحذف رموز الوصول ورموز التفويض وتجزئات رموز التحديث منتهية الصلاحية إلا بعد إلغاء منحها أو انتهاء صلاحية العائلة بالكامل. تُحتفظ بالتجزئات المستخدمة ما دامت العائلة تحتوي على رمز تحديث أو رمز تفويض أو رمز جهاز معتمد أو رمز وصول قابل للاستخدام، بحيث لا يمكن لعملية التنظيف تعطيل اكتشاف إعادة التشغيل.