앱에 2단계 인증을 추가하는 방법

앱에 2단계 인증(2FA)을 추가하려면, 사용자가 QR 코드를 스캔해 인증 앱을 연결하고, 비밀번호 다음에 그 앱이 보여 주는 6자리 코드를 입력하게 하세요. 코드가 맞는 것을 확인한 뒤에야 서버에서 완전한 세션을 만드세요. 사용자가 2FA를 켤 때 일회용 복구 코드를 모두 발급하고, 누군가 코드를 추측할 수 있는 횟수를 제한하며, 2FA를 끄려면 비밀번호와 현재 코드를 모두 요구하세요. 호스팅 인증 제공업체를 쓰고 있다면, 직접 만들지 말고 제공업체의 내장 다중 인증 옵션을 켜세요.

이 가이드는 선택지, 정확한 흐름, AI 빌더에 줄 프롬프트, 그리고 2FA가 있는 것처럼 보이지만 실제로는 아무 기능도 하지 않게 만드는 실수들을 설명합니다. 개념이 낯설다면 먼저 2단계 인증이란을 읽으세요.

시작 전에: 로그인 기능이 먼저 있어야 합니다

2FA는 이미 있는 로그인 위에 얹는 기능입니다. 다음 중 하나가 먼저 필요합니다.

• 직접 운영하는 로그인. 사용자와 해시된 비밀번호를 앱의 데이터베이스에 저장합니다.
• 호스팅 인증 제공업체. 사용자를 대신 관리합니다.

둘 중 아직 없다면 앱에 로그인을 추가하는 방법부터 시작하세요. 나머지 가이드는 비밀번호 단계가 이미 동작한다고 가정합니다.

두 번째 인증 수단 고르기

TOTP는 시간 기반 일회용 비밀번호(time-based one-time password)의 약자로, 인증 앱이 사용하는 표준(RFC 6238)입니다. 서버와 사용자 휴대폰이 비밀 값을 공유하고, 각자 그 비밀과 현재 시각으로 같은 짧은 코드를 만듭니다. 보통 30초마다 바뀝니다. 네트워크 연결이나 SMS 제공업체가 필요 없습니다.

패스키는 사용자 기기에 저장된 암호학적 키로 비밀번호를 대체하거나 보완합니다. 더 강하지만 직접 만들기에는 작업이 더 많습니다. 그래서 많은 앱은 TOTP로 시작하고 나중에 패스키를 추가하거나, 인증 제공업체에서 패스키를 받습니다.

직접 만들까, 켜기만 할까?

제공업체가 어떤 방식을 지원하는지, 어떤 요금제에서 가능한지는 최신 문서에서 확인하세요. 어느 쪽이든 코드 생성 수학을 직접 구현하지 마세요. 널리 쓰이는 라이브러리를 쓰세요.

정책을 먼저 정하기

프롬프트를 쓰기 전에 다음을 정하세요. 설계가 달라지기 때문입니다.

1. 누가 반드시 써야 하나요? 모두에게 선택 사항, 관리자와 직원에게는 필수, 또는 전체 필수. 관리자 권한이 있는 모든 사람에게 필수로 두는 것이 흔합니다. 역할 기반 접근 제어를 참고하세요.
2. 사용자는 얼마나 자주 코드를 다시 입력하나요? 로그인할 때마다, 또는 기기마다 30일 동안 "이 기기 기억하기"를 설정.
3. 어떤 작업에 새로운 확인이 필요하나요? 이메일 변경, 정산 정보 변경, 2FA 끄기가 좋은 후보입니다. 이를 단계별 인증(step-up authentication)이라고 합니다.
4. 휴대폰을 잃어버렸을 때의 절차는 무엇인가요? 복구 코드와, 여러분이 기꺼이 운영할 수 있는 수동 대체 절차입니다.

단계별 진행: 직접 운영하는 로그인에 TOTP 2FA 구현하기

1. 올바른 필드를 저장하기

