[Node.js] Gmail SMTP를 활용한 이메일 인증 시스템 구현하기 (앱 비밀번호 설정부터 발송까지)

 

 

회원가입이나 비밀번호 변경 등 웹 서비스 개발 시 이메일 인증 기능은 필수적입니다. 개발 초기 단계나 소규모 프로젝트에서 유료 이메일 솔루션을 사용하기 부담스러울 때, Google(Gmail)의 SMTP 서버를 이용하면 무료로 안정적인 이메일 발송 기능을 구현할 수 있습니다.

 

이번 포스팅에서는 Google 계정 설정부터 Node.js(Nodemailer)를 이용한 실무 코드 작성, 그리고 전체적인 이메일 인증 시스템의 논리 흐름까지 단계별로 정리해 보겠습니다.

---

1. Google 계정 설정 (앱 비밀번호 발급)

Google은 보안 정책상 외부 프로그램에서 Gmail 일반 비밀번호로 SMTP에 접속하는 것을 제한하고 있습니다. 따라서 2단계 인증을 설정한 후, 외부 연동을 위한 앱 비밀번호(App Password)를 따로 발급받아야 합니다.

설정 순서

1. [Google 계정 관리] 페이지로 이동합니다.
2. 왼쪽 메뉴에서 [보안] 탭을 클릭합니다.
3. 'Google에 로그인하는 방법' 섹션에서 [2단계 인증]을 활성화합니다. (이미 활성화되어 있다면 다음 단계로 진행합니다.)
4. 엡 비밀번호 검색후 페이지 이동  [앱 비밀번호] 메뉴를 선택합니다.
5. 앱 이름 입력창에 적절한 명칭(예: My Web Server)을 적고 [만들기]를 클릭합니다.
6. 화면에 생성되는 16자리 임시 비밀번호를 안전한 곳에 복사해 둡니다. (이 창을 닫으면 비밀번호를 다시 확인할 수 없으므로 반드시 메모해 두어야 합니다.)

---

2. SMTP 서버 기본 정보

메일 발송 라이브러리 설정에 필요한 Google SMTP 서버의 명세입니다.

• SMTP 호스트 주소: smtp.gmail.com
• 포트 번호: 587 (STARTTLS 보안 프로토콜을 사용하는 포트입니다.)
• 사용자 이름: 본인의 Gmail 주소 (예: your-email@gmail.com)
• 비밀번호: 위에서 발급받은 16자리 앱 비밀번호 (공백 없이 입력해야 합니다.)

---

3. 백엔드 코드 작성 (Node.js & Nodemailer)

많은 백엔드 환경 중 가장 접근성이 좋은 Node.js와 메일 전송 라이브러리인 Nodemailer를 기준으로 코드를 구현해 보겠습니다.

먼저 필요한 패키지를 설치합니다.

npm install nodemailer dotenv

환경변수 파일 설정 (.env)

중요한 계정 정보와 앱 비밀번호가 소스코드에 그대로 노출되지 않도록 환경변수 파일에 분리하여 저장합니다.

EMAIL_USER=your-email@gmail.com
EMAIL_PASS=abcd efgh ijkl mnop  # 발급받은 16자리 앱 비밀번호

메일 전송 모듈 작성 (mailer.js)

const nodemailer = require('nodemailer');
require('dotenv').config();

// 1. SMTP 설정을 포함한 transporter 객체 생성
const transporter = nodemailer.createTransport({
  service: 'gmail',
  host: 'smtp.gmail.com',
  port: 587,
  secure: false, // 587 포트(STARTTLS)를 사용할 때는 false로 지정합니다.
  auth: {
    user: process.env.EMAIL_USER,
    pass: process.env.EMAIL_PASS
  }
});

/**
 * 사용자에게 인증 코드가 포함된 메일을 발송하는 함수
 * @param {string} toEmail - 수신자 이메일 주소
 * @param {string} authCode - 생성된 6자리 인증 번호
 */
