AWS Rekognition Face Liveness Demo

AWS Rekognition Face Liveness를 활용한 얼굴 생체 인식 데모 애플리케이션입니다. 카메라 앞에 실제 사람이 있는지 확인하고, 사진/영상/마스크를 이용한 스푸핑 공격을 탐지합니다.

주요 기능

• 실시간 Face Liveness 검사
• 스푸핑(사진, 영상, 마스크) 공격 탐지
• 0-100 신뢰도 점수 제공
• 한국어 UI 지원
• BFF(Backend For Frontend) 아키텍처로 보안 강화

---

빠른 시작

1. 의존성 설치

pnpm install

2. 환경 변수 설정

.env.local 파일을 생성하고 AWS 자격 증명을 입력합니다:

cp .env.example .env.local

AWS_ACCESS_KEY_ID=your_access_key_id
AWS_SECRET_ACCESS_KEY=your_secret_access_key
AWS_REGION=ap-northeast-1

3. 개발 서버 실행

pnpm dev

브라우저에서 http://localhost:3000을 열어 확인합니다.

---

AWS 자격 증명 발급 가이드

Face Liveness를 사용하려면 AWS IAM 자격 증명이 필요합니다.

방법 1: IAM 사용자 생성 (권장)

Step 1: AWS 콘솔 로그인

1. AWS Management Console에 로그인합니다.
2. 리전을 아시아 태평양 (도쿄) ap-northeast-1로 설정합니다.

Step 2: IAM 사용자 생성

1. IAM 서비스로 이동합니다.
2. 좌측 메뉴에서 사용자 → 사용자 생성을 클릭합니다.
3. 사용자 이름을 입력합니다 (예: face-liveness-demo).
4. 다음을 클릭합니다.

Step 3: 권한 설정

1. 직접 정책 연결을 선택합니다.
2. 다음 정책들을 검색하여 선택합니다:
   • AmazonRekognitionFullAccess
   • AmazonS3FullAccess (감사 이미지 저장 시 필요)
3. 다음 → 사용자 생성을 클릭합니다.

Step 4: 액세스 키 발급

1. 생성된 사용자를 클릭합니다.
2. 보안 자격 증명 탭으로 이동합니다.
3. 액세스 키 섹션에서 액세스 키 만들기를 클릭합니다.
4. 로컬 코드를 선택하고 다음을 클릭합니다.
5. 액세스 키 만들기를 클릭합니다.
6. Access Key ID와 Secret Access Key를 안전한 곳에 저장합니다.

⚠️ 주의: Secret Access Key는 한 번만 표시됩니다. 반드시 저장해두세요!

방법 2: 기존 사용자에 권한 추가

기존 IAM 사용자가 있다면:

1. IAM → 사용자 → 해당 사용자 선택
2. 권한 추가 → 직접 정책 연결
3. AmazonRekognitionFullAccess 정책 추가
4. 해당 사용자의 액세스 키 사용

---

S3 버킷 설정 (선택사항)

Face Liveness 감사 이미지를 저장하려면 S3 버킷을 설정해야 합니다.

저장되는 이미지

S3 버킷을 설정하면 liveness-audit/ 폴더에 다음 이미지가 자동 저장됩니다:

이미지	설명
referenceImage	Liveness 검증에 사용된 얼굴 대표 이미지
auditImages	검증 과정에서 캡처된 이미지들 (최대 4장)

참고: 현재 데모에서는 이미지 저장만 수행하며, Face Match(얼굴 비교) 기능은 구현되지 않았습니다.

Step 1: S3 버킷 생성

1. S3 콘솔로 이동합니다.
2. 버킷 만들기를 클릭합니다.
3. 버킷 이름을 입력합니다 (예: my-liveness-audit-images).
4. 리전: 아시아 태평양 (도쿄) ap-northeast-1
5. 기본 설정을 유지하고 버킷 만들기를 클릭합니다.

Step 2: CORS 설정

버킷 → 권한 → CORS(Cross-origin 리소스 공유) 편집:

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
    "AllowedOrigins": ["*"],
    "ExposeHeaders": ["ETag"]
  }
]

Step 3: 버킷 정책 설정