각 사용자에게 필요한 것은 다음과 같습니다. 2FA 활성화 여부, TOTP 비밀(저장 시 암호화, 평문 금지), 활성화된 시각, 그리고 해시해서 저장한 복구 코드 목록입니다. 비밀번호처럼 해시로 저장하세요. 실패한 시도 횟수를 세는 곳도 두세요.

2. 등록

1. 사용자가 설정을 열고 2단계 인증 켜기를 클릭합니다.
2. 서버가 새 비밀을 만들어 QR 코드로 돌려주고, 스캔할 수 없는 사람을 위해 텍스트 버전도 함께 제공합니다.
3. 사용자가 인증 앱으로 스캔하고 현재 코드를 입력합니다.
4. 서버가 코드를 확인합니다. 코드가 맞을 때에만 비밀을 저장하고 2FA를 활성화합니다.
5. 앱이 복구 코드 8~10개를 한 번만 보여 주고, 사용자에게 저장하라고 요청합니다.

4단계가 중요합니다. 코드를 확인하기 전에 2FA를 켜 버리면, 스캔에 실패한 사람이 다음 로그인 때 잠깁니다.

3. 두 번째 단계가 있는 로그인

1. 사용자가 이메일과 비밀번호를 제출합니다. 서버가 이를 확인합니다.
2. 2FA가 켜져 있다면, 서버는 완전한 세션을 만들지 않습니다. 대신 짧게 유지되는 "두 번째 인증 대기" 상태를 만듭니다.
3. 앱이 코드 입력 화면을 보여 줍니다. 서버가 코드를 확인하며, 시계 오차를 감안해 약간의 여유 시간을 둡니다.
4. 그제야 서버가 실제 세션을 발급합니다.

모든 보호된 라우트와 API 엔드포인트는 대기 상태를 거부해야 합니다. 브라우저에서만 페이지를 숨기는 2FA 화면은 직접 API를 호출하면 우회되므로 보호 기능이 아닙니다.

4. 제한과 알림

6자리 코드는 백만 가지 조합이므로, 제한이 없으면 추측으로 뚫릴 수 있습니다. 시도 횟수를 제한하고, 여러 번 실패하면 일정 시간 두 번째 단계를 잠그고, 사용자에게 이메일로 알리세요. 요청 속도 제한과 앱에서 이메일 보내기를 참고하세요.

5. 복구와 끄기

• 복구 코드는 한 번만 작동하고, 사용하면 삭제됩니다.
• 2FA를 끄려면 비밀번호와 현재 코드 또는 복구 코드가 필요합니다.
• 복구 코드를 다시 생성하면 이전 코드 세트는 무효가 됩니다.
• 2FA를 켜거나 끌 때마다 사용자에게 이메일을 보내세요.

AI 빌더에 줄 프롬프트

핵심 흐름부터 시작하세요.

기존 이메일과 비밀번호 로그인에 인증 앱(TOTP)을 사용하는 선택적 2단계 인증을 추가해 주세요. 잘 알려진 TOTP 라이브러리를 쓰고, 알고리즘을 직접 구현하지 마세요. 설정에서 QR 코드와 텍스트 비밀을 보여 주고, 사용자가 올바른 코드를 입력한 뒤에만 2FA를 켜 주세요. 비밀은 암호화해서 저장하고, 설정 후에는 다시 보여 주지 마세요. 일회용 복구 코드 10개를 한 번만 보여 주고, 해시해서 저장해 주세요.

그다음 강제 적용입니다. 생성된 코드에서 가장 자주 부족한 부분이 여기입니다.

서버에서 2FA를 강제해 주세요. 올바른 비밀번호 입력 후, 2FA가 켜진 사용자는 완전한 세션이 아니라 짧게 유지되는 대기 상태를 받습니다. 보호된 모든 페이지와 API 라우트는 대기 상태를 거부해야 합니다. 코드 시도는 5회로 제한하고, 그 뒤 두 번째 단계를 15분 동안 잠그고 사용자에게 이메일을 보내 주세요.

다음은 정책입니다.

