دليل الإعداد الفني لمشغّلي شبكات الجوّال في FPNV

تاريخ التعديل الأخير: 10 سبتمبر 2025

نظرة عامة

يتضمّن هذا المستند جميع الخطوات الإلزامية لإعداد مشغّل شبكة جوّال على خدمة "تأكيد رقم الهاتف في Firebase" (FPNV) من خلال عمليات تأكيد رقم الهاتف وفقًا للمواصفة TS.43.

مصطلحات

الجهات المعنية

• مقدّم خدمات الاتصالات (CSP)
  • مثلاً، مشغّلو شبكات الجوّال
• مواقع تجميع المحتوى
  • مجمّعات تواجه التطبيقات: هي مجمّعات تسمح للتطبيقات بإجراء عملية تحقق بدون أن يتفاعل التطبيق مباشرةً مع مشغّل شبكة الجوّال.
  • على سبيل المثال، خدمة "إثبات ملكية رقم الهاتف" في Firebase
  • مجمّع البيانات الوصفية: هو مجمّع يتيح لمشغّل شبكة الجوّال إمكانية الانضمام إلى مجمّع بيانات وصفية متاح للتطبيقات
    • يمكن أن يكون المجمّع الفائق مسؤولاً عن إعداد خوادم تحديد الأهلية لشركات النقل و/أو إعداد تفاصيل خوادم تحديد الأهلية مع المجمّعات التي تواجه التطبيقات.
• FPNV: خدمة إثبات ملكية رقم الهاتف في Firebase
• مدير الحسابات التقنية في Google: هو مدير حسابات تقنية في Google يساعد في إعداد شركة النقل لاستخدام ميزة "التحقّق من اسم النشاط التجاري على شبكة Google"
• خدمة "هاتف Android": توفّر واجهات برمجة تطبيقات لأرقام الهواتف على Android، بما في ذلك منصة للمشغّلين ومجمّعي البيانات لتوفير عمليات التحقّق من TS.43.
• الرابطة العالمية لمشغّلي شبكات الجوّال (GSMA): هي رابطة تضم مشغّلي شبكات الجوّال الذين يحدّدون المواصفات، بما في ذلك TS.43
• CAMARA: مشروع مفتوح المصدر لنظام التشغيل Linux يحدّد واجهات برمجة التطبيقات الخاصة بمشغّلي شبكات الجوّال بالتعاون مع الرابطة العالمية لمشغّلي شبكات الجوّال (GSMA)

بنود التحقّق

• PNV: إثبات ملكية رقم الهاتف
• TS.43: يحدّد البروتوكول الذي تستخدمه أجهزة العميل الجوّالة والخوادم للتواصل مع مشغّل شبكة الجوّال باستخدام HTTP
• EAP-AKA: طريقة مصادقة محدّدة في https://www.rfc-editor.org/rfc/rfc4187، ولا تتطلّب التفاعل مع المستخدم
• ECS: Entitlement Configuration Server
  • نقطة الدخول التي يمكن من خلالها لمجمّع المحتوى التواصل مع مشغّل شبكة الجوّال
• ODSA: تفعيل الخدمة على الجهاز
  • تشير إلى العمليات المختلفة التي يوفّرها نظام ECS لتفعيل الخدمات على الجهاز
  • على سبيل المثال، AcquireTemporaryToken أو GetPhoneNumber

خادم التحقّق من أهلية مشغّل شبكة الجوّال ونقطة نهاية PNV

إنشاء نقاط النهاية اللازمة

ACTION1: ينفّذ مشغّل شبكة الجوّال نقاط النهاية التالية، والتي يمكن الوصول إليها جميعًا من خلال الإنترنت. يمكنك الاطّلاع على الملحق (أ) لمزيد من التفاصيل حول عملية التنفيذ.

المتطلبات الفنية

الأداء العام: يجب أن يكون وقت التشغيل لجميع نقاط النهاية %99.99 على الأقل.

