eID Verification Sample

⚠️ IMPORTANT WARNING ⚠️

This POC (Proof of Concept) MAY NOT ACTUALLY WORK as expected. It is designed primarily to demonstrate the elements of implementation requirements rather than be a fully functional system.

Please consider this project as:

• A reference for code structure and components
• A guide showing implementation hints and approaches
• A demonstration of concepts rather than a working implementation

The focus should be on understanding the architecture, flow, and integration points rather than expecting a fully functional demo.

This is a sample implementation for an eID verification system of a virtual nation. This project can be used as reference code for the eID Verification Bounty Challenge.

Project Structure

eID-verification-sample/
├── client/                      # Demo RP Website
├── verification-server/         # Verification Server
└── mock-eid-api/                # Mock eID API Server

IMPORTANT NOTE: The mock-eid-api is NOT the actual implementation target. It is merely a simulation or mockup of the APIs that would be provided by real eID providers. In a real-world implementation, this would be replaced by actual eID systems provided by identity authorities.

Technology Stack

• TypeScript
• Node.js
• Express
• JWT (JSON Web Token)
• EJS (Client Template Engine)
• QRCode (QR Code Generation)

Implemented User Scenarios

1. Cross-Device Authentication (Starting from Desktop)

   • User accesses the demo website from a desktop
   • Requests a QR code and scans it
   • Completes authentication in the eID app on a mobile device
   • Returns to the original website to view profile information

2. Same-Device Authentication (Starting from Mobile)

   • User accesses the demo website from a mobile device
   • Clicks an authentication link to move to the mobile eID app
   • Completes authentication on the same device
   • Returns to the original website to view profile information

Key Components

1. Demo RP Website (Client)

   • Provides user interface
   • Displays QR codes and authentication links
   • Shows user information after authentication

2. Verification Server

   • Mediates between the eID system and the client
   • Manages sessions and issues tokens
   • Checks authentication status and provides user information

3. Mock eID API Server

   • Simulates a real eID system (this is NOT the implementation target)
   • Handles user authentication and token issuance
   • Provides user information

Installation

1. Clone the repository

git clone https://github.com/yourusername/eID-verification-sample.git
cd eID-verification-sample

2. Install and configure each service

# Install client
cd client
npm install
cd ..

# Install verification server
cd verification-server
npm install
cd ..

# Install mock eID API
cd mock-eid-api
npm install
cd ..

3. Configure environment variables: Each service directory contains a .env file. Modify settings as needed.

Running the Application

Each service must be run in a separate terminal:

1. Run the mock eID API server

cd mock-eid-api
npm start

2. Run the verification server

cd verification-server
npm start

3. Run the client website

cd client
npm start

4. Access the client website in your browser

http://localhost:3000

Testing

The current implementation simulates a virtual eID app. For testing, you can use the following user accounts:

• User ID: user-001
• Name: Hong Gildong
• National ID: 1234567890

Customization

To adapt for real eID systems, modify the following parts:

1. verification-server/src/services/verificationService.ts - Logic for communication with the actual eID API
2. mock-eid-api directory - Replace with the actual eID system
3. Authentication flow and data structures - Adjust to match actual eID requirements

Security Considerations

This demo implementation is provided for educational purposes. For a production environment, the following additional security considerations should be implemented:

1. Use of HTTPS
2. Appropriate token expiration and renewal mechanisms
3. Rate limiting and brute force prevention
4. Proper encryption of sensitive information
5. Secure session management

License

MIT