Panduan Aktivasi Operator Teknis FPNV

Tanggal Terakhir Diubah: 10 September 2025

Ringkasan

Dokumen ini mencakup semua langkah wajib untuk mengaktifkan operator di Verifikasi Nomor Telepon Firebase (FPNV) melalui verifikasi nomor telepon TS.43.

Terminologi

Pihak yang Terlibat

• CSP: Penyedia Layanan Komunikasi
  • mis. Operator seluler
• Agregator
  • Agregator yang Berinteraksi dengan Aplikasi: Agregator yang memungkinkan aplikasi melakukan verifikasi tanpa aplikasi berinteraksi langsung dengan operator
  • misalnya, Verifikasi Nomor Telepon Firebase
  • Meta-Agregator: Agregator yang mendukung operator untuk mengaktifkan agregator yang menghadap aplikasi
    • Meta-agregator dapat bertanggung jawab untuk menyiapkan server hak untuk operator dan/atau mengonfigurasi detail server hak dengan agregator yang menghadap aplikasi
• FPNV: Firebase Phone Number Verification
• TAM Google: Manajer Akun Teknis Google, yang membantu mengaktifkan operator di FPNV
• Telefoni Android: Menawarkan API nomor telepon di Android, termasuk platform bagi operator dan agregator untuk memberikan verifikasi TS.43
• GSMA: Asosiasi operator jaringan seluler yang menentukan spesifikasi, termasuk TS.43
• CAMARA: Project open source Linux yang menentukan API operator dalam kolaborasi dengan GSMA

Persyaratan Verifikasi

• PNV: Verifikasi Nomor Telepon
• TS.43: Menentukan protokol bagi klien dan server seluler untuk berkomunikasi dengan operator menggunakan HTTP
• EAP-AKA: Metode autentikasi yang ditentukan dalam https://www.rfc-editor.org/rfc/rfc4187, yang tidak memerlukan interaksi dengan pengguna
• ECS: Entitlement Configuration Server
  • Titik entri bagi agregator untuk berkomunikasi dengan operator
• ODSA: Aktivasi Layanan di Perangkat
  • Merujuk pada berbagai operasi yang disediakan oleh ECS untuk mengaktifkan layanan di perangkat
  • misalnya AcquireTemporaryToken; GetPhoneNumber

Server Pemberian Hak Operator dan Endpoint PNV

Membuat Endpoint yang Diperlukan

ACTION1: Operator menerapkan endpoint berikut, yang semuanya dapat diakses melalui Internet. Lihat Lampiran A untuk mengetahui detail selengkapnya tentang penerapannya.

Persyaratan Teknis

Performa Umum: Waktu beroperasi semua endpoint harus minimal 99,99%.

Keamanan: Untuk alasan keamanan, endpoint operator harus memenuhi persyaratan berikut:

• Token Autentikasi EAP-AKA: Harus berakhir dalam waktu 1 jam
• Token Sementara: Penggunaan tunggal dengan masa berlaku 5 menit
• Opsi 1 - Vanilla TS.43
  • Token OAuth: Harus berakhir dalam waktu 1 jam
• Opsi 2 - CAMARA
  • Token Akses CAMARA: Penggunaan tunggal dengan masa berlaku 5 menit

Kualitas Data API: 100% konten respons yang berhasil (yaitu MSISDN harus akurat).

FPNV mendukung dua jenis TS.43. Perbedaan utamanya adalah cara server FPNV akan menukar TempToken dengan operator.

• Vanilla TS.43: Merujuk pada penerapan sebagaimana ditentukan oleh spesifikasi TS.43
• CAMARA: Mengacu pada implementasi sebagaimana ditentukan oleh alur token JWT CAMARA

Opsi 1 - Penerapan TS.43 Vanilla

Permintaan dari Perangkat Android

1. Endpoint EAP-AKA: Menampilkan token auth
2. Endpoint AcquireTemporaryToken: Mengingat token auth, kembalikan TempToken

Permintaan dari Server FPNV

1. Endpoint OAuth 2.0 - Alur ID/Rahasia Klien OAuth: Mengingat ID/rahasia klien OAuth, menampilkan token akses OAuth
2. GetPhoneNumber Endpoint: Mengingat token akses OAuth dan TempToken, mengembalikan nomor telepon yang sesuai

Opsi 2 - Penerapan CAMARA

Penerapan CAMARA serupa dengan penerapan TS.43 standar, kecuali untuk endpoint yang menangani permintaan dari server FPNV.

Permintaan dari Perangkat Android