الأمان: لأسباب تتعلّق بالأمان، يجب أن تستوفي نقاط نهاية مشغّل شبكة الجوّال المتطلبات التالية:

• رمز مصادقة EAP-AKA: يجب أن تنتهي صلاحيته خلال ساعة واحدة
• الرمز المميز المؤقت: يُستخدَم مرة واحدة وتنتهي صلاحيته بعد 5 دقائق
• الخيار 1 - Vanilla TS.43
  • رمز OAuth المميز: يجب أن تنتهي صلاحيته في غضون ساعة واحدة
• الخيار 2 - CAMARA
  • رمز الدخول إلى CAMARA: يمكن استخدامه مرة واحدة وتنتهي صلاحيته بعد 5 دقائق

جودة البيانات في واجهة برمجة التطبيقات: يجب أن تكون جميع محتويات الاستجابات الناجحة دقيقة (أي يجب أن يكون رقم MSISDN دقيقًا).

تتوافق ميزة FPNV مع نوعَين من معيار TS.43. ويكمن الاختلاف الرئيسي في طريقة تبادل خادم FPNV لرمز TempToken مع شركة الاتصالات.

• Vanilla TS.43: يشير إلى التنفيذ على النحو المنصوص عليه في مواصفات TS.43
• CAMARA: تشير إلى التنفيذ على النحو المنصوص عليه في تدفق حامل رمز JWT الخاص بـ CAMARA

الخيار 1: تنفيذ مواصفات TS.43 الأساسية

الطلبات من جهاز Android

1. نقطة نهاية EAP-AKA: تعرض رمز مصادقة
2. نقطة نهاية AcquireTemporaryToken: عند توفّر رمز المصادقة، يتم عرض TempToken

الطلبات من خادم FPNV

1. نقطة نهاية OAuth 2.0 - مسار معرّف العميل/السر الخاص ببروتوكول OAuth: عند توفّر معرّف العميل/السر الخاص ببروتوكول OAuth، يتم عرض رمز دخول OAuth
2. نقطة نهاية GetPhoneNumber: عند توفّر رمز الوصول OAuth وTempToken، يتم عرض رقم الهاتف المرتبط بهما.

الخيار 2 - تنفيذ CAMARA

يشبه تنفيذ CAMARA عملية التنفيذ العادية لمواصفات TS.43، باستثناء نقاط النهاية التي تعالج الطلبات من خادم FPNV.

الطلبات من جهاز Android

1. نقطة نهاية EAP-AKA: تعرض رمز مصادقة
2. نقطة نهاية AcquireTemporaryToken: عند توفّر رمز مميّز للمصادقة، يتم عرض TempToken

الطلبات من خادم FPNV

1. نقطة نهاية OAuth 2.0 - مسار حامل JWT: عند توفّر JWT يحتوي على TempToken، يتم عرض رمز دخول CAMARA
2. نقطة نهاية NumberVerification v2 في CAMARA: عند توفّر رمز الدخول في CAMARA، يتم عرض رقم الهاتف المرتبط به.

إعداد ميزة "الهاتف على Android" و"التحقّق من رقم الهاتف"

تطبيق اختبار مشغّل شبكة الجوّال

الإجراء 2: يتواصل مشغّل شبكة الجوّال مع المدير التقني للحسابات (TAM) في Google، ويشارك المدير التقني للحسابات تطبيق اختبار مشغّل شبكة الجوّال FPNV مع مشغّل شبكة الجوّال. يحاكي تطبيق الاختبار هذا الطلبات التي سترسلها خدمة "التحقّق من اسم الشبكة" بدون إشراك خادم الخدمة. ويفيد تطبيق الاختبار هذا مشغّل شبكة الجوّال في التحقّق من أنّ نقاط النهاية تعمل بشكل سليم.

