Руководство по технической проверке номера телефона Firebase для подключения к оператору связи

Дата последнего изменения: 10 сентября 2025 г.

Обзор

В этом документе описаны все обязательные шаги для подключения оператора к системе проверки телефонных номеров Firebase (Firebase PNV) с помощью проверки телефонных номеров TS.43.

Терминология

Вовлеченные стороны

• CSP : Поставщик услуг связи
  • например, операторы мобильной связи
• Агрегаторы
  • Агрегаторы, работающие с приложениями : агрегатор, который позволяет приложениям выполнять проверку без непосредственного взаимодействия приложения с оператором.
    • например, проверка номера телефона Firebase
  • Мета-агрегатор : агрегатор, который помогает оператору подключиться к агрегатору, работающему с приложением.
    • Метаагрегатор может отвечать за настройку серверов прав доступа для операторов и/или настройку данных серверов прав доступа с помощью агрегаторов, работающих с приложениями.
• Firebase PNV : проверка номера телефона Firebase
• Google TAM : технический менеджер по работе с клиентами Google, который помогает оператору адаптироваться к Firebase PNV.
• Телефония на Android : предлагает API телефонных номеров на Android, включая платформу для операторов и агрегаторов, позволяющую проводить проверки TS.43.
• GSMA : Ассоциация операторов мобильной связи, определяющая спецификации, включая TS.43
• CAMARA : проект с открытым исходным кодом Linux, который определяет API-интерфейсы операторов в сотрудничестве с GSMA.

Условия проверки

• PNV : Проверка номера телефона
• TS.43 : определяет протокол для мобильных клиентов и серверов, используемый для связи с оператором связи с использованием HTTP.
• EAP-AKA : Метод аутентификации, определенный в https://www.rfc-editor.org/rfc/rfc4187 , не требующий взаимодействия с пользователем.
• ECS : сервер конфигурации прав
  • Точка входа для взаимодействия агрегатора с оператором
• ODSA : Активация сервиса на устройстве
  • Относится к различным операциям, предоставляемым ECS для активации услуг на устройстве.
  • например AcquireTemporaryToken; GetPhoneNumber

Сервер управления правами оператора и конечная точка PNV

Создание необходимых конечных точек

ДЕЙСТВИЕ 1 : Оператор реализует следующие конечные точки, все из которых доступны через Интернет. Подробнее об этом см. в Приложении А.

Технические требования

Общая производительность : время безотказной работы всех конечных точек должно быть не менее 99,99%.

Безопасность : по соображениям безопасности конечные точки оператора связи должны соответствовать следующим требованиям:

• Токен авторизации EAP-AKA : срок действия должен истечь в течение 1 часа.
• Временный токен : одноразовый, срок действия 5 минут.
• Вариант 1 — Ванильный TS.43
  • Токен OAuth : срок действия должен истечь в течение 1 часа.
• Вариант 2 - КАМАРА
  • Токен доступа CAMARA : одноразовый, срок действия 5 минут

Качество данных API : 100% содержимого успешных ответов (т.е. MSISDN должен быть точным).

Firebase PNV поддерживает две версии TS.43. Основное отличие заключается в том, как сервер Firebase PNV будет обмениваться TempToken с оператором.

• Vanilla TS.43 : относится к реализации, предписанной спецификацией TS.43.
• CAMARA : относится к реализации, предписанной потоком переноса JWT CAMARA.

Вариант 1 — реализация Vanilla TS.43

Запросы с устройства Android

1. Конечная точка EAP-AKA : возврат токена авторизации
2. Конечная точка AcquireTemporaryToken : при наличии токена авторизации вернуть TempToken

Запросы от сервера Firebase PNV

1. Конечная точка OAuth 2.0 — идентификатор клиента OAuth/секретный поток : по полученному идентификатору клиента OAuth/секретному ключу вернуть токен доступа OAuth.
2. GetPhoneNumber Endpoint : с учетом токена доступа OAuth и TempToken вернуть соответствующий номер телефона.

Вариант 2 — Реализация CAMARA

Реализация CAMARA похожа на базовую реализацию TS.43, за исключением конечных точек для обработки запросов от сервера Firebase PNV.

Запросы с устройства Android

1. Конечная точка EAP-AKA : возврат токена авторизации
2. Конечная точка AcquireTemporaryToken : при наличии токена авторизации вернуть TempToken