1. Endpoint EAP-AKA: Menampilkan token auth
2. Endpoint AcquireTemporaryToken: Mengingat token auth, menampilkan TempToken

Permintaan dari Server FPNV

1. Endpoint OAuth 2.0 - Alur Pembawa JWT: Mengingat JWT yang berisi TempToken, menampilkan token akses CAMARA
2. Endpoint NumberVerification v2 CAMARA: Mengingat token akses CAMARA, menampilkan nomor telepon yang sesuai

Mengaktifkan Telepon Android & FPNV

Aplikasi Pengujian Operator

TINDAKAN2: Operator menghubungi Manajer Akun Teknis (TAM) Google dan TAM akan membagikan aplikasi pengujian operator FPNV kepada operator. Aplikasi pengujian operator ini meniru permintaan yang akan dikirim oleh FPNV, tanpa melibatkan server FPNV. Aplikasi pengujian operator ini berguna bagi operator untuk memvalidasi bahwa endpoint mereka berfungsi dengan baik.

TINDAKAN3: Operator memverifikasi bahwa endpoint di atas berfungsi secara menyeluruh dengan menggunakan aplikasi pengujian operator FPNV.

Menyiapkan Konfigurasi Produksi yang Diperlukan

Konfigurasi Android - EAP-AKA / AcquireTempToken

ACTION4: Operator menentukan konfigurasi produksi untuk permintaan EAP-AKA/AcquireTempToken dari Teleponi Android

• Config:
  • ID Jasa Kurir Kanonis Android untuk ekspedisi ini
  • Nilai TS.43 use_cases: use_case=GetPhoneNumber
  • URL server hak produksi untuk EAP-AKA/AcquireTempToken
  • SAN dan sidik jari sertifikat x509 produksi Firebase
  • SAN: fpnv.googleapis.com
  • Sidik Jari: aad068c93399a22fc2b11ab58468e8cb72b8f9fc53700991799a8b764c589c7e

Konfigurasi Firebase - Menukarkan TempToken dengan Telepon

ACTION5: Kredensial Firebase untuk mengambil token OAuth dari operator

• Vanilla TS.43
  • Operator membuat client ID dan rahasia klien OAuth untuk permintaan FPNV. Operator kemudian mengonfigurasi endpoint OAuth-nya untuk menampilkan token akses bagi kredensial ini
• CAMARA
  • TAM Google menyediakan kunci publik Google, sehingga endpoint OAuth operator dapat memverifikasi bahwa JWT ditandatangani oleh Google

ACTION6: Operator menentukan konfigurasi produksi untuk server FPNV guna menukar TempToken untuk ponsel

• ID Operator Kanonis Android MNO ini
• Vanilla TS.43
  • OAuth - Alur ID/Rahasia Klien
  • URL endpoint OAuth
  • ID/rahasia klien OAuth
  • Cakupan OAuth (jika ada)
  • GetPhoneNumber
  • URL endpoint GetPhoneNumber
• CAMARA
  • OAuth - Alur Bearer JWT
  • URL endpoint OAuth
  • NumberVerification API v2
  • URL endpoint NumberVerification

Membagikan Kredensial/Konfigurasi

Verifikasi Nomor Telepon Firebase

TINDAKAN7: Operator membagikan konfigurasi produksi dari TINDAKAN4 dan TINDAKAN6 kepada Technical Account Manager Google.

• [PENTING] Rahasia OAuth harus dibagikan menggunakan mekanisme di luar jalur (tidak melalui email, tidak melalui dokumen, dll.) yang aman dengan Google. Mekanisme di luar band ini akan disepakati oleh operator dan TAM Google.

ACTION8: TAM Google memvalidasi bahwa konfigurasi berfungsi secara menyeluruh menggunakan aplikasi pengujian operator. Setelah itu, TAM Google akan menyimpan kredensial OAuth di penyimpanan aman Google dan memperbarui konfigurasi FPNV untuk menukar TempToken dengan ponsel (yaitu konfigurasi ACTION6).

Telepon Android

TINDAKAN9: Operator mengikuti dokumen "Google Open Gateway CSP Onboarding" (yang akan dibagikan oleh TAM Google kepada operator). Operator atau TAM Google mereka mengajukan tiket Buganizer untuk mengaktifkan konfigurasi Teleponi Android: https://issuetracker.google.com/issues/new?component=1861595&template=2168610. Bug ini akan mengambil konfigurasi produksi dari ACTION4.