ACTION3: يتحقّق مشغّل شبكة الجوّال من أنّ نقاط النهاية المذكورة أعلاه تعمل بشكل كامل من خلال استخدام تطبيق اختبار مشغّل شبكة الجوّال FPNV.

إعداد إعدادات الإنتاج اللازمة

إعداد Android - EAP-AKA / AcquireTempToken

ACTION4: تحدّد شركة الاتصالات إعدادات الإنتاج لطلباتها EAP-AKA/AcquireTempToken من Android Telephony

• الإعدادات:
  • معرّف مشغل شبكة الجوّال الأساسي على Android لمشغل شبكة الجوّال هذا
  • قيم TS.43 use_cases: use_case=GetPhoneNumber
  • عنوان URL لخادم حقوق الإنتاج في EAP-AKA/AcquireTempToken
  • الاسم البديل للموضوع والملف المرجعي لشهادة x509 الخاصة ببيئة الإنتاج في Firebase
  • SAN: fpnv.googleapis.com
  • بصمة الإصبع: aad068c93399a22fc2b11ab58468e8cb72b8f9fc53700991799a8b764c589c7e

إعدادات Firebase - استبدال TempToken برقم الهاتف

ACTION5: بيانات اعتماد Firebase لاسترداد رمز OAuth المميز من شركة الاتصالات

• Vanilla TS.43
  • تنشئ شركة النقل معرّف عميل OAuth وسرّه لطلبات FPNV. يضبط مشغّل شبكة الجوّال نقطة نهاية OAuth لعرض رمز دخول لهذه البيانات
• CAMARA
  • توفّر خدمة Google TAM المفتاح العام الخاص بـ Google، كي يتمكّن نقطة نهاية OAuth التابعة لمشغّل شبكة الجوّال من التحقّق من أنّ Google وقّعت على رمز JWT.

‫ACTION6: يحدّد مشغّل شبكة الجوّال إعدادات الإنتاج لخادم FPNV من أجل استبدال TempToken برقم هاتف.

• معرّف Android الأساسي لشركة تشغيل شبكة الجوّال
• Vanilla TS.43
  • OAuth - مسار معرّف العميل/السر
  • عنوان URL لنقطة نهاية OAuth
  • معرّف عميل OAuth/سر عميل OAuth
  • نطاق OAuth (إن وُجد)
  • GetPhoneNumber
  • عنوان URL لنقطة النهاية GetPhoneNumber
• CAMARA
  • OAuth - مسار حامل JWT
  • عنوان URL لنقطة نهاية OAuth
  • NumberVerification API v2
  • عنوان URL لنقطة نهاية NumberVerification

مشاركة بيانات الاعتماد/الإعدادات

تأكيد رقم الهاتف في Firebase

ACTION7: يشارك مشغّل شبكة الجوّال إعدادات الإنتاج من ACTION4 وACTION6 مع مدير الحساب الفني في Google.

• [مهم] يجب مشاركة سر OAuth باستخدام آلية آمنة خارج النطاق (بدون رسائل إلكترونية أو مستندات أو غير ذلك) مع Google. سيتم الاتفاق على هذه الآلية خارج النطاق بين شركة الاتصالات ومدير الحساب التقني في Google.

ACTION8: يتحقّق فريق TAM في Google من أنّ الإعدادات تعمل بشكل كامل باستخدام تطبيق الاختبار الخاص بمشغّل شبكة الجوّال. بعد ذلك، سيخزّن فريق TAM في Google بيانات اعتماد OAuth في مساحة تخزين آمنة من Google وسيعدّل إعدادات FPNV لتبديل TempToken برقم هاتف (أي إعدادات ACTION6).

الاتصال الهاتفي على Android

