3d:"/_next/static/immutable/chunks/2l8_lktacakvg.js" 3e:"/_next/static/immutable/chunks/3z_g1baa39jd6.js" 3f:"/_next/static/immutable/chunks/02i8jb3txq7v0.js" 40:"/_next/static/immutable/chunks/1-6pzy0y-034l.js" 41:"/_next/static/immutable/chunks/1v4el-9vb2ymu.js" 42:I[67949,["$4","$5","$6","$7","$8","$9","$a","$b","$c","$d","$e","$3d","$3e","$3f","$40","$41"],"default"] 43:T5d5c,

📌

요약 — 관리자 로그인의 2차 확인을 새 기기 메일 승인에서 Supabase MFA(TOTP)로 바꿨다. 세션 토큰의 aal 클레임을 proxy, API 가드, RLS 정책 세 곳에서 확인해, 비밀번호만으로 만든 세션은 관리 기능과 데이터에 접근하지 못한다. 변경은 #1554에 있다.

이 글은 hyeoniverse 개발기 시리즈의 하나로, 사이트 보안 점검 2단계에서 한 작업을 정리한다. 1단계에서는 익명 방문자가 악용할 수 있는 항목(공유 속도 제한, 공개 읽기 정책, 보안 헤더)을 고쳤다^[1].

기존 방식의 문제: 검사가 로그인 API에만 있었다

관리자 로그인은 비밀번호를 확인한 뒤 새 기기 메일 승인을 거쳤다. 처음 보는 브라우저면 세션을 지우고 승인 링크를 메일로 보내는 방식이다. 이 확인과 로그인 실패 잠금은 POST /api/admin/auth 안에서만 실행됐다. 그런데 Supabase 세션을 만드는 경로는 세 가지다.

경로	새 기기 확인	실패 잠금
`POST /api/admin/auth`	실행	실행
Supabase Auth 직접 호출 (`/auth/v1/token`)^[2]	실행 안 됨	실행 안 됨
GitHub OAuth (`/auth/callback`)	실행 안 됨	해당 없음

flowchart TD
  pw["비밀번호 로그인<br/>POST /api/admin/auth"] --> chk{"새 기기 확인<br/>· 실패 잠금"}
  chk -->|통과| s1(["세션"])
  direct["Supabase Auth 직접<br/>/auth/v1/token"] --> s2(["세션"])
  gh["GitHub OAuth<br/>/auth/callback"] --> s3(["세션"])
  s1 --> api["관리 API<br/>로그인했는가 · 역할이 있는가"]
  s2 --> api
  s3 --> api

세 경로 모두 같은 형식의 세션을 만든다. 관리 API는 로그인 여부와 역할만 확인했기 때문에 세션이 어느 경로로 만들어졌는지 구분할 수 없었다. 비밀번호를 아는 사람은 두 번째, 세 번째 경로로 승인 메일 없이 관리 기능을 쓸 수 있었다.

따라서 확인 시점을 로그인에서 요청으로 옮겨야 했다. 그러려면 세션 자체에 2단계 인증 여부가 기록되어 있어야 한다.

aal 클레임: 세션에 기록되는 인증 수준

Supabase가 발급하는 access token(JWT)에는 aal(Authenticator Assurance Level) 클레임이 있다^[3]. 비밀번호나 OAuth만 거친 세션은 aal1, TOTP 코드까지 확인한 세션은 aal2다. 이 값은 Supabase가 서명한 토큰 안에 있으므로 클라이언트가 바꿀 수 없다.

flowchart LR
  a["비밀번호"] --> l1(["aal1"])
  b["GitHub"] --> l1
  c["Supabase 직접"] --> l1
  l1 -->|"인증 앱 6자리 확인"| l2(["aal2"])

로그인 경로와 관계없이 TOTP를 확인하지 않은 세션은 aal1이다. 서버는 요청마다 이 값만 확인하면 된다. Supabase에서 TOTP는 별도 설정 없이 켜져 있고 모든 요금제에서 무료다^[4].

TOTP 코드 생성 방식

인증 앱이 30초마다 보여 주는 6자리 숫자는 RFC 6238(TOTP)에 따라 계산한다. TOTP는 카운터 기반 일회용 비밀번호인 RFC 4226(HOTP)의 카운터 자리에 시간을 넣은 방식이다.

비밀 키 공유: 등록할 때 서버가 무작위 키를 만들고 QR 코드로 보여 준다. QR에는 otpauth://totp/...?secret=... 형식으로 키가 담겨 있고^[5], 인증 앱은 이 키를 기기에 저장한다. 키는 등록할 때 한 번만 전달된다.

