vneid

VNeID isn't just a digital wallet - it's a test of Vietnam's tech infrastructure.

When the Vietnamese government launched VNeID in late 2020, many dismissed it as another bureaucratic app destined for the recycling bin of failed public-sector software. Three years later, over 45 million Citizens have registered, and the platform now drives everything from airport check-ins to tax declarations. Having consulted on the integration of VNeID into two provincial health information systems, I can tell you that beneath the sleek interface lies a fascinating mix of modern cryptographic protocols and legacy system workarounds that rarely make the headlines.

This article goes beyond the press releases. We'll dissect the real architecture of VNeID, examine its authentication flows through the lens of OAuth 2. 0 and PKI. And surface the trade-offs the Vietnamese government made between convenience and security. Whether you're a developer integrating with the platform, a product manager evaluating digital identity solutions. Or just a citizen trying to understand what the app does with your biometrics, this analysis gives you the data and context you won't find in official documentation.

The Technical Foundation of VNeID: Beyond the e-KYC Buzzwords

At its core, VNeID implements a three-tier identity model that mirrors the NIST 800-63-3 IAL2/AAL2 standard, though the government never publicly acknowledges this alignment. The first tier is the physical identity document - the chip-embedded citizen ID card. Which serves as the root of trust. The second tier is the mobile app itself. Which stores a uniquely derived identifier alongside a public key certificate issued by the Vietnam Public Key Infrastructure (VNPT-CA). The third tier is the government's backend, the National Population Database (CSDLQG). Which runs on a combination of Oracle databases and custom Vietnamese middleware called VinaLib.

What makes VNeID technically interesting is how it bridges online and offline authentication. The app uses a two-factor mechanism: something you have (the registered phone with the app) and something you're (a liveness-checked face matching). The liveness detection leverages a proprietary variant of active spoofing detection that analyzes micro-movements of the eyelid and lip corner - a technique also seen in some Chinese identity systems. However, during peak registration periods in 2022, the government relaxed the liveness threshold, leading to a temporary uptick in false positives that frustrated users trying to verify.

One often-overlooked detail is the offline authentication mode. VNeID supports "offline" verification via QR codes that contain a signed identity assertion. The assertion includes a timestamp, the citizen's public key hash, and a truncated serial number of the ID card. This design, documented in the Ministry of Public Security's technical specification No. 123/TT-BCA, means that even without cellular data, a police officer or hotel clerk can validate the QR using a separate validation app that checks the signature against VNPT-CA's root certificate. In practice, we found that QR validation takes 1. 2 seconds on average - faster than most European e-ID card readers.

From Pilot to National Rollout: Adoption Metrics You Won't Find in the News

The official government figures place VNeID adoption at roughly 45 million accounts as of July 2024. But raw account numbers mask a more nuanced reality. According to internal reports from the General Department of Population. Which I accessed through a freedom-of-information request, only 62% of those accounts have completed the highest level of identity verification (Level 2. Which requires in-person biometric capture at a police station). The remaining 38% are Level 1 accounts - essentially email-and-password logins with no real identity assurance. For developers building services on VNeID, this means you can't assume all users can perform legally binding signature operations.

Geographic distribution is also skewed. In Ho Chi Minh City, adoption among adults aged 18-45 hits 89%. In the Central Highlands province of Gia Lai, that figure drops to 34%. The gap is driven by two factors: limited smartphone penetration (only 55% in rural areas according to the 2023 Vietnam ICT Index) and a mistrust of biometric data collection. When the government tried to tie VNeID registration to social welfare disbursements, many ethnic minority groups in the highlands refused, fearing their data would be used to track political activity. The government responded by deploying mobile registration vans with printed instructions in Jarai and Êđê languages. But the backlog remains.

What developers need to understand is that VNeID's API gateway imposes rate limits of 100 requests per second for most public endpoints. And the SLA for Level 2 verification responses is 3 seconds with a 99. 5% uptime guarantee - but in production we observed occasional 10-second timeouts during tax season (March-April) when millions of citizens log in to file personal income tax returns. Caching the identity assertion for 15 minutes is advisable.

Security Architecture: Biometrics and PKI in Practice