ACTION9: يتبع مشغّل شبكة الجوّال مستند "إعداد Google Open Gateway CSP" (الذي سيشاركه مدير الحسابات التقني (TAM) في Google مع مشغّل شبكة الجوّال). يرسل مشغّل شبكة الجوّال أو مدير الحساب التقني (TAM) في Google تذكرة Buganizer لإعداد الإعدادات على "خدمة الاتصال الهاتفي من Android": https://issuetracker.google.com/issues/new?component=1861595&template=2168610. سيتم إدخال الخطأ في إعدادات الإنتاج من ACTION4.

إذا كان أحد برامج تجميع البيانات الوصفية يضبط عملية الدمج مع FPNV نيابةً عن مشغّل شبكة الجوّال، يجب تقديم بيان موافقة (عبر البريد الإلكتروني أو ملف PDF أو رسالة أو غير ذلك) من القيادة العليا لمشغّل شبكة الجوّال (مستوى مدير أو أعلى) يؤكّد العلاقة التجارية مع مشغّل شبكة الجوّال المذكور. بعد ذلك، يمكن لمجمّع البيانات الوصفية توفير إعدادات مشغّل شبكة الجوّال نيابةً عنه إلى خدمة "هاتف Android".

الملحق (أ) التنفيذ التفصيلي

الحساسية لحالة الأحرف

• عناوين HTTP غير حساسة لحالة الأحرف
• ومع ذلك، فإنّ تنسيقَي XML وJSON حساسان لحالة الأحرف. لذلك، بالنسبة إلى حقول الطلب/الرد، تأكَّد من أنّ الحقول تتطابق مع هذه المستندات تمامًا.

الخطوة 1 - EAP-AKA / AcquireTempToken

نقاط النهاية: يجب أن تستخدم كلّ من EAP-AKA وAcquireTempToken نقطة نهاية ECS نفسها.

EAP-AKA Challenge

المراجع: TS.43 الإصدار 12.0 - القسم 2.8.1 - "مصادقة EAP-AKA المضمّنة من خلال خادم إعداد الأذونات".

الخطوة 1 من بروتوكول المصادقة القابلة للتوسيع (EAP) وبروتوكول المصادقة والمفتاح المتفق عليه (AKA): طلب المصادقة

EAP-AKA #1 - GET Request to ECS

يرسل وحدة Android Telephony طلب TS.43 EAP-AKA إلى خادم تحديد الأهلية التابع لمشغّل شبكة الجوّال.

عناوين الطلبات في Android

• Accept: application/vnd.gsma.eap-relay.v1.0+json
  • هذا التنسيق خاص بـ GSMA وليس application/json فقط.

حقول الطلبات في Android

• eap_id: يُرجى الاطّلاع على الملحق ج من التوصية RCC.14
  • أي 0<IMSI>@<realm>.mnc<MNC>.mcc<MCC>.3gppnetwork.org
• GID1: يتم تحديدها فقط إذا كان إصدار حق الوصول هو 12.0
• ‫app_name: سيحتوي AppName المرمّز على قيمة مجزأة باستخدام MD5 لحالة الاستخدام التي يتم من خلالها إثبات ملكية الهاتف:
  • ستتضمّن جميع طلبات التجميع التي تواجه التطبيق اسم تطبيق Google-OGI
• app: يمثّل معرّف التطبيق ap2014 معلومات رقم الهاتف
• terminal_vendor/model/sw_version: اضبط القيمة على قيمة عشوائية، ولن يضمن نظام التشغيل Android أنّ هذه الحقول تتضمّن معلومات الجهاز الفعلية.
• ‫vers: إصدار الإعدادات، مثل 0 أو 1
• entitlement_version: ستضبط Google إصدار المحتوى الذي يتم إرساله إلى شركات النقل استنادًا إلى ما تطلبه شركة النقل
  • عادةً ما تكون قيمة entitlement_version هي 10.0 أو 12.0

EAP-AKA #1 - Response from ECS

عناوين استجابة ECS

• Content-Type: يتوقّع نظام التشغيل Android أن يتطابق نوع الرد مع عنوان Accept في الطلب
  • أي application/vnd.gsma.eap-relay.v1.0+json