버킷 → 권한 → 버킷 정책 편집:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowRekognitionAccess",
      "Effect": "Allow",
      "Principal": {
        "Service": "rekognition.amazonaws.com"
      },
      "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::your-bucket-name/*"
    }
  ]
}

your-bucket-name을 실제 버킷 이름으로 변경하세요.

Step 4: 환경 변수 설정

.env.local 파일에 버킷 이름을 추가합니다:

LIVENESS_S3_BUCKET=your-bucket-name

이 환경 변수가 설정되면 Liveness 세션 생성 시 자동으로 liveness-audit/ 폴더에 이미지가 저장됩니다.

---

환경 변수 설정 방법

로컬 개발 환경

.env.local 파일에 직접 입력:

AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=ap-northeast-1
LIVENESS_S3_BUCKET=                # 선택사항 - 감사 이미지 저장용

Vercel 배포 시

1. Vercel 대시보드 → 프로젝트 → Settings → Environment Variables
2. 다음 변수들을 추가:
   • AWS_ACCESS_KEY_ID
   • AWS_SECRET_ACCESS_KEY
   • AWS_REGION
   • LIVENESS_S3_BUCKET (선택사항)

환경 변수 없이 사용

환경 변수가 없는 경우, 앱 실행 시 모달이 표시되어 브라우저에서 직접 자격 증명을 입력할 수 있습니다. 입력된 자격 증명은 sessionStorage에 저장되며, 브라우저를 닫으면 삭제됩니다.

---

프로젝트 구조

src/
├── app/                    # Next.js App Router
│   ├── api/liveness/       # BFF API 엔드포인트
│   ├── liveness/           # Liveness 검사 페이지
│   └── page.tsx            # 홈페이지
├── components/             # React 컴포넌트
│   ├── credentials/        # 자격 증명 관련
│   ├── liveness/           # Liveness 검사 관련
│   └── ui/                 # 공용 UI
├── hooks/                  # 커스텀 React 훅
├── lib/                    # 라이브러리 (AWS SDK 래퍼)
├── types/                  # TypeScript 타입 정의
└── constants/              # 상수 정의

---

기술 스택

프레임워크 & 언어

기술	버전	설명
Next.js	16.0.6	React 기반 풀스택 프레임워크 (App Router)
React	19.2.0	UI 라이브러리
TypeScript	^5	정적 타입 검사
Tailwind CSS	^4	유틸리티 기반 CSS 프레임워크

AWS 관련 라이브러리

라이브러리	버전	설명
@aws-amplify/ui-react-liveness	^3.4.7	Face Liveness UI 컴포넌트
@aws-amplify/ui-react	^6.13.1	Amplify UI React 컴포넌트
aws-amplify	^6.15.8	AWS Amplify 코어 라이브러리
@aws-sdk/client-rekognition	^3.940.0	AWS Rekognition SDK
@aws-sdk/client-sts	^3.940.0	AWS STS SDK (임시 자격 증명)

유틸리티

라이브러리	버전	설명
Zod	^4.1.13	런타임 스키마 유효성 검사

개발 도구

도구	버전	설명
ESLint	^9	코드 린팅
babel-plugin-react-compiler	1.0.0	React Compiler (실험적)
@tailwindcss/postcss	^4	Tailwind PostCSS 플러그인

---

스크립트

# 개발 서버 실행
pnpm dev

# 프로덕션 빌드
pnpm build

# 프로덕션 서버 실행
pnpm start

# 린트 검사
pnpm lint

---

문제 해결

"카메라에 접근할 수 없습니다" 오류

1. 브라우저에서 카메라 권한을 허용했는지 확인하세요.
2. HTTPS 또는 localhost에서만 카메라에 접근할 수 있습니다.
3. 다른 앱이 카메라를 사용 중인지 확인하세요.

"자격 증명 오류" 발생

1. Access Key ID와 Secret Access Key가 올바른지 확인하세요.
2. IAM 사용자에게 AmazonRekognitionFullAccess 권한이 있는지 확인하세요.
3. 리전이 ap-northeast-1로 설정되어 있는지 확인하세요.

빌드 오류 발생

# node_modules 삭제 후 재설치
rm -rf node_modules pnpm-lock.yaml
pnpm install

---

라이선스

MIT License

---

참고 자료

• AWS Rekognition Face Liveness 문서
• AWS Amplify UI FaceLivenessDetector
• Next.js 문서