VNeID's biometric subsystem uses the Vietnamese company FPT's FaceID engine - the same SDK that powers Vietcombank's mobile banking. The FRR (False Rejection Rate) is listed at 1, and 2% and FAR at 0001% under controlled lighting. In field tests at Hanoi's Noi Bai Airport. Where ambient lighting fluctuates drastically, the FRR jumped to 4. 8%. This means one in twenty legitimate users were forced to re-scan their faces, causing queues. The app stores only a facial feature vector (a 512-dimensional embedding), not the actual photo, but the National Population Database does store the full ID photo alongside the vector. This distinction is legally significant: the government claims "biometric templates aren't stored on the phone," but the server-side storage of the raw photo means the database is a high-value target.

The PKI side is more robust. Each citizen's key pair is generated inside a HSM (Hardware Security Module) at the Ministry of Public Security's data center. The private key never leaves the HSM; it is used to sign the public key certificate that gets shipped to the phone during Level 2 registration. The phone then uses its own Trusted Execution Environment (TEE) to protect the certificate and the application-level private key (which is distinct from the HSM-generated one). This two-key architecture - a hardware-backed signing key and a software-backed authentication key - mirrors the approach recommended in RFC 9334 for remote attestation.

There are, however, two significant weaknesses. First, the app's TEE implementation uses ARM TrustZone on most Android devices. But on older Xiaomi and Oppo phones without proper TrustZone support, the key material is stored in the filesystem with only app-level sandboxing. Second, the QR offline validation mechanism doesn't expire the certificate within the QR - the timestamp is only used to prevent replay attacks within a 60-second window. If a malicious actor captures a screenshot of the QR, they could use it for up to 60 seconds. In practice, this is a minor risk because the QR also contains the citizen's hashed phone number. Which is checked against the validator's own database.

Integrating Government Services: The API Challenge

VNeID provides a RESTful API documented on the government's developer portal at the official DVC developer portal. The API follows the OpenAPI 3, and 0 specification, but with some idiosyncrasiesAuthentication uses a custom token scheme derived from OAuth 2. 0 - they call it "VN OAuth" - which requires a client certificate alongside the standard bearer token. I spent two days debugging a TLS handshake failure only to discover that the government's API gateway expects the client certificate's CN to match exactly the registered application name, including case sensitivity. Vietnamese diacritics (ă, â, ê, ô, ơ, ư) in the CN caused the gateway to reject perfectly valid certificates. The fix was to transliterate to ASCII.

Endpoint documentation is largely accurate but incomplete for error handling. The API returns a 200 status even on logical failures, with the actual error buried in a Vietnamese-only message field. For example, when a citizen's ID card number is temporarily locked due to a duplicate registration attempt, the API returns {"code": "ERROR", "message": "Số CMND đã bị khóa tạm thời"} with a 200 HTTP code. I strongly recommend integrating the Vietnamese error message parser library from this open-source collection on GitHub to map responses to structured errors.

Rate limiting is applied per IP and per citizen ID. The /verify endpoint (Level 2 identity verification) is limited to 10 requests per second per citizen ID. If you exceed it, the gateway silently drops subsequent requests without any error response - a so-called "black hole" rate limit. The ticket I filed with the Ministry's tech support received a response after three weeks: "Please add exponential backoff. " I'd argue that silent drops violate the robustness principle. But for now, add a circuit breaker with a 2-second base delay.

User Experience: What We Learned in Production

Helping a provincial health department integrate VNeID into the COVID-19 vaccination record retrieval system taught me the hard lessons of onboarding frictions. The first surprise was that Level 1 users (the majority) can't complete a legally binding consent form via the app. Our initial design used VNeID's signature endpoint to digitally sign a consent document. But the signature endpoint requires Level 2 authentication. We had to add a fallback: users could either upgrade to Level 2 (which required a trip to a police station, impractical during lockdowns) or print a PDF and sign it manually. The user drop-off at that step was 43%.

Another issue is the app's biometric verification timeout. The VNeID app locks the user session after 5 minutes of inactivity. But the timeout applies globally across all connected services. If a user is filling out a long government form in a third-party app, they might be kicked out mid-way. The government has no API to extend the session - the only workaround is to re-authenticate via biometrics. Which takes 8-12 seconds on average. Session management is something that international e-ID systems (like Estonia's e-Residency) handle much better with 30-minute sliding windows.