حقول استجابة ECS

• ‫eap-relay-packet: يحتوي على حزمة EAP وفقًا للمعيار RCC.14 - القسم C.2

الخطوة 2 من بروتوكول EAP-AKA - الحصول على رمز المصادقة

EAP-AKA #2 - POST Request to ECS

سيرسل بعد ذلك وحدة Android Telephony النتيجة eap-relay-packet التي تم تلقّيها إلى نقطة النهاية نفسها.

عناوين الطلبات في Android

• Accept: سيضبط Android عنوانَي Accept على النحو التالي:
  • ‫application/vnd.gsma.eap-relay.v1.0+json: يشير إلى أنّ مشغّل شبكة الجوّال يعيد ملف JSON إذا كان الجهاز بحاجة إلى إرسال طلب آخر من نوع EAP-AKA مرة أخرى
  • text/vnd.wap.connectivity-xml: يشير إلى التنسيق الفعلي الذي سيتوقّع نظام التشغيل Android أن تعرضه شركة الاتصالات عند إرجاع رمز مصادقة EAP-AKA
• Content-Type: application/vnd.gsma.eap-relay.v1.0+json

حقول الطلبات في Android

• ‫eap-relay-packet: يحتوي على حزمة eap-relay-packet الخاصة باستجابة EAP-AKA السابقة، ولكن بتنسيق EAP-Response/AKA-Challenge وفقًا لمعيار RFC 4817 - القسم 9.2.

EAP-AKA #2 - Response from ECS

بعد إتمام عملية مصادقة EAP-AKA بنجاح، يعرض مشغّل شبكة الجوّال رمز مصادقة.

عناوين استجابة ECS

• Content-Type: يتوقّع نظام التشغيل Android أن يكون الرد متوافقًا مع عنوان Accept في الطلب
  • أي أنّ نظام التشغيل Android يتوقّع أن يكون نوع الرد الذي يتضمّن رمز المصادقة هو text/vnd.wap.connectivity-xml
  • يتم استخدام عنوان Accept الآخر، application/vnd.gsma.eap-relay.v1.0+json، إذا أراد مشغّل شبكة الجوّال أن يطلب من Android تنفيذ طلب EAP-AKA آخر.

حقول استجابة ECS

• ‫TOKEN.token: يحتوي على رمز المصادقة
• TOKEN.validity: عدد الثواني التي يكون فيها الرد صالحًا بعد أن يتلقّى الجهاز الرد
  • ستتحقّق Google من أنّ رمز المصادقة يستوفي المتطلبات الفنية.

AcquireTemporary Token

AcquireTempToken - طلب GET إلى ECS

باستخدام رمز المصادقة الذي تم تلقّيه من EAP-AKA، يجلب جهاز Android رمزًا مميّزًا مؤقتًا من خلال إرسال طلب إلى نقطة نهاية AcquireTemporaryToken الخاصة بمشغّل شبكة الجوَّال. الطلب

• مثال: TS.43 v12.0 - Section 6.4.6 - "AcquireTemporaryToken Request Example"
• تتضمّن AcquireTempToken مَعلمات مشابهة لمعلمات EAP-AKA #1، باستثناء ما يلي:
  • تحدّد AcquireTempToken أيضًا IMSI, operation وoperation_targets
  • لا تحدّد AcquireTempToken EAP_ID

عناوين الطلبات في Android

• Accept: سيضبط نظام التشغيل Android القيمة text/vnd.wap.connectivity-xml

حقول الطلبات في Android

• terminal_vendor/model/sw_version: لا يضمن نظام التشغيل Android أنّ هذه الحقول تحتوي على معلومات الجهاز الفعلية.
• operation_targets
  • FPNV: هدف العملية هو GetPhoneNumber

AcquireTempToken - Response from ECS