Jika meta-agregator menyiapkan integrasi FPNV atas nama operator, maka pernyataan izin (email, PDF, surat, dll.) dari pimpinan operator (tingkat Direktur ke atas) harus mengonfirmasi hubungan bisnis mereka dengan operator tersebut. Setelah itu, meta-agregator dapat memberikan konfigurasi operator atas nama operator ke Teleponi Android.

Lampiran A. Penerapan Mendetail

Kepekaan Huruf Besar/Kecil

• Header HTTP tidak peka huruf besar/kecil
• Namun, format XML dan JSON peka huruf besar/kecil. Jadi, untuk kolom permintaan/respons, pastikan kolom tersebut sama persis dengan dokumentasi ini.

Langkah 1 - EAP-AKA / AcquireTempToken

Endpoints: EAP-AKA dan AcquireTempToken harus menggunakan endpoint ECS yang sama.

Tantangan EAP-AKA

Referensi: TS.43 v12.0 - Bagian 2.8.1 - "Embedded EAP-AKA Authentication by Entitlement Configuration Server".

Langkah 1 EAP-AKA - Tantangan Autentikasi

EAP-AKA #1 - GET Request to ECS

Modul Telephony Android mengirimkan permintaan EAP-AKA TS.43 ke server hak operator.

Header Permintaan Android

• Accept: application/vnd.gsma.eap-relay.v1.0+json
  • Formatnya adalah JSON khusus untuk GSMA, bukan hanya application/json

Kolom Permintaan Android

• eap_id: Lihat RCC.14 Lampiran C
  • yaitu 0<IMSI>@<realm>.mnc<MNC>.mcc<MCC>.3gppnetwork.org
• GID1: Hanya ditentukan jika versi hak adalah 12.0
• app_name: AppName yang dienkode akan memiliki nilai hash MD5 dari kasus penggunaan yang melakukan verifikasi telepon:
  • Semua permintaan agregator yang ditujukan untuk aplikasi akan memiliki nama aplikasi Google-OGI
• app: ID aplikasi ap2014 merepresentasikan Informasi Nomor Telepon
• terminal_vendor/model/sw_version: Ditetapkan ke nilai arbitrer; Android tidak akan menjamin bahwa kolom ini berisi info perangkat yang sebenarnya
• vers: Versi konfigurasi; misalnya 0 atau 1
• entitlement_version: Google akan mengonfigurasi versi hak yang dikirim ke operator berdasarkan permintaan operator
  • Biasanya, entitlement_version adalah 10.0 atau 12.0

EAP-AKA #1 - Respons dari ECS

Header Respons ECS

• Content-Type: Android mengharapkan jenis respons cocok dengan header Accept permintaan
  • yaitu application/vnd.gsma.eap-relay.v1.0+json

Kolom Respons ECS

• eap-relay-packet: Berisi paket EAP yang mengikuti RCC.14 - Bagian C.2

EAP-AKA Langkah 2 - Mendapatkan Token Auth

EAP-AKA #2 - Permintaan POST ke ECS

Modul Telephony Android kemudian akan mengirim kembali eap-relay-packet yang diterima ke endpoint yang sama.

Header Permintaan Android

• Accept: Android akan menyetel dua header Accept:
  • application/vnd.gsma.eap-relay.v1.0+json: Merujuk pada operator yang mengembalikan JSON lagi jika perangkat perlu mengirim permintaan EAP-AKA lain lagi
  • text/vnd.wap.connectivity-xml: Merujuk pada format sebenarnya yang diharapkan Android agar operator menampilkan token autentikasi EAP-AKA
• Content-Type: application/vnd.gsma.eap-relay.v1.0+json

Kolom Permintaan Android

• eap-relay-packet: Berisi eap-relay-packet respons EAP-AKA sebelumnya, tetapi dalam format EAP-Response/AKA-Challenge yang mengikuti RFC 4817 - Bagian 9.2.

EAP-AKA #2 - Response from ECS

Setelah autentikasi EAP-AKA berhasil, operator akan menampilkan kembali token autentikasi.

Header Respons ECS

• Content-Type: Android mengharapkan respons yang cocok dengan header Accept permintaan
  • yaitu Android mengharapkan respons dengan token autentikasi memiliki jenis text/vnd.wap.connectivity-xml
  • Header Accept lainnya, application/vnd.gsma.eap-relay.v1.0+json, adalah jika operator ingin Android melakukan permintaan EAP-AKA lain

Kolom Respons ECS