시간 카운터 계산: 현재 유닉스 시간을 30으로 나눈 몫(floor(t / 30))을 카운터로 쓴다. 서버와 기기의 시각이 같으면 같은 카운터가 나온다^[6].

HMAC 계산: 비밀 키로 카운터의 HMAC-SHA1 값을 구한다. 키를 모르면 이 값을 계산할 수 없다.

6자리로 축약: 20바이트 결과의 마지막 4비트를 오프셋으로 삼아 4바이트를 잘라 내고(dynamic truncation^[7]), 10⁶으로 나눈 나머지를 쓴다.

sequenceDiagram
  participant App as 인증 앱(휴대폰)
  participant Srv as 서버(Supabase)
  Note over App,Srv: 등록 — 한 번만
  Srv->>App: QR(비밀 키)
  App->>Srv: 현재 6자리
  Srv->>Srv: 같은 키 · 같은 시각으로 계산해 비교
  Note over App,Srv: 로그인할 때마다 — 키는 전달되지 않는다
  App->>App: HMAC(키, 시각÷30) → 6자리
  App->>Srv: 6자리
  Srv->>Srv: 같은 계산 → 일치하면 세션을 aal2 로

Node.js로 구현하면 다음과 같다.

import { createHmac } from "node:crypto";

function totp(secret: Buffer, now = Date.now(), step = 30, digits = 6) {
  const counter = Math.floor(now / 1000 / step);   // 시간 카운터
  const msg = Buffer.alloc(8);
  msg.writeBigUInt64BE(BigInt(counter));
  const h = createHmac("sha1", secret).update(msg).digest(); // HMAC-SHA1
  const offset = h[h.length - 1] & 0x0f;                    // dynamic truncation
  const bin = (h.readUInt32BE(offset) & 0x7fffffff) % 10 ** digits;
  return bin.toString().padStart(digits, "0");
}

RFC 6238 부록 B의 테스트 키(12345678901234567890)와 시각 59초를 넣으면 8자리 기준 94287082가 나오고, 위 함수도 같은 값을 반환한다. 이 사이트의 e2e 테스트는 이 함수로 코드를 계산해 2단계 인증 화면을 통과한다.

이 구조에서 다음 특성이 나온다.

네트워크가 필요 없다: 인증 앱은 키와 시계만으로 코드를 만든다. SMS 인증과 달리 통신사나 발송 비용이 없다.

비밀번호와 저장 위치가 다르다: 비밀번호는 사용자의 기억이나 비밀번호 관리자에, TOTP 키는 인증 앱에 있다. 공격자는 둘을 따로 확보해야 한다.

시도 횟수 제한이 필요하다: 6자리 코드는 100만 가지뿐이다. 이 사이트는 계정당 10분에 10회까지만 코드 확인을 허용한다.

키가 노출되면 인증 앱을 뺏긴 것과 같다: QR 아래에 표시하는 키를 다른 사람이 알면 같은 코드를 만들 수 있다. 그래서 등록 화면은 로그인한 본인만 열 수 있다.

aal 확인 위치: proxy, API 가드, RLS

aal을 한 곳에서만 확인하면 기존 방식과 같은 문제가 생긴다. 그래서 요청이 지나가는 세 지점에서 모두 확인한다.

flowchart TD
  req["요청 + 세션 토큰"] --> proxy{"1 · proxy<br/>/admin · /api/admin"}
  proxy -->|"aal1 · 화면"| mfa["/admin/mfa 로"]
  proxy -->|"aal1 · API"| f1["403 MFA_REQUIRED"]
  proxy -->|aal2| guard{"2 · requireAuth<br/>모든 관리 API"}
  guard -->|aal1| f2["403 MFA_REQUIRED"]
  guard -->|aal2| db{"3 · RLS 정책<br/>app_claims()"}
  direct["토큰으로 /rest/v1 직접"] --> db
  db -->|aal2| ok["역할대로 읽기 · 쓰기"]
  db -->|aal1| pub["공개 정책만"]

위치	대상 요청	aal1 세션 처리
proxy (`src/proxy.ts`)	`/admin/` 화면, `/api/admin/`	화면은 `/admin/mfa`로 보내고, API는 403
requireAuth (`src/lib/api/requireAuth.ts`)	`/api/admin` 밖의 관리 API	403
RLS (`app_claims()`)	토큰으로 PostgREST를 직접 호출하는 요청	역할 없음 → 공개 정책만