مثال: TS.43 v12.0 - Section 6.6.6 - "AcquireTemporaryToken Response Example"

عناوين استجابة ECS

• Content-Type: يتوقّع نظام التشغيل Android أن يتطابق نوع الرد مع عنوان Accept في الطلب
  • أي text/vnd.wap.connectivity-xml

حقول استجابة ECS

• APPLICATION.TemporaryToken: TemporaryToken التي يمكن لخادم FPNV استبدالها برقم هاتف
• APPLICATION.TemporaryTokenExpiry: وقت انتهاء الصلاحية بالتنسيق YYYY-MM-DDThh:mm:ssTZD
  • ستتحقّق Google من أنّ تاريخ انتهاء صلاحية TempToken يستوفي المتطلبات الفنية.
• APPLICATION.OperationResult: يُرجى الاطّلاع على TS.43 الإصدار 12.0 - القسم 6.5.1
  • على وجه التحديد، إذا كانت العمليات SUCCESS، فسيتم عرض القيمة 1

الخطوة 2 - استبدال TempToken برقم الهاتف

الخيار 1 - Vanilla TS.43

نقاط النهاية: يمكن أن تكون نقاط نهاية OAuth وGetPhoneNumber خوادم/نقاط نهاية مختلفة عن بعضها البعض. يمكن أن تختلف نقاط النهاية هذه أيضًا عن نقطة نهاية EAP-AKA/AcquireTempToken.

OAuth

على مشغّل شبكة الجوّال اتّباع دليل OAuth هذا وتقديم معلومات OAuth اللازمة إلى Google (معرّف العميل وسر العميل وعنوان URL لخادم OAuth).

OAuth - طلب POST إلى خادم المصادقة التابع لمشغّل شبكة الجوّال

عناوين طلبات FPNV

• Authorization: سيتم ضبط FPNV على Basic $BASE64_ENCODED_CREDENTIALS
  • بيانات الاعتماد المشفّرة باستخدام Base64 هي ترميز Base64 لـ OAuth $CLIENT_ID:$CLIENT_SECRET
• Content-Type: سيتم ضبط FPNV على application/x-www-form-urlencoded
• Accept: سيتم ضبط FPNV على application/json

حقول طلب FPNV

• grant_type: client_credentials

POST HTTP/1.1
Host: $OAUTH_ENDPOINT
Authorization: Basic $BASE64_ENCODED_CREDENTIALS
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=client_credentials

OAuth - Response from Carrier's Auth Server

عناوين استجابة مشغّل شبكة الجوّال

• Content-Type: تتوقّع FPNV أن يتطابق نوع الاستجابة مع عنوان Accept في الطلب
  • أي application/json

حقول ردّ مشغّل شبكة الجوّال

• استبدِل access_token برمز الدخول عبر OAuth.
• token_type: bearer
• استبدِل expires_in بتاريخ انتهاء صلاحية رمز الدخول عبر OAuth بالثواني
  • ستتحقّق Google من أنّ وقت انتهاء صلاحية رمز OAuth المميز يستوفي المتطلبات الفنية.

200 OK
Content-Type: application/json

{
  "access_token": $ACCESS_TOKEN,
  "token_type": "bearer",
  "expires_in": $EXPIRATION_IN_SECS,
}

GetPhoneNumber

GetPhoneNumber - طلب POST إلى ECS

يسترد خادم التحقّق من Google رقم الهاتف باستخدام عملية GetPhoneNumber.

• مثال: TS.43 v12.0 - Section 6.4.7 - "GetPhoneNumber Request Example"

عناوين طلبات FPNV

• Accept: application/json
• Content-Type: application/json

حقول الطلبات في FPNV

• ‫requestor_id: تحدّد هذه السمة الخدمة التي تستدعي عملية GetPhoneNumber TS.43
  • معرّف UUID لإثبات ملكية رقم الهاتف في Firebase: 191fd7cc-f7cd-4bb4-a5d2-455ae1fb9a19