Запросы от сервера Firebase PNV

1. Конечная точка OAuth 2.0 — поток переноса JWT : при наличии JWT, содержащего TempToken, вернуть токен доступа CAMARA
2. Конечная точка CAMARA NumberVerification v2 : при наличии токена доступа CAMARA вернуть соответствующий номер телефона

Внедрение Android-телефонии и Firebase PNV

Тестовое приложение оператора связи

ДЕЙСТВИЕ 2 : Оператор связи обращается к техническому менеджеру по работе с клиентами Google (TAM), который предоставляет оператору связи тестовое приложение Firebase PNV. Это тестовое приложение имитирует запросы, отправляемые Firebase PNV, без использования сервера Firebase PNV. Это тестовое приложение позволяет оператору связи проверить корректность работы конечных точек.

ДЕЙСТВИЕ 3 : Оператор проверяет сквозную работу вышеуказанных конечных точек с помощью тестового приложения Firebase PNV.

Настройка необходимых производственных конфигураций

Конфигурация Android — EAP-AKA / AcquireTempToken

ДЕЙСТВИЕ 4 : Оператор определяет свою производственную конфигурацию для запросов EAP-AKA/AcquireTempToken от Android-телефонии

• Конфигурация:
  • Канонический идентификатор оператора Android этого оператора
  • Значения use_cases TS.43: use_case=GetPhoneNumber
  • URL-адрес сервера прав на производство для EAP-AKA/AcquireTempToken
  • SAN и отпечаток пальца производственного сертификата Firebase x509
    • SAN : fpnv.googleapis.com
    • Отпечаток пальца : aad068c93399a22fc2b11ab58468e8cb72b8f9fc53700991799a8b764c589c7e

Конфигурация Firebase — обмен TempToken для телефона

ДЕЙСТВИЕ 5 : Учетные данные Firebase для получения токена OAuth от оператора связи

• Ваниль TS.43
  • Carrier создаёт идентификатор и секретный ключ клиента OAuth для запросов Firebase PNV. Затем Carrier настраивает свою конечную точку OAuth для возврата токена доступа для этих учётных данных.
• КАМАРА
  • Google TAM предоставляет открытый ключ Google, чтобы конечная точка OAuth оператора могла проверить, что JWT был подписан Google.

ДЕЙСТВИЕ 6 : Оператор определяет производственную конфигурацию для сервера Firebase PNV для обмена TempToken на телефон

• Идентификатор канонического оператора Android этого мобильного оператора
• Ваниль TS.43
  • OAuth — идентификатор клиента/секретный поток
    • URL конечной точки OAuth
    • Идентификатор/секрет клиента OAuth
    • Область действия OAuth (если есть)
  • Получить номер телефона
    • URL-адрес конечной точки GetPhoneNumber
• КАМАРА
  • OAuth - поток данных JWT
    • URL конечной точки OAuth
  • API NumberVerification v2
    • URL конечной точки NumberVerification

Совместное использование учетных данных/конфигураций

Проверка номера телефона Firebase

ACTION7 : Carrier предоставляет свою производственную конфигурацию из ACTION4 и ACTION6 техническому менеджеру по работе с клиентами Google.

• [ВАЖНО] Секретный ключ OAuth должен быть передан Google через безопасный внешний механизм (без электронной почты, документов и т. д.) . Этот внешний механизм будет согласован оператором связи и техническим менеджером Google.

ACTION8 : Google TAM проверяет сквозную работоспособность конфигурации с помощью тестового приложения оператора. После этого Google TAM сохранит учётные данные OAuth в безопасном хранилище Google и обновит конфигурации Firebase PNV для обмена TempToken на телефон (т.е. конфигурации ACTION6 ).

Android-телефония

ДЕЙСТВИЕ 9 : Оператор связи следует документу «Google Open Gateway CSP Onboarding» (которым технический менеджер Google поделится с оператором связи). Оператор связи или его технический менеджер Google подает заявку Buganizer для подключения к конфигурации Android Telephony: https://issuetracker.google.com/issues/new?component=1861595&template=2168610 . Эта ошибка будет учитываться в рабочей конфигурации из ДЕЙСТВИЯ 4 .