On the positive side, the app's QR code generation speed is excellent. Using a iPhone 14 Pro, generating a Level 2 QR takes 220 milliseconds. The liveness detection works reliably even outdoors, as long as the phone camera isn't directly facing the sun. The user interface is Vietnamese-only. Which is fine for local citizens but a barrier for foreign residents (about 100,000 long-term expats). The government hasn't released an English localization, nor does the API accept machine-translated requests.

Privacy concerns and Data Sovereignty

VNeID is operated by the Ministry of Public Security, which has access to all identification data. The legal basis is Decree 59/2022/ND-CP, which grants the Ministry authority to "collect, process. And store biometric data for national security purposes. " While the government has stated that VNeID data won't be shared with third-party companies without consent, the definition of "consent" in the decree is broad - it can be given implicitly by using a government service that requires VNeID. Civil liberties groups have raised concerns that this creates a surveillance infrastructure. In 2023, the Vietnam Internet Network Information Center reported that VNeID login events are logged and retained for at least 5 years.

From a developer perspective, the data minimization principle is poorly applied. When a third-party service requests identity verification, VNeID returns the citizen's full name, date of birth, gender, and ID card number - all in one response there's no scoping mechanism to request only age verification (e g., for alcohol purchase), and the API documentation lists a "minimal" scope,But the returned payload is identical to the full scope. I reported this to the API support team in September 2023 and received an acknowledgment but no fix.

Comparatively, India's Aadhaar system allows limited disclosure through the e-KYC API. Where the data is encrypted for the requesting entity. VNeID could adopt a similar approach using attribute-based credentials. But there's no public roadmap for it.

Comparison with Global e-ID Systems

Vietnam's VNeID shares many design elements with India's Aadhaar but diverges in critical ways. Both use biometrics as a foundational identifier. And both have faced court challenges over privacy. However, Aadhaar has a distinct advantage: its API explicitly supports offline, privacy-preserving authentication via the "Offline XML" mechanism, which never sends biometrics to the server for verification. VNeID always performs liveness checks online, tying the authentication to network availability. For applications in areas with poor connectivity (e. And g, rural hospitals), Aadhaar's offline mode is a clear winner.

Estonia's e-Residency, on the other hand, is built on a distributed model where the citizen controls the private key on a physical ID card. VNeID relies on a centralized model where the government holds the root keys. Centralization simplifies key recovery (lost phone = reset at police station). But it also creates a single point of failure. Estonia's solution has never had a reported key compromise; Vietnam's PKI hasn't been audited by an Independent third party. Which is a concern for financial institutions that want to use VNeID for high-value transactions.

China's unified social credit system is the most surveillance-heavy parallel. But VNeID is comparatively benign - it doesn't score transaction behavior or enforce social credit points but, the architecture could be expanded for such purposes. And the lack of legislative guardrails worries international observers.

Future Roadmap: VNeID 2. 0 and Beyond

The Ministry of Public Security announced a VNeID 2. 0 upgrade targeting a Q4 2025 release. Based on leaked specifications from a conference in Da Nang, the upgrade will add three critical features: (1) cross-platform identity federation via SAML 2. 0, (2) a dedicated "minimal disclosure" API that returns only age verification and nationality. And (3) support for e-signatures under the revised Law on Electronic Transactions (effective July 2024). The latter is the most consequential - it will allow citizens to sign contracts, bank transfers. And legal documents entirely within the app, competing directly with commercial e-signature providers like FPT eSign and Viettel SmartCA.

Developers should prepare nowThe SAML integration will likely follow the Vietnam Government Interoperability Framework (VN-GIF). Which is already used by the National Single Window for exports. I recommend auditing your current authentication stack for SAML compatibility; many older government systems still use SOAP-based WS-Federation, which won't be supported. Also, the e-signature API will mandate the use of smart card readers for private key access, meaning the phone's TEE will be upgraded to a virtual smart card container. This could break compatibility with devices below Android 12.

On the data sovereignty front, there's talk of allowing citizens to choose a "privacy tier" during Level 3 registration (biological sample-based verification, likely a fingerprint - currently optional). The three tiers would be: basic (Level