Face Recognition API

This Serverless API compares a selfie (sent as base64) with a user’s ID card image stored in Amazon S3 using Amazon Rekognition. The ID card location is fetched from MongoDB using the provided userId.

© 2025

---

How it works

1. Client sends userId and selfieBase64 to the API.
2. Lambda queries MongoDB for the document where userId matches and extracts the ID card S3 location from common fields (e.g., idCardUrl, id_card_url, s3Url, attachemnt, bucket+key, etc.).
3. Rekognition CompareFaces runs with SourceImage from S3 (ID card) and TargetImage as bytes (selfie).
4. Rekognition DetectFaces runs on the selfie to return image quality (brightness, sharpness).
5. API returns similarity and quality scores.

---

Features

• Face comparison (ID card vs selfie) via Rekognition
• Selfie image quality scoring (brightness, sharpness)
• S3 integration for ID card storage
• MongoDB lookup by userId
• CORS enabled

---

API

Single endpoint (function name typically compareFaces):

• Method: POST

• Body:

  {
      "userId": "123456-78-9012",
      "selfieBase64": "<base64-string>"
  }

• Success (200):

  {
      "status": { "statusCode": 200, "message": "Face comparison successful." },
      "fields": { "userId": "123456-78-9012" },
      "scores": {
          "faceMatchSimilarity": 98.75,
          "selfieImageQuality": { "brightness": 87.4, "sharpness": 92.1 }
      }
  }

• Also 200 when no match:

  • "message": "No matching face found."

• Client errors (400):

  • "Missing userId or selfieBase64"
  • "User not found"
  • "ID card S3 location not available" (document missing supported fields)
  • "No face detected in one or both images"

• Auth errors (403):

  • Access denied to Rekognition or S3 (IAM issue)

• Server errors (500):

  • Database not configured
  • AWS client error

---

Prerequisites

1. AWS account and Serverless Framework CLI

2. Node.js & npm

3. Python 3.12+

4. MongoDB with a collection containing documents like:

   {
       "userId": "123456-78-9012",
       "attachemnt": "https://your-bucket.s3.us-east-1.amazonaws.com/path/id.jpg"
   }

   Supported fields for the ID image include:

   • idCardUrl, id_card_url, idCardS3Url, idCardS3ObjectUrl,
   • idCardImageUrl, id_card_image_url,
   • idUrl, id_url, idImageUrl, id_image_url, idPhotoUrl, id_photo_url,
   • imageUrl, image_url, photoUrl, photo_url,
   • attachment, attachement, attachemnt, attachUrl, attachmentUrl,
   • s3Url, s3ObjectUrl,
   • or bucket + key (with optional S3_BUCKET_NAME).

5. AWS S3 bucket for ID images

6. Rekognition permissions for runtime

---

Environment variables (.env)

Create a .env file in the project root:

# MongoDB
MONGODB_URI=mongodb+srv://<user>:<pass>@<cluster>/<db>
DB_NAME=databases
USER_COLLECTION=idcards

# AWS
AWS_REGION=us-east-1
S3_BUCKET_NAME=your-bucket-name  # used for raw keys or bucket+key documents

# Debug (optional)
DEBUG=true

---

Local development

Install Python deps and run a local invoke:

pip install -r requirements.txt
serverless invoke local --function compareFaces --path test_event.json

Example test_event.json body (replace with a real base64 selfie):

{
    "body": "{\"userId\":\"123456-78-9012\",\"selfieBase64\":\"<base64>\"}"
}

PowerShell helper to create base64:

$bytes = [System.IO.File]::ReadAllBytes("C:\\path\\to\\selfie.jpg")
$b64 = [System.Convert]::ToBase64String($bytes)
"{`"body`":`"{\"userId\":\"123456-78-9012\",\"selfieBase64\":\"$b64\"}`"}" | Set-Content test_event.json -Encoding UTF8

---

Deploy

serverless deploy

If you see CloudFormation permission errors when deploying from your machine, temporarily attach AdministratorAccess (fastest for hackathons) to your deploying user, or grant at least CloudFormation, IAM PassRole, Lambda, API Gateway, Logs, and S3 permissions. Runtime (Lambda execution role) must include:

• rekognition:CompareFaces
• rekognition:DetectFaces
• s3:GetObject, s3:GetBucketLocation for your ID image bucket

---

Troubleshooting

• 400 User not found: The userId doesn’t exist in MongoDB.
• 400 ID card S3 location not available: Add one of the supported fields to the document (see list above) or provide bucket+key.
• 403 Access denied: Update IAM to allow Rekognition and S3 read.
• Deploy fails with CloudFormation not authorized: Grant your local deployer permissions (or use a deployment role in serverless.yml).

---

Security notes

• Don’t log base64 selfie data in production.
• Use DEBUG only during development.
• Keep IAM least-privileged in non-hackathon environments.