Если метаагрегатор настраивает интеграцию Firebase PNV от имени оператора, необходимо предоставить согласие (электронное письмо, PDF-файл, письмо и т. д.) от руководства оператора (уровня Директор+), подтверждающее деловые отношения с данным оператором. После этого метаагрегатор может предоставить конфигурацию оператора от имени оператора в Android Telephony.

Приложение А. Подробная реализация

Чувствительность к регистру

• HTTP-заголовки не чувствительны к регистру
• Однако форматы XML и JSON чувствительны к регистру. Поэтому убедитесь, что поля запроса/ответа полностью соответствуют этой документации.

Шаг 1 — EAP-AKA / AcquireTempToken

Конечные точки : EAP-AKA и AcquireTempToken должны использовать одну и ту же конечную точку ECS.

Вызов EAP-AKA

Ссылки : TS.43 v12.0 - Раздел 2.8.1 - «Встроенная аутентификация EAP-AKA с помощью сервера конфигурации прав».

EAP-AKA Шаг 1 — Проверка подлинности

EAP-AKA #1 — GET-запрос к ECS

Модуль телефонии Android отправляет запрос TS.43 EAP-AKA на сервер полномочий оператора.

Заголовки запросов Android

• Accept : application/vnd.gsma.eap-relay.v1.0+json
  • Это формат JSON, специфичный для GSMA, а не только application/json

Поля запроса Android

• eap_id : см. RCC.14 Приложение C
  • т. е. 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 — Ответ от ECS

Заголовки ответов ECS

• Content-Type : Android ожидает, что тип ответа соответствует заголовку Accept запроса.
  • т.е. application/vnd.gsma.eap-relay.v1.0+json

Поля ответа ECS

• eap-relay-packet : содержит пакет EAP, соответствующий RCC.14 — раздел C.2

EAP-AKA Шаг 2 — Получение токена авторизации

EAP-AKA #2 — запрос POST в ECS

Затем модуль телефонии Android отправит полученный 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 — Ответ от 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 проверит, соответствует ли токен авторизации техническим требованиям.

Приобретите временный токен

AcquireTempToken — запрос GET к ECS

Используя токен авторизации, полученный от EAP-AKA, клиент Android получает временный токен, вызывая конечную точку AcquireTemporaryToken оператора. Запрос

• Пример : TS.43 v12.0 - Раздел 6.4.6 - «Пример запроса AcquireTemporaryToken»
• 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
  • Firebase PNV : Цель операции — GetPhoneNumber

AcquireTempToken — ответ от ECS

Пример : TS.43 v12.0 - Раздел 6.6.6 - «Пример ответа AcquireTemporaryToken»

Заголовки ответов ECS

• Content-Type : Android ожидает, что тип ответа соответствует заголовку Accept запроса.
  • т.е. text/vnd.wap.connectivity-xml

Поля ответа ECS

• APPLICATION.TemporaryToken : временный токен, который сервер Firebase PNV может затем обменять на номер телефона.
• APPLICATION.TemporaryTokenExpiry : Срок действия в формате ГГГГ-ММ-ДДTчч:мм:ссTZD
  • Google подтвердит, что срок действия TempToken соответствует техническим требованиям.
• APPLICATION.OperationResult : см. TS.43 v12.0 - Раздел 6.5.1
  • В частности, если операции как SUCCESS , то вернуть 1

Шаг 2 — Обмен TempToken на номер телефона

Вариант 1 — Ванильный TS.43

Конечные точки : конечные точки OAuth и GetPhoneNumber могут быть разными серверами/конечными точками. Эти конечные точки также могут отличаться от конечной точки EAP-AKA/AcquireTempToken.

OAuth

Оператор должен следовать этому руководству по OAuth и предоставить Google необходимую информацию по OAuth (идентификатор клиента, секретный код клиента, URL-адрес сервера OAuth).

OAuth — POST-запрос на сервер авторизации оператора

Заголовки запроса Firebase PNV

• Authorization : Firebase PNV установит Basic $BASE64_ENCODED_CREDENTIALS
  • Учетные данные в кодировке base64 представляют собой кодировку base64 OAuth $CLIENT_ID:$CLIENT_SECRET
• Content-Type : Firebase PNV установит application/x-www-form-urlencoded
• Accept : Firebase PNV установит application/json

Поля запроса Firebase PNV