관리자 계정은 2FA를 필수로 해 주세요. 2FA가 없는 관리자는 설정 화면으로 보내고, 설정을 마치기 전까지 대시보드에 접근하지 못하게 해 주세요. 2FA를 끄거나 계정 이메일을 바꾸려면 비밀번호와 현재 코드를 모두 요구해 주세요. 2FA가 켜지거나 꺼질 때 사용자에게 이메일을 보내 주세요.

마지막으로 에이전트에게 무엇을 만들었는지 설명하도록 요청하세요.

완료된 두 번째 인증을 확인하는 모든 라우트를 나열하고, TOTP 비밀과 복구 코드가 어디에 저장되며 어떻게 보호되는지 설명해 주세요.

흔한 실수

• 비밀번호 다음에 세션을 발급함. 가장 심각한 버그입니다. 코드가 확인되기 전에 완전한 세션이 존재하면 2FA는 장식에 불과합니다. 비밀번호 단계 후에만 보호된 API를 호출해 보면 확인할 수 있습니다.
• 시도 횟수 제한 없음. 무제한 추측이 가능하면 코드는 무차별 대입으로 깨집니다.
• 비밀이나 복구 코드를 평문으로 저장함. 데이터베이스가 유출되면 모든 사람의 두 번째 인증 수단이 함께 넘어갑니다.
• 확인하기 전에 활성화함. 스캔을 잘못한 사용자는 다음 로그인 때 잠깁니다.
• 복구 경로가 없음. 휴대폰을 잃을 때마다 고객 지원 문의나 고객 이탈로 이어집니다.
• 쉽게 끌 수 있음. 훔친 세션으로 코드 없이 2FA를 끌 수 있다면 보호 기능은 사라집니다.
• 로그에 코드 남김. 코드와 비밀이 서버 로그나 오류 메시지에 절대 나타나지 않게 하세요.
• 로그인 페이지에서만 확인함. 비밀번호 재설정, "매직 링크" 로그인, 소셜 로그인도 2FA를 지켜야 합니다. 그렇지 않으면 우회로가 됩니다.

테스트 체크리스트

• 올바른 코드를 입력해야만 등록이 완료된다
• 올바른 비밀번호는 맞지만 코드가 없는 로그인은 보호된 페이지나 API에 아무 접근도 허용하지 않는다
• 잘못된 코드는 거부되고, 반복된 잘못된 코드는 잠금과 이메일을 발생시킨다
• 몇 분 전의 코드는 거부된다
• 각 복구 코드는 정확히 한 번만 작동한다
• 2FA를 끄려면 비밀번호와 현재 코드가 필요하다
• 비밀번호 재설정으로 2FA를 우회할 수 없다
• (필수로 설정했다면) 2FA가 없는 관리자는 관리자 페이지에 접근할 수 없다
• 비밀과 복구 코드는 데이터베이스에서 암호화되거나 해시되어 있다
• 로그에 코드나 비밀이 나타나지 않는다

출시 전에는 AI로 만든 앱의 보안 체크리스트 전체도 실행하세요.

Mythex에서 2FA 추가하기

Mythex는 앱의 최종 사용자를 위한 로그인 시스템을 기본 제공하지 않습니다. 그래서 2FA는 선택한 인증 방식의 일부가 됩니다. 프로젝트 데이터베이스를 쓰는 이메일과 비밀번호 로그인을 직접 만들거나, 다중 인증을 지원하는 호스팅 제공업체를 쓰는 방식입니다. 위와 같은 프롬프트로 채팅에 원하는 내용을 설명하세요. 제공업체 키는 메시지 입력창이 아니라 프로젝트 시크릿에 넣으세요(/secrets, 프로젝트 설정, 또는 에이전트가 보여 주는 시크릿 카드를 이용). 문서의 앱에 로그인 추가하기 레시피에 시작용 프롬프트가 있고, 만든 앱의 보안에서는 키와 권한에 관한 습관을 다룹니다. 에이전트 작업이 끝나면 게시하기 전에 미리보기에서 체크리스트의 모든 항목을 테스트하세요.

자주 묻는 질문