Skip to main contentSkip to navigation
블로그로 돌아가기
튜토리얼

JWT 통합 튜토리얼: 앱에 토큰 인증 추가하기

이메일/비밀번호 앱에서의 JWT 수명 주기를 다루는 단계별 튜토리얼: 가입, 로그인, 토큰 저장, 서버 측 검증, 2FA, 로그아웃, 그리고 jwt.io로 토큰 디버깅하기.

업데이트
6분 소요

JWT가 이메일·비밀번호 인증에 어떻게 들어맞는지 검색해 보면 똑같은 질문이 계속 반복됩니다. 자격 증명을 토큰에 넣어도 안전한가, 그래도 HTTPS가 필요한가, 이 토큰은 누가 읽어야 하는가, 만료되면 어떻게 되는가. 답은 짧지만, 이를 제대로 이해하는 것이 작업의 대부분입니다.

이 튜토리얼은 AuthFlow™ REST API를 사용하여 이메일/비밀번호 앱에서 JSON Web Token이 최초 가입부터 로그아웃까지 거치는 전체 수명 주기를 살펴봅니다. 토큰 형식 자체는 RFC 7519에 정의되어 있지만, 따라오는 데 읽을 필요는 없습니다.

JWT란 무엇이고, 무엇이 아닌가

JWT는 인증의 결과물이지 인증을 대체하는 것이 아닙니다. 사용자는 이메일과 비밀번호로 자신이 누구인지 한 번 증명합니다. 그러면 서버는 "이 사람은 이미 인증되었다"고 말해 주는 서명된 토큰을 돌려주고, 이후의 모든 요청은 비밀번호 대신 이 토큰을 담아 보냅니다. 올바른 키를 가진 서비스라면 데이터베이스를 다시 조회하지 않고도 토큰을 확인할 수 있기 때문에, JWT는 무상태 및 분산 시스템에서 유용합니다.

JWT는 세 부분으로 이루어집니다. 헤더(토큰 유형과 서명 알고리즘), 사용자에 대한 클레임을 담은 페이로드, 그리고 서명입니다. 서명은 토큰이 변조되지 않았음을 증명할 뿐 아무것도 숨기지 않습니다. 페이로드는 base64로 인코딩되어 있을 뿐이므로 토큰을 입수한 사람은 누구나 읽을 수 있습니다. JWT는 비밀이 아니라 변조 감지가 가능한 것으로 취급하세요.

비밀번호를 토큰에 넣지 마세요

초보자가 자주 묻는 질문은 사용자의 자격 증명을 JWT에 저장해도 되느냐는 것입니다. 일반적으로 그럴 필요가 없습니다. 토큰 자체가 로그인으로 만들어지는 수명이 짧은 자격 증명이기 때문입니다. 사용자를 식별해야 한다면 sub 클레임에 식별자를 넣고, 백엔드에서 필요하다면 역할이나 접근 수준을 함께 넣으세요. 비밀번호, 비밀 값, 그리고 브라우저에 보이면 곤란한 모든 것은 넣지 마세요.

HTTPS는 별개의 문제이며 모든 통신에 사용해야 합니다. HTTPS는 클라이언트와 서버 사이의 트래픽을 보호하고, JWT 서명은 토큰의 무결성을 보호합니다. 어느 쪽도 다른 쪽을 대체하지 못합니다.

1단계: API 키는 서버에 보관하기

AuthFlow 호출은 모두 소유자 대시보드의 API 키를 사용하여 조직을 대신해 이루어집니다. 이 키는 AUTHFLOW_API_KEY 같은 서버 측 환경 변수처럼 직접 관리하는 인프라에 있어야 합니다. 브라우저 JavaScript에 절대 포함하지 마세요. 가장 단순하고 안전한 설계는 프런트엔드가 통신하는 작은 백엔드(또는 저희가 공개한 ExpressJS 프록시)를 두고, 이 백엔드가 대신 /auth와 통신하는 것입니다.

2단계: 가입과 로그인

가입이나 로그인 전에 백엔드는 사용자의 이메일로 /auth/fooBar에서 수명이 짧은 남용 방지 토큰을 요청합니다. 이 토큰은 45초 후에 만료되므로 다음 호출 직전에 가져오고 절대 재사용하지 마세요. 그런 다음 foobar 값, api_key, email, 복잡도 규칙(8~32자, 대문자, 소문자, 숫자, 특수문자 포함)을 충족하는 password, fullname, 그리고 true로 설정한 disclaimed와 함께 /auth/signUp을 호출합니다. 가입에 성공하면 곧바로 세션 토큰이 반환되며, 이메일과 역할이 중복되면 409가 반환됩니다.

로그인도 /auth/login에 대해 같은 방식으로 동작합니다. 성공하면 RS512로 서명된 JWT인 세션 토큰을 받습니다. RS512는 키 쌍을 사용하므로, 토큰은 여러분이 볼 일 없는 개인 키로 서명되고 어떤 비밀도 공유하지 않고 검증할 수 있습니다.