async function sendVerificationEmail(toEmail, authCode) {
  try {
    const mailOptions = {
      from: `"내 서비스 이름" <${process.env.EMAIL_USER}>`,
      to: toEmail,
      subject: '[서비스 이름] 회원가입 인증 코드 안내',
      html: `
        <div style="font-family: Arial, sans-serif; max-width: 500px; margin: 0 auto; padding: 20px; border: 1px solid #ddd; border-radius: 5px;">
          <h2 style="color: #333;">안녕하세요, 서비스 이름입니다.</h2>
          <p>회원가입 절차를 완료하기 위해 아래의 인증 코드를 홈페이지 입력창에 기입해 주세요.</p>
          <div style="background-color: #f9f9f9; padding: 15px; text-align: center; border-radius: 4px; margin: 20px 0;">
            <span style="font-size: 24px; font-weight: bold; color: #4CAF50; letter-spacing: 5px;">${authCode}</span>
          </div>
          <p style="font-size: 12px; color: #666;">본 인증 코드는 발송 후 5분간 유효합니다.</p>
        </div>
      `
    };

    const info = await transporter.sendMail(mailOptions);
    console.log(`이메일 발송 완료: ${info.messageId}`);
    return true;
  } catch (error) {
    console.error('이메일 전송 중 에러 발생:', error);
    return false;
  }
}

module.exports = { sendVerificationEmail };

---

4. 이메일 인증 시스템의 전체 흐름

단순히 이메일을 발송하는 것뿐만 아니라, 실제 서비스에서 이를 어떻게 검증하고 관리해야 하는지 전체 흐름을 이해하는 것이 중요합니다.

[클라이언트]                     [백엔드 서버]                     [메모리 DB (Redis 등)]
    |                                 |                                   |
    |  --- 1. 인증 이메일 요청 --->   |                                   |
    |                                 |  --- 2. 랜덤 6자리 코드 생성 --->  |
    |                                 |  --- 3. 이메일&코드 캐싱(5분) --->|
    |                                 |                                   |
    |                                 |  --- 4. Google SMTP에 전송 요청 -> Gmail 서버
    |                                 |                                   |
    |  <-- 5. 인증코드 메일 수신 ------ |                                   |
    |                                 |                                   |
    |  --- 6. 인증코드 입력 및 제출 -> |                                   |
    |                                 |  --- 7. 저장된 코드와 비교 ------->|
    |  <-- 8. 최종 회원가입 완료 -----  |                                   |

1. 인증 요청: 사용자가 이메일을 입력하고 인증 메일 발송을 요청합니다.
2. 코드 생성 및 보관: 서버는 난수 발생기를 통해 6자리 코드(예: 582931)를 생성하고, 해당 이메일 주소를 Key값으로 하여 코드를 임시 보관합니다. 이때, 유효기간(예: 3~5분) 설정을 위해 Redis와 같은 인메모리 DB를 사용하면 관리가 용이합니다.
3. 이메일 발송: 위에서 정의한 SMTP 발송 로직으로 사용자에게 이메일을 전송합니다.
4. 인증 검증: 사용자가 입력창에 인증 코드를 적어 제출하면, 서버는 보관하고 있던 코드와 일치하는지 비교한 뒤 세션에 '인증 성공' 여부를 등록하거나 다음 회원가입 단계로 통과시킵니다.

---

5. 실무 적용 시 주의할 점 및 한계

Google SMTP는 설정이 직관적이고 무료라는 강력한 장점이 있지만, 실제 프로덕션 환경에서는 다음과 같은 제한 사항이 존재합니다.

• 일일 전송 한도 제한: 개인 Gmail 무료 계정은 하루에 약 500통, 유료 Google Workspace 계정은 약 2,000통의 발송 한도를 가집니다. 사용자가 많아지면 메일이 정상적으로 발송되지 않을 수 있습니다.
• 환경변수 관리 보안: 생성된 16자리 앱 비밀번호는 Gmail 계정에 직접 접근할 수 있는 권한을 가지므로, 소스코드 버전 관리 도구(GitHub 등)에 노출되지 않도록 각별히 유의해야 합니다.
• 프로덕션 이관: 서비스 규모가 커지거나 하루 발송량이 많아질 경우, AWS SES, Mailgun, SendGrid 등 대량 발송 전용 SaaS 솔루션으로 마이그레이션하는 것을 추천합니다.

---

마치며

Google SMTP를 활용하면 초기 서비스 개발 시 비용을 들이지 않고도 신뢰성 높은 이메일 전송 시스템의 프로토타입을 신속하게 만들어낼 수 있습니다. 이메일 전송 로직 자체는 매우 단순하므로, 인증 코드의 유효 기간 처리나 예외 상황(잘못된 이메일 형식 등)에 대한 비즈니스 로직을 탄탄하게 구현하는 것에 초점을 맞춰 보시기 바랍니다.