e-ID Mongolia

System Architecture

5 Docker containers on a single server with Nginx reverse proxy and Let's Encrypt SSL.

Internet Layer — DNS + SSL

🌐

smartid.mn

Web + API

:443

🔐

keycloak.smartid.mn

Identity Provider

:443

🔍

debug.smartid.mn

Real-time Monitor

:443

Reverse Proxy — Nginx

⚡

Nginx

TLS termination, routing

Let's Encrypt

Application Layer

🚀

Go Backend

BFF API — all business logic

:8081 (chi router)

⚛️

Next.js

Web frontend (SSR)

:3000

🔑

Keycloak 24

OIDC / SSO / Custom SPI

:8080

Data Layer

🐘

PostgreSQL 16

Keycloak DB + Device fingerprints

:5432

⚡

Redis 7

Challenge sessions (TTL 120s)

:6379

Mobile Clients

📱

iOS App

Swift + SwiftUI + Secure Enclave

mn.geid.smartid

🤖

Android App

Kotlin + Compose + StrongBox

mn.geid.smartid

🔔

Firebase FCM

Push Notifications (V1 API)

APNs + GCM

Authentication Flow

Complete passwordless authentication in under 5 seconds.

User enters Registration Number

User visits smartid.mn and enters their national registration number (e.g., МА74101813)

POST /api/auth/init { "personalCode": "МА74101813" }

WEBGO BACKEND

Challenge Created + Push Sent

Go backend creates 6-digit verification code, stores in Redis (120s TTL), sends FCM push notification to registered device.

Redis: challenge:{uuid} → { displayCode: "499745", status: "pending" } FCM → APNs/GCM → Mobile Device

GO BACKENDREDISFIREBASE

Web Shows Code + Polls Status

Web displays the verification code with a circular countdown timer. Polls backend every 2 seconds for status changes.

GET /api/auth/status/{sessionId} → { "status": "pending" }

WEB

Mobile: Verify Code + Enter PIN

Push notification opens challenge screen. User compares 6-digit code, enters 6-digit PIN, confirms with biometric (Face ID / fingerprint).

iOSANDROID

Cryptographic Confirmation

App signs sessionId with device private key (EC P-256, hardware-backed), sends signature + X.509 certificate to backend.

POST /api/auth/confirm { "sessionId": "uuid", "action": "approve", "deviceSignature": "MEQCIG27VasBWu5xcl8y...", // ECDSA-SHA256 "deviceCertificate": "MIIBkTCB+wIU..." // X.509 from Intermediate CA }

DEVICE KEYGO BACKEND

Signature + Certificate Chain Verified

Go backend verifies ECDSA signature with stored public key, validates X.509 certificate chain (Root CA → Intermediate CA → Device Cert). Challenge marked "approved".

[Crypto] Signature VERIFIED for МА74101813 [PKI] Certificate VERIFIED, CN: МА74101813

ECDSA VERIFYX.509 CHAIN

Web Redirects to Dashboard

Polling detects "approved" status. Web redirects to authenticated dashboard. Total time: ~3-5 seconds.

GET /api/auth/status/{sessionId} → { "status": "approved" } → redirect /dashboard

WEB

PKI Certificate Hierarchy

Self-signed Root CA, replaceable with official CA without re-registering devices.

Root CA

e-ID Mongolia Root CA

Self-signed · EC P-256 · Valid 20 years

🔄 Replaceable with official CA (e.g., Монгол ЦГУ)

Intermediate CA

Gerege Systems LLC

Signed by Root CA · Valid 10 years

Re-sign with new Root → all device certs remain valid

Device Certificate

МА74101813 (iPhone)

Secure Enclave key · Valid 2 years

Device Certificate

МА74101813 (Android)

StrongBox/TEE key · Valid 2 years

Security Layers

8 layers of defense-in-depth protection.

Hardware-Backed Keys

EC P-256 private keys in iOS Secure Enclave / Android StrongBox. Cannot be exported even on jailbroken devices.

X.509 Certificate Chain

Root CA → Intermediate CA → Device Certificate. Full PKI with chain verification on every confirmation.

ECDSA Signature

Every confirmation cryptographically signed with device private key. Prevents replay and spoofing attacks.

Visual Verification

6-digit code displayed on both web and mobile. User verifies match — prevents MITM attacks.

PIN + Biometric

6-digit PIN entry + Face ID / Touch ID / Fingerprint. Multi-factor: possession + knowledge + inherence.

Time-Limited Challenges

120-second TTL on challenges. Auto-expire in Redis. Single-use — consumed after verification.

Device Fingerprint

SHA-256 composite hash of hardware identifiers. Unique per device, survives factory reset.

TLS + HSTS

TLS 1.2/1.3 everywhere. HSTS with includeSubDomains. All traffic encrypted end-to-end.

Technology Stack

Modern, production-ready technologies chosen for security and performance.

🚀

Go 1.25

BFF API server (chi router, ECDSA, X.509)

⚛️

Next.js 16

Web frontend (SSR, Tailwind, Stitch design)

🔑

Keycloak 24

Identity provider (OIDC, SSO, Custom SPI)

🐘

PostgreSQL 16

Identity + device fingerprint storage

⚡

Redis 7

Challenge sessions with TTL

🔔

Firebase FCM v1

Push notifications (APNs + GCM)

📱

Swift + SwiftUI

iOS app (Secure Enclave, CryptoKit)

🤖

Kotlin + Compose

Android app (Keystore, StrongBox)

🐳

Docker Compose

5-container deployment

🔒

Let's Encrypt

Auto-renewing SSL certificates

🛡️

Nginx

Reverse proxy, TLS termination

🇲🇳

MN / EN i18n

Bilingual interface

API Endpoints

All endpoints served by Go backend at smartid.mn/api/

Method	Endpoint	Description
POST	/api/auth/init	Create challenge + send push notification
GET	/api/auth/status/{sessionId}	Poll challenge status (pending/approved/rejected)
POST	/api/auth/confirm	Approve/reject with signature + certificate
POST	/api/auth/keycloak-verify	Keycloak SPI internal verification
GET	/api/auth/ca	Root + Intermediate CA certificates
POST	/api/device/register	Register device + issue X.509 certificate
PUT	/api/device/token	Update FCM push token
POST	/api/device/fingerprint	Save device fingerprint to PostgreSQL
GET	/api/dashboard/stats	User count, device count, sessions
GET	/api/dashboard/devices	Registered device fingerprints
GET	/api/dashboard/events	Keycloak login/logout events

System Architecture

Authentication Flow

PKI Certificate Hierarchy

Security Layers

Technology Stack

API Endpoints

Live URLs