• 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 — ответ от сервера авторизации оператора связи

Заголовки ответа оператора связи

• Content-Type : Firebase PNV ожидает, что тип ответа соответствует заголовку 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 — POST-запрос в ECS

Сервер проверки Google извлекает номер телефона с помощью операции GetPhoneNumber .

• Пример : TS.43 v12.0 - Раздел 6.4.7 - «Пример запроса GetPhoneNumber»

Заголовки запросов Firebase PNV

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

Поля запроса Firebase PNV

• requestor_id : идентифицирует службу, вызывающую операцию GetPhoneNumber TS.43.
  • UUID проверки номера телефона Firebase : 191fd7cc-f7cd-4bb4-a5d2-455ae1fb9a19
• temporary_token : временный токен из AcquireTempToken
• access_token : токен OAuth для аутентификации Google у оператора связи
• terminal_vendor/model/sw_version : Firebase PNV будет заполнять эти поля произвольными значениями.
• entitlement_version : Google настроит версию прав, отправляемую операторам, на основе того, что запросит оператор.
  • Обычно entitlement_version — 10.0 или 12.0.
• app : Firebase PNV установит ap2014
• app_name : Firebase PNV установит firebase для всех запросов Firebase PNV
  • Примечание : AcquireTempToken будет иметь имя app_name Google-OGI , независимо от того, какой агрегатор используется.
• operation : Firebase PNV установит GetPhoneNumber

GetPhoneNumber — ответ от ECS

Пример : TS.43 v12.0 - Раздел 6.6.7 - «Пример ответа GetPhoneNumber»

Заголовки ответа оператора связи

• Content-Type : Firebase PNV ожидает, что тип ответа соответствует заголовку Accept запроса.
  • т.е. application/json

Поля ответа оператора связи

• ap2014.MSISDN : Firebase PNV ожидает, что номер телефона будет возвращен в формате E164.
  • JSON чувствителен к регистру, поэтому MSISDN должен быть написан заглавными буквами.

Коды ошибок TemporaryToken

Ссылки из TS.43 v12.0 , раздел 2.8.6.

В следующей таблице приведены ответы об ошибках, которые ECS, как ожидается, вернет на сервер проверки Google для запросов GetPhoneNumber:

Вариант 2 - КАМАРА

Конечные точки : получение токена доступа CAMARA и получение номера телефона могут осуществляться с разных серверов/конечных точек. Эти конечные точки также могут отличаться от конечной точки EAP-AKA/AcquireTempToken.

OAuth — получение токена доступа CAMARA

Google будет поддерживать только поток носителей JWT CAMARA, но не поток CIBA.

Токен доступа CAMARA — запрос POST оператору связи

Google создаст JWT со следующими полями.

• iss : Эмитент JWT (он же идентификатор клиента)
  • т. е. firebase (фактическая интеграция Firebase PNV) или 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"
}

Firebase PNV подпишет JWT, используя свой закрытый ключ, а оператор связи сможет проверить JWT, используя соответствующий открытый ключ. Firebase PNV предоставит открытый ключ через конечную точку JWKS. Операторам связи следует регулярно опрашивать эту конечную точку JWKS на предмет открытого ключа (например, один раз в день), поскольку Firebase PNV регулярно обновляет открытые ключи (например, один раз в 30 дней).

Заголовки запросов Firebase PNV

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

Поля запроса Firebase PNV

• grant_type : urn:ietf:params:oauth:grant-type:jwt-bearer
• assertion : JWT, созданный выше и подписанный закрытым ключом Firebase PNV
  • Примечательно, что этот 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 : Firebase PNV ожидает, что тип ответа соответствует заголовку 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"
}

API проверки номеров CAMARA v2

Затем Google обменяет этот токен доступа CAMARA, отправив запрос GET на конечную точку оператора /device-phone-number .

Проверка номера CAMARA — запрос GET оператору связи

Заголовки запросов Firebase PNV

• 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 — ответ от оператора

Заголовки ответа оператора связи

• Content-Type : Firebase PNV ожидает, что тип ответа соответствует заголовку Accept запроса.
  • т.е. application/json

Поля ответа оператора связи

• devicePhoneNumber : возвращает номер телефона в формате E164.

200 OK
Content-Type: application/json

{
 "devicePhoneNumber": $PHONE_NUMBER
}