• TOKEN.token: Berisi token autentikasi
• TOKEN.validity: Jumlah detik validitas respons, setelah perangkat menerima respons
  • Google akan memvalidasi bahwa token otorisasi memenuhi Persyaratan Teknis

AcquireTemporary Token

AcquireTempToken - Permintaan GET ke ECS

Dengan menggunakan token autentikasi yang diterima dari EAP-AKA, klien Android mengambil token sementara dengan memanggil endpoint AcquireTemporaryToken operator. Permintaan

• Contoh: TS.43 v12.0 - Section 6.4.6 - "AcquireTemporaryToken Request Example"
• AcquireTempToken memiliki parameter yang serupa dengan EAP-AKA #1, kecuali:
  • AcquireTempToken juga menentukan IMSI, operation dan operation_targets
  • AcquireTempToken tidak menentukan EAP_ID

Header Permintaan Android

• Accept: Android akan menetapkan text/vnd.wap.connectivity-xml

Kolom Permintaan Android

• terminal_vendor/model/sw_version: Android tidak menjamin bahwa kolom ini berisi info perangkat yang sebenarnya
• operation_targets
  • FPNV: Target operasi adalah GetPhoneNumber

AcquireTempToken - Response from ECS

Contoh: TS.43 v12.0 - Section 6.6.6 - "AcquireTemporaryToken Response Example"

Header Respons ECS

• Content-Type: Android mengharapkan jenis respons cocok dengan header Accept permintaan
  • yaitu text/vnd.wap.connectivity-xml

Kolom Respons ECS

• APPLICATION.TemporaryToken: TemporaryToken yang kemudian dapat ditukar oleh server FPNV dengan nomor telepon
• APPLICATION.TemporaryTokenExpiry: Waktu habis masa berlaku dalam format YYYY-MM-DDThh:mm:ssTZD
  • Google akan memvalidasi bahwa masa berlaku TempToken memenuhi Persyaratan Teknis
• APPLICATION.OperationResult: Lihat TS.43 v12.0 - Bagian 6.5.1
  • Secara khusus, jika operasi sebagai SUCCESS, maka tampilkan 1

Langkah 2 - Tukarkan TempToken dengan Nomor Telepon

Opsi 1 - Vanilla TS.43

Endpoint: Endpoint OAuth dan GetPhoneNumber dapat berupa server/endpoint yang berbeda. Endpoint ini juga dapat berbeda dengan endpoint EAP-AKA/AcquireTempToken.

OAuth

Operator harus mengikuti panduan OAuth ini dan memberikan info OAuth yang diperlukan (Client ID; Client Secret; URL server OAuth) kepada Google

OAuth - Permintaan POST ke Server Autentikasi Operator

Header Permintaan FPNV

• Authorization: FPNV akan menetapkan Basic $BASE64_ENCODED_CREDENTIALS
  • Kredensial berenkode base64 adalah encoding base64 dari OAuth $CLIENT_ID:$CLIENT_SECRET
• Content-Type: FPNV akan menetapkan application/x-www-form-urlencoded
• Accept: FPNV akan menetapkan application/json

Kolom Permintaan 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 - Respons dari Server Autentikasi Operator

Header Respons Operator

• Content-Type: FPNV mengharapkan jenis respons cocok dengan header Accept permintaan
  • yaitu application/json

Kolom Respons Ekspedisi

• access_token: Token akses OAuth
• token_type: bearer
• expires_in: Masa berlaku token akses OAuth dalam detik
  • Google akan memvalidasi bahwa waktu habis masa berlaku token OAuth memenuhi Persyaratan Teknis

200 OK
Content-Type: application/json

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

GetPhoneNumber

GetPhoneNumber - Permintaan POST ke ECS

Server verifikasi Google mengambil nomor telepon menggunakan Operasi GetPhoneNumber.

• Contoh: TS.43 v12.0 - Section 6.4.7 - "GetPhoneNumber Request Example"

Header Permintaan FPNV

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

Kolom Permintaan FPNV

• requestor_id: Mengidentifikasi layanan yang memanggil operasi GetPhoneNumber TS.43
  • UUID Verifikasi Nomor Telepon Firebase: 191fd7cc-f7cd-4bb4-a5d2-455ae1fb9a19
• temporary_token: TemporaryToken dari AcquireTempToken
• access_token: Token OAuth untuk Google agar dapat melakukan autentikasi dengan operator
• terminal_vendor/model/sw_version: FPNV akan mengisi kolom ini dengan nilai arbitrer
• entitlement_version: Google akan mengonfigurasi versi hak yang dikirim ke operator berdasarkan permintaan operator
  • Biasanya, entitlement_version adalah 10.0 atau 12.0