• temporary_token: TemporaryToken من AcquireTempToken
• access_token: رمز OAuth المميز الذي تستخدمه Google للمصادقة مع مشغل شبكة الجوّال
• terminal_vendor/model/sw_version: ستملأ FPNV هذه الحقول بقيم عشوائية
• entitlement_version: ستضبط Google إصدار المحتوى الذي يتم إرساله إلى شركات النقل استنادًا إلى ما تطلبه شركة النقل
  • عادةً ما تكون قيمة entitlement_version هي 10.0 أو 12.0
• app: سيتم ضبط FPNV على ap2014
• app_name: ستضبط ميزة "الشبكة الخاصة التي تحافظ على الخصوصية" القيمة firebase لجميع طلبات FPNV
  • ملاحظة: ستتضمّن AcquireTempToken قيمة app_name تساوي Google-OGI، بغض النظر عن أداة التجميع المستخدَمة.
• operation: سيتم ضبط FPNV على GetPhoneNumber

GetPhoneNumber - Response from ECS

مثال: TS.43 v12.0 - Section 6.6.7 - "GetPhoneNumber Response Example"

عناوين استجابة مشغّل شبكة الجوّال

• Content-Type: تتوقّع FPNV أن يتطابق نوع الاستجابة مع عنوان Accept في الطلب
  • أي application/json

حقول ردّ مشغّل شبكة الجوّال

• ap2014.MSISDN: تتوقّع FPNV أن يتم عرض رقم الهاتف بتنسيق E164
  • تتأثر JSON بحالة الأحرف، لذا يجب كتابة MSISDN بالأحرف اللاتينية الكبيرة

رموز الخطأ TemporaryToken

المراجع من TS.43 الإصدار 12.0، الفقرة 2.8.6

يوضّح الجدول التالي الردود التي تشير إلى حدوث خطأ والتي من المتوقّع أن يعرضها ECS على خادم التحقّق من Google لطلبات GetPhoneNumber:

الخيار 2 - CAMARA

نقاط النهاية: يمكن أن يكون استرداد رمز الدخول إلى CAMARA واسترداد رقم الهاتف من خوادم/نقاط نهاية مختلفة. يمكن أن تختلف نقاط النهاية هذه أيضًا عن نقطة نهاية EAP-AKA / AcquireTempToken.

OAuth - استرداد رمز الدخول إلى CAMARA

ستتيح Google استخدام تدفق حامل رمز JWT المميز من CAMARA ولن تتيح استخدام تدفق CIBA.

رمز الدخول إلى CAMARA - طلب POST إلى مشغّل شبكة الجوّال

ستنشئ Google رمز JWT يتضمّن الحقول التالية.

• iss: جهة إصدار رمز JWT (المعروف أيضًا باسم معرّف العميل)
  • على سبيل المثال، firebase (عملية دمج FPNV الفعلية) أو fpnv-carrier-tester-app (تطبيق تجريبي لمشغّل شبكة جوّال)
• sub: موضوع رمز JWT
  • أي operatortoken:$TEMP_TOKEN
• ‫aud: الجمهور؛ المستلمون الذين تم تصميم رمز JWT لهم
  • عنوان URL لنقطة نهاية الرمز المميز (أي عنوان URL لخادم المصادقة)
• ‫exp: وقت انتهاء الصلاحية بالثواني
  • سترسل Google مدة انتهاء صلاحية تتطابق مع المدة التي يجب أن يكون فيها رمز الدخول إلى CAMARA صالحًا (راجِع المتطلبات الفنية).
• ‫iat: تم إصداره في الوقت المحدد بالثواني
• jti: معرّف فريد لتجنُّب هجمات إعادة الإرسال
  • مثلاً، معرّف فريد عالمي (UUID) تم إنشاؤه عشوائيًا