1. proxy: 관리 화면과 /api/admin

Next.js 16의 proxy(이전 이름 middleware)^[8]는 /admin/*과 /api/* 요청을 모두 거친다. 세션이 aal1이면 화면 요청은 /admin/mfa?next=<원래 경로>로 보내고, /api/admin/* 요청에는 403 MFA_REQUIRED를 반환한다. 예외는 등록·확인 화면과 그 API뿐이다.

// src/proxy.ts (요약)
if (!isMfaPath(pathname) && !(await passesMfa(supabase))) {
  if (isAdminApi(pathname)) return rejectApi(403, "Two-factor authentication required", "MFA_REQUIRED");
  return redirect(`/admin/mfa?next=${encodeURIComponent(pathname + search)}`);
}

2. requireAuth: /api/admin 밖의 관리 API

글 저장(/api/posts)처럼 /api/admin 밖에 있는 관리 API도 있다. 이 API들은 모두 requireAuth()를 호출하므로 여기서 한 번 더 확인한다. proxy의 경로 규칙이 바뀌어도 이 확인은 그대로 남는다.

3. RLS: 토큰으로 PostgREST를 직접 호출하는 경우

앞의 두 단계는 Next.js 서버를 거치는 요청에만 적용된다. 세션 토큰은 Supabase PostgREST(/rest/v1)에도 그대로 쓸 수 있으므로 DB 정책에서도 확인해야 한다^[9]. 이 사이트의 RLS 정책은 app_role(), app_level(), app_author_id() 함수로 토큰의 역할을 읽는다. 이 세 함수가 aal2 토큰에서만 역할을 반환하도록 바꿨다.

CREATE OR REPLACE FUNCTION app_claims() RETURNS jsonb LANGUAGE sql STABLE AS $$
  SELECT CASE WHEN auth.jwt() ->> 'aal' = 'aal2' OR NOT public.mfa_required()
              THEN coalesce(auth.jwt() -> 'app_metadata', '{}'::jsonb)
              ELSE '{}'::jsonb END;
$$;

CREATE OR REPLACE FUNCTION app_role() RETURNS text LANGUAGE sql STABLE AS $$
  SELECT coalesce(app_claims() ->> 'role', '');
$$;

이제 aal1 세션은 DB에서 역할이 없는 사용자로 처리되어 익명 방문자와 같은 공개 정책만 적용받는다. 정책이 역할을 직접 읽지 않고 이 세 함수를 거치도록 만들어 두었기 때문에, 정책 수십 개를 고치지 않고 함수 세 개만 수정했다.

2단계 인증 강제 설정

설정 화면에는 사이트 전체의 2단계 인증 강제 여부를 바꾸는 스위치가 있다. 비밀번호만으로 이 스위치를 끌 수 있다면 강제 설정이 의미가 없으므로 다음 조건을 둔다.

설정 변경 API는 소유자 계정이면서 aal2인 세션만 허용한다. 비밀번호만 아는 aal1 세션은 설정을 바꿀 수 없다.

값은 한 행짜리 테이블(security_settings)에 저장하고, 정책과 서버 모두 mfa_required() 함수로 읽는다. 값을 읽지 못하면(마이그레이션 적용 전, DB 장애) 켜져 있는 것으로 처리한다.

서버는 세션이 aal1일 때만 강제 여부를 조회한다. aal2 세션의 요청에는 조회가 추가되지 않는다.

설정을 바꾸면 관리자 알림을 남긴다.

운영 기준

항목	기준	이유
새 기기	막지 않고 알림 메일만 보낸다	접근 차단은 2단계 인증이 맡는다. 메일 보안 스캐너가 승인 링크(상태를 바꾸는 GET 요청)를 미리 열어 승인해 버리는 문제도 함께 없어진다^[10].
인증 앱 수	두 개 등록, 마지막 하나는 삭제 불가	휴대폰 하나만 등록하면 분실했을 때 로그인할 수 없다.
모두 잃어버린 경우	DB에서 해당 사용자의 MFA factor를 삭제하고 다시 등록	service role 권한이 필요하다.
배포 순서	코드 배포 → 인증 앱 등록 → RLS 마이그레이션	마이그레이션을 먼저 적용하면 등록을 마치기 전까지 관리 화면에서 데이터가 보이지 않는다.
로그인 실패 메시지	하나로 통일	존재하지 않는 계정과 틀린 비밀번호를 구분해 응답하면 계정 존재 여부가 드러난다.

정리

기존 구조는 모든 관리자 세션이 로그인 API를 거쳐 만들어진다고 가정했다. 실제로는 Supabase Auth 직접 호출과 OAuth 콜백으로도 같은 세션이 만들어지고, 세션만 보고는 어느 경로로 만들어졌는지 알 수 없다. 그래서 확인 기준을 로그인 경로에서 세션 토큰의 aal 클레임으로 바꾸고, 이 값을 proxy, API 가드, RLS 세 곳에서 확인하도록 했다.

인증 검사를 추가할 때는 그 검사를 거치지 않고 같은 세션이나 데이터에 도달하는 경로가 있는지 먼저 확인해야 한다. 그런 경로가 있다면 검사를 각 경로가 공통으로 지나는 지점이나 데이터에 가까운 계층으로 옮긴다.

참고

관련 PR: #1551 보안 점검 도구 · 함수 권한, #1552 속도 제한 · 공개 읽기 정책 · 보안 헤더, #1553 CSP 위반 보고, #1554 2단계 인증 강제

Supabase — Multi-Factor Authentication, TOTP

RFC 6238 — TOTP, RFC 4226 — HOTP

NIST SP 800-63B — Authentication and Lifecycle Management

점검 도구 추가와 SECURITY DEFINER 함수 권한 회수는 #1551, 익명 경로 속도 제한 · 공개 읽기 정책 · 보안 헤더는 #1552, CSP 위반 보고는 #1553.

브라우저에 공개된 anon 키만 있으면 비밀번호 로그인 엔드포인트를 직접 호출할 수 있다. anon 키는 공개를 전제로 한 값이라 이것 자체는 문제가 아니다.

Supabase 문서 — JWT Claims Reference. AAL이라는 이름과 단계 구분은 NIST SP 800-63B에서 왔다. AAL1은 단일 요소, AAL2는 서로 다른 두 요소로 인증한 상태다.

Supabase 문서 — Multi-Factor Authentication. 요금이 붙는 것은 SMS · 전화 기반 MFA이고, 이 사이트는 쓰지 않는다. TOTP 등록 · 확인 API는 TOTP 문서에 있다.

Key Uri Format. secret은 Base32로 인코딩한 키다. 대부분의 인증 앱이 이 형식을 읽는다.

기기 시계가 조금 어긋나도 통과하도록 서버는 보통 앞뒤 한 칸(±30초) 정도를 함께 비교한다. RFC 6238 5.2절 참고.

RFC 4226 5.3절. 결과의 어느 위치를 쓸지를 결과 자신이 정해서, 특정 바이트에 치우치지 않게 한다.

Next.js 문서 — proxy.js. Next.js 16에서 middleware가 proxy로 이름이 바뀌었다.

Supabase 문서 — Row Level Security. 정책 안에서 auth.jwt()로 토큰 클레임을 읽을 수 있다.

일부 메일 서비스는 악성 링크 검사를 위해 받은 메일의 링크를 서버에서 미리 연다. 링크를 여는 것만으로 승인되면 사용자가 누르지 않아도 승인된다.

16:["$","$L42",null,{"tag":"보안","initialData":{"posts":[{"id":"5896086e-9f5b-48a7-b89a-37bfbfcc52de","title":"Supabase 관리자 로그인에 TOTP 2단계 인증 강제하기","slug":"admin-two-factor-totp","content":"$43","content_type":"richtext","excerpt":"새 기기 메일 승인을 Supabase MFA(TOTP)로 바꿨다. 세션 토큰의 aal 클레임을 proxy, API 가드, RLS 정책에서 각각 확인해 비밀번호만으로 만든 세션의 관리 기능 접근을 막는다.","cover_image":"https://images.pexels.com/photos/4973899/pexels-photo-4973899.jpeg?auto=compress&cs=tinysrgb&h=650&w=940","tags":["보안","Supabase","Next.js","2FA","TOTP"],"published":true,"language":"ko","view_count":2,"created_at":"2026-10-21T10:26:38.911521+00:00","updated_at":"2026-10-21T14:50:55.478+00:00","title_en":"","content_en":"","excerpt_en":"","like_count":0,"category":"개발","is_pinned":false,"series_id":"50adf6cd-222b-4d12-a438-8a3731ec9388","series_order":0,"post_number":281,"summary_ko":"{\"emoji\":\"🔐\",\"tldr\":\"Supabase TOTP 강제, aal 클레임 3중 검증\",\"blocks\":[{\"type\":\"paragraph\",\"text\":\"관리자 로그인의 2차 확인을 새 기기 메일 승인에서 **Supabase MFA(TOTP)** 로 전환했습니다. 세션 토큰의 `aal` 클레임을 proxy, API 가드, RLS 정책 세 곳에서 확인해 비밀번호만으로 만든 세션의 접근을 차단합니다.\"},{\"type\":\"list\",\"items\":[{\"text\":\"Next.js 16 proxy 가 관리 화면과 `/api/admin` 요청을 모두 거릅니다.\",\"label\":\"Proxy\"},{\"text\":\"`requireAuth` 함수가 글 저장 등 외부 관리 API 를 보호합니다.\",\"label\":\"API 가드\"},{\"text\":\"PostgREST 직접 호출 시 토큰 기반 정책을 적용해 DB 접근을 통제합니다.\",\"label\":\"RLS\"}],\"title\":\"검증 위치\"},{\"type\":\"callout\",\"tone\":\"warn\",\"text\":\"6자리 TOTP 코드는 100만 가지뿐이므로, 계정당 10분에 10회까지만 시도할 수 있도록 제한을 두었습니다.\"}],\"keywords\":[\"Supabase\",\"TOTP\",\"MFA\",\"RLS\",\"보안\"],\"hash\":\"6d91ec5f\"}","summary_en":"{\"emoji\":\"🔐\",\"tldr\":\"Supabase TOTP enforcement, aal claim triple check\",\"blocks\":[{\"type\":\"paragraph\",\"text\":\"Replaced new-device email approval with **Supabase MFA (TOTP)** for admin logins. The `aal` claim in session tokens is verified at three points: proxy, API guard, and RLS policies, blocking access from password-only sessions.\"},{\"type\":\"list\",\"items\":[{\"text\":\"Next.js 16 proxy intercepts all admin UI and `/api/admin` requests.\",\"label\":\"Proxy\"},{\"text\":\"`requireAuth` protects external admin APIs like post saving.\",\"label\":\"API Guard\"},{\"text\":\"Row Level Security applies token-based policies to direct PostgREST calls.\",\"label\":\"RLS\"}],\"title\":\"Verification Points\"},{\"type\":\"callout\",\"tone\":\"warn\",\"text\":\"Since 6-digit TOTP codes have only 1 million possibilities, attempts are limited to 10 per account every 10 minutes.\"}],\"keywords\":[\"Supabase\",\"TOTP\",\"MFA\",\"RLS\",\"Security\"],\"hash\":\"6d91ec5f\"}","deleted_at":null,"scheduled_at":null,"purge_after":null,"sort_order":0,"tag_notes":{"2FA":{"en":"","ko":""},"Next.js":{"en":"","ko":""},"Supabase":{"en":"","ko":""}},"github_url":"","icon":"","cover_position":50,"cover_zoom":1,"version":5,"author_ids":["owner"],"source_lang":"ko","series":{"title":"hyeoniverse 개발기","title_en":"HYEONIVERSE Devlog"}}],"works":[],"totalCount":1,"totalPages":1,"relatedTags":[{"tag":"Supabase","count":1},{"tag":"Next.js","count":1},{"tag":"2FA","count":1},{"tag":"TOTP","count":1}],"perPage":10,"description":""},"allTags":[{"tag":"Next.js","count":2,"description":"React 풀스택 프레임워크입니다. App Router, 서버 컴포넌트, 라우트 핸들러로 SSR/ISR/CSR을 한 곳에서 처리합니다.","related":["라우팅","버그 수정","보안","Supabase","2FA"]},{"tag":"라우팅","count":1,"description":"","related":["Next.js","버그 수정"]},{"tag":"버그 수정","count":1,"description":"","related":["Next.js","라우팅"]},{"tag":"보안","count":1,"description":"","related":["Supabase","Next.js","2FA","TOTP"]},{"tag":"Supabase","count":1,"description":"Postgres 기반의 백엔드 애즈 어 서비스입니다. 인증, DB, 스토리지, 실시간, 엣지 함수를 하나의 SDK로 제공합니다.","related":["보안","Next.js","2FA","TOTP"]},{"tag":"2FA","count":1,"description":"","related":["보안","Supabase","Next.js","TOTP"]},{"tag":"TOTP","count":1,"description":"","related":["보안","Supabase","Next.js","2FA"]}]}]

hyeoniverse 개발기 #1 - Supabase 관리자 로그인에 TOTP 2단계 인증 강제하기