• app: FPNV akan menetapkan ap2014
• app_name: FPNV akan menetapkan firebase untuk semua permintaan FPNV
  • Catatan: AcquireTempToken akan memiliki app_name Google-OGI, terlepas dari agregator yang digunakan
• operation: FPNV akan menetapkan GetPhoneNumber

GetPhoneNumber - Respons dari ECS

Contoh: TS.43 v12.0 - Section 6.6.7 - "GetPhoneNumber Response Example"

Header Respons Operator

• Content-Type: FPNV mengharapkan jenis respons cocok dengan header Accept permintaan
  • yaitu application/json

Kolom Respons Ekspedisi

• ap2014.MSISDN: FPNV mengharapkan nomor telepon ditampilkan dalam format E164
  • JSON peka huruf besar/kecil, jadi MSISDN harus menggunakan huruf kapital

Kode Error TemporaryToken

Referensi dari TS.43 v12.0, bagian 2.8.6.

Tabel berikut menjelaskan respons kegagalan yang diharapkan dikembalikan oleh ECS ke Server Verifikasi Google untuk permintaan GetPhoneNumber:

Opsi 2 - CAMARA

Endpoint: Pengambilan token akses CAMARA dan pengambilan nomor telepon dapat menggunakan server/endpoint yang berbeda satu sama lain. Endpoint ini juga dapat berbeda dengan endpoint EAP-AKA / AcquireTempToken.

OAuth - Retrieve CAMARA Access Token

Google hanya akan mendukung alur pembawa JWT CAMARA dan bukan alur CIBA.

Token Akses CAMARA - Permintaan POST ke Operator

Google akan membuat JWT dengan kolom berikut.

• iss: Penerbit JWT (alias Client ID)
  • yaitu firebase (integrasi FPNV sebenarnya) atau fpnv-carrier-tester-app (aplikasi pengujian operator)
• sub: Subjek JWT
  • yaitu operatortoken:$TEMP_TOKEN
• aud: Audiens; penerima yang dituju JWT
  • URL endpoint token (yaitu URL server otorisasi)
• exp: Waktu habis masa berlaku dalam detik
  • Google akan mengirimkan durasi masa berlaku yang sesuai dengan berapa lama token akses CAMARA harus berlaku (lihat Persyaratan Teknis)
• iat: Dikeluarkan pada waktu dalam detik
• jti: ID unik untuk menghindari serangan replay
  • mis. UUID yang dibuat secara acak
• scope: Tujuan permintaan
  • yaitu 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 akan menandatangani JWT menggunakan kunci pribadinya sendiri dan operator dapat memvalidasi JWT menggunakan kunci publik yang sesuai. FPNV akan memberikan kunci publik menggunakan endpoint JWKS. Operator harus secara rutin melakukan polling endpoint JWKS ini untuk mendapatkan kunci publik (misalnya, sekali per hari), karena FPNV akan merotasi kunci publik pada irama yang teratur (misalnya, sekali setiap 30 hari).

Header Permintaan FPNV

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

Kolom Permintaan FPNV

• grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer
• assertion: JWT yang dibuat di atas dan ditandatangani dengan kunci pribadi FPNV
  • Khususnya, JWT ini berisi 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

Token Akses CAMARA - Respons dari Operator

Header Respons Operator

• Content-Type: FPNV mengharapkan jenis respons cocok dengan header Accept permintaan
  • yaitu application/json

Kolom Respons Ekspedisi

• access_token: Token akses CAMARA, yang nantinya dapat ditukar dengan nomor telepon
• token_type: bearer
• expires_in: Masa berlaku token akses OAuth dalam detik
  • Google akan memvalidasi bahwa waktu habis masa berlaku token OAuth memenuhi Persyaratan Teknis
• scope: Tujuan permintaan
  • yaitu 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"
}

CAMARA NumberVerification API v2

Kemudian, Google akan menukarkan token akses CAMARA tersebut dengan mengirimkan permintaan GET ke endpoint /device-phone-number operator.

CAMARA NumberVerification - Permintaan GET ke Operator

Header Permintaan 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

Header Respons Operator

• Content-Type: FPNV mengharapkan jenis respons cocok dengan header Accept permintaan
  • yaitu application/json

Kolom Respons Ekspedisi

• devicePhoneNumber: Menampilkan nomor telepon dalam format E164

200 OK
Content-Type: application/json

{
 "devicePhoneNumber": $PHONE_NUMBER
}