• scope: الغرض من الطلب
  • أي dpv:FraudPreventionAndDetection number-verification:device-phone-number:read

{
  "iss": "firebase",
  "sub": "operatortoken:ey...",
  "aud": $OAUTH_ENDPOINT,
  "exp": $EXPIRATION_TIME_IN_SECS,
  "iat": $ISSUED_AT_TIME_IN_SECS,
  "jti": $RANDOMLY_GENERATED_UUID,
  "scope": "dpv:FraudPreventionAndDetection number-verification:device-phone-number:read"
}

ستوقّع FPNV على رمز JWT باستخدام مفتاحها الخاص، ويمكن لمشغّل شبكة الجوّال التحقّق من صحة رمز JWT باستخدام المفتاح العام المقابل. ستوفّر FPNV المفتاح العام باستخدام نقطة نهاية JWKS. على مشغّلي شبكات الجوّال أن يطلبوا بيانات نقطة نهاية JWKS هذه بانتظام للحصول على المفتاح العام (مثلاً، مرة واحدة في اليوم)، لأنّ ميزة "التحقّق من صحة رقم الهاتف واسمه" ستغيّر المفاتيح العامة بوتيرة منتظمة (مثلاً، مرة واحدة كل 30 يومًا).

عناوين طلبات FPNV

• Content-Type: application/x-www-form-urlencoded
• Accept: application/json

حقول الطلبات في FPNV

• grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer
• assertion: رمز JWT الذي تم إنشاؤه أعلاه وتم توقيعه باستخدام المفتاح الخاص لـ FPNV
  • والجدير بالذكر أنّ رمز JWT هذا يحتوي على TempToken.

POST /token.oauth2 HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&assertion=$JWT

رمز الدخول إلى CAMARA - ردّ من شركة الاتصالات

عناوين استجابة مشغّل شبكة الجوّال

• Content-Type: تتوقّع FPNV أن يتطابق نوع الاستجابة مع عنوان Accept في الطلب
  • أي application/json

حقول ردّ مشغّل شبكة الجوّال

• access_token: رمز الدخول إلى CAMARA، والذي يمكن استبداله لاحقًا برقم هاتف
• token_type: bearer
• استبدِل expires_in بتاريخ انتهاء صلاحية رمز الدخول عبر OAuth بالثواني
  • ستتحقّق Google من أنّ وقت انتهاء صلاحية رمز OAuth المميز يستوفي المتطلبات الفنية.
• scope: الغرض من الطلب
  • أي dpv:FraudPreventionAndDetection number-verification:device-phone-number:read

200 OK
Content-Type: application/json

{
  "access_token": $CAMARA_ACCESS_TOKEN,
  "token_type": "bearer",
  "expires_in": $EXPIRATION_IN_SECS,
  "scope": "dpv:FraudPreventionAndDetection number-verification:device-phone-number:read"
}

الإصدار 2 من واجهة برمجة التطبيقات NumberVerification من CAMARA

ستستبدل Google رمز الدخول هذا من CAMARA من خلال إرسال طلب GET إلى نقطة النهاية /device-phone-number الخاصة بمشغّل شبكة الجوّال.

‫CAMARA NumberVerification - طلب GET إلى مشغّل شبكة الجوّال

عناوين طلبات FPNV

• Authorization: Bearer $CAMARA_ACCESS_TOKEN
• Accept: application/json

GET /device-phone-number
Authorization: Bearer $CAMARA_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

CAMARA NumberVerification - Response from Carrier

عناوين استجابة مشغّل شبكة الجوّال

• Content-Type: تتوقّع FPNV أن يتطابق نوع الاستجابة مع عنوان Accept في الطلب
  • أي application/json

حقول ردّ مشغّل شبكة الجوّال

• devicePhoneNumber: تعرض رقم الهاتف بتنسيق E164

200 OK
Content-Type: application/json

{
 "devicePhoneNumber": $PHONE_NUMBER
}