3단계: 토큰을 신중하게 저장하기

백엔드가 토큰을 받으면 어디에 둘지 결정해야 합니다. 페이지 스크립트가 읽을 수 없어 크로스 사이트 스크립팅 버그의 피해를 줄여 주므로 HTTP-only 쿠키를 권장합니다. 무엇을 선택하든 임시 토큰이 아닌 세션 토큰을 보관하고, 로그에 절대 기록되지 않도록 하세요.

4단계: 보호된 모든 라우트에서 검증하기

백엔드가 보호된 요청을 처리하기 전에 토큰을 확인하세요. sessionToken과 사용자의 email로 /auth/validate를 호출하면, 유효한 토큰은 성공하고 유효하지 않거나 만료된 토큰은 401을 반환합니다. 현재 사용자의 프로필이 필요할 때는 /auth/me를 사용하세요. 보호된 모든 요청에 대해 서버에서 이를 수행하는 것이 중요합니다. 검증하지 않는 서명된 토큰은 아무것도 보호하지 못하기 때문입니다.

만료는 설계의 일부입니다. 토큰이 만료되면 앱이 몰래 연장하려 하지 않고 사용자가 다시 로그인합니다. 사용자를 로그인 화면으로 보내는 방식으로 이 401을 자연스럽게 처리하도록 하세요.

5단계: 2단계 인증(2FA) 처리하기

사용자가 2FA를 활성화했다면 /auth/login은 세션 토큰을 반환하지 않고 requires2FA와 tempToken을 반환합니다. 그러면 앱은 두 번째 인증 요소를 요청하고, /auth/2fa 검증 엔드포인트 중 하나(TOTP 코드, 백업 코드, 이메일 OTP)로 tempToken을 교환합니다. 이 교환을 거쳐야만 실제 세션 토큰이 만들어지므로, 반드시 그 토큰을 저장하고 tempToken은 절대 저장하지 마세요.

jwt.io로 토큰 디버깅하기

무언가 이상할 때 토큰에 실제로 무엇이 들어 있는지 가장 빨리 확인하는 방법은 jwt.io입니다. 디버거에 토큰을 붙여 넣으면 헤더와 페이로드가 디코딩되어 알고리즘, sub 클레임, 만료 시각을 확인할 수 있습니다. 대개 이것만으로 만료된 토큰, 잘못된 사용자, 또는 실수로 저장된 tempToken을 찾아낼 수 있습니다.

지금까지의 내용에서 한 가지 주의할 점이 따라옵니다. 토큰은 자격 증명입니다. 운영 환경의 유효한 토큰은 민감한 정보로 다루고, 디버깅에는 테스트 계정을 우선 사용하며, 신뢰할 수 없는 도구에는 실제 토큰을 붙여 넣지 마세요. 토큰을 디코딩하는 것은 검증하는 것과 같지 않습니다. 검증은 여전히 서버에서 /auth/validate를 통해 이루어집니다.

6단계: 로그아웃

세션을 종료하려면 sessionToken과 email로 /auth/logout을 호출한 다음, 토큰을 저장해 둔 곳에서 제거하세요. 비밀번호 변경도 /auth/changePassword를 통해 비슷하게 동작합니다. 그 과정에서 인증 이벤트를 기록해 두면 문제가 생겼을 때 유용한 추적 자료가 됩니다.

JWT 연동 체크리스트

  • API 키는 서버 측 설정에만 있고, 브라우저 코드에는 절대 없습니다.
  • 모든 가입과 로그인 전에 새로운 /auth/fooBar 호출이 선행됩니다.
  • 토큰 페이로드에 비밀번호나 비밀 값을 넣지 않고, sub와 역할로 사용자를 식별합니다.
  • 세션 토큰은 HTTP-only 쿠키 또는 서버가 제어하는 다른 저장소에 보관합니다.
  • 보호된 모든 라우트는 작업을 시작하기 전에 /auth/validate로 토큰을 검증합니다.
  • 만료되었거나 유효하지 않은 토큰(401)은 사용자를 로그인 화면으로 돌려보냅니다.
  • 2FA 경로에서는 tempToken이 아니라 최종 세션 토큰을 저장합니다.
  • 모든 통신에 HTTPS를 사용하며, 토큰은 로그에 절대 기록하지 않습니다.

이것이 전체 흐름입니다. 한 번 인증하고, 서명된 토큰을 들고 다니며, 서버에서 검증하고, 만료되게 두는 것입니다. 전체 엔드포인트 레퍼런스는 시작 가이드를 읽어 보시고, 다른 방식이 궁금하다면 다른 플랫폼의 접근법과 비교해 보세요. 토큰이 이상해 보일 때는 jwt.io가 그 안에 무엇이 있는지 보여 줄 것입니다.

JWT 통합JWT 이메일 비밀번호 인증토큰 기반 인증jwt.io 디버거RS512 JWT