Supabase Auth + RLS로 팀 RBAC 구현하기 — JWT claims 설계부터 역할별 접근 정책까지

[1] Custom Access Token Hook (PostgreSQL 함수)
    → 로그인 시 team_members 조회 → JWT app_metadata에 역할 배열 삽입
 
[2] JWT Claims (app_metadata.team_roles)
    → [{team_id, role}, ...] 형태로 토큰 안에 이미 존재
 
[3] Row Level Security (RLS)
    → 쿼리마다 auth.jwt() / auth.uid()로 역할 확인 → 행 단위 필터 적용

raw_app_meta_data  → 서버만 수정 가능 → 인가(Authorization)에 사용 ✅
raw_user_meta_data → 사용자가 직접 수정 가능 → 인가에 사용 금지 ❌

(auth.jwt() -> 'app_metadata' ->> 'role')

-- 팀 테이블
CREATE TABLE teams (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT now()
);
 
-- 팀 멤버십 테이블 (역할 포함)
CREATE TABLE team_members (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  team_id UUID REFERENCES teams(id) ON DELETE CASCADE,
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  role TEXT CHECK (role IN ('admin', 'member', 'viewer')) NOT NULL,
  UNIQUE(team_id, user_id)
);
 
-- Hook 타임아웃 방지를 위한 인덱스 (필수)
CREATE INDEX ON team_members(user_id);
CREATE INDEX ON team_members(team_id, user_id);
 
-- 팀 소유 리소스 예시
CREATE TABLE team_documents (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  team_id UUID REFERENCES teams(id) ON DELETE CASCADE,
  title TEXT NOT NULL,
  content TEXT,
  created_by UUID REFERENCES auth.users(id)
);

CREATE OR REPLACE FUNCTION public.custom_access_token_hook(event JSONB)
RETURNS JSONB
LANGUAGE plpgsql
STABLE  -- 동일 트랜잭션 내에서 결과가 불변임을 선언. 플래너가 호출 횟수를 최적화할 수 있음
AS $$
DECLARE
  claims JSONB;
  user_id UUID;
  team_roles JSONB;
BEGIN
  user_id := (event->>'user_id')::UUID;
 
  -- 유저의 모든 팀 역할을 배열로 조회
  SELECT jsonb_agg(
    jsonb_build_object('team_id', team_id::TEXT, 'role', role)
  )
  INTO team_roles
  FROM team_members
  WHERE team_members.user_id = user_id;
 
  claims := event->'claims';
 
  -- app_metadata에 팀 역할 배열 삽입 (팀이 없는 유저는 빈 배열)
  claims := jsonb_set(
    claims,
    '{app_metadata, team_roles}',
    COALESCE(team_roles, '[]'::JSONB)
  );
 
  RETURN jsonb_set(event, '{claims}', claims);
END;
$$;
 
-- Hook이 실행될 수 있도록 supabase_auth_admin에 실행 권한 부여
GRANT EXECUTE ON FUNCTION public.custom_access_token_hook TO supabase_auth_admin;

{
  "app_metadata": {
    "team_roles": [
      { "team_id": "uuid-a", "role": "admin" },
      { "team_id": "uuid-b", "role": "viewer" }
    ]
  }
}

CREATE OR REPLACE FUNCTION get_user_team_role(check_team_id UUID)
RETURNS TEXT
LANGUAGE sql
STABLE  -- 동일 트랜잭션 내 반복 호출 시 결과 캐싱 허용
SECURITY DEFINER
SET search_path = public  -- search_path 조작을 통한 보안 취약점 방지
AS $$
  SELECT role
  FROM team_members
  WHERE team_id = check_team_id
    AND user_id = auth.uid()
  LIMIT 1;
$$;

ALTER TABLE team_members ENABLE ROW LEVEL SECURITY;
 
-- 본인의 team_members 행만 조회 가능 (SECURITY DEFINER 함수 내부는 이 정책의 영향을 받지 않음)
CREATE POLICY "team_members_select_own"
  ON team_members FOR SELECT
  USING (user_id = auth.uid());

-- RLS 활성화 (이게 먼저!)
ALTER TABLE team_documents ENABLE ROW LEVEL SECURITY;
 
-- 뷰어 이상: 자기 팀 문서 조회 가능
-- get_user_team_role()은 행마다 호출되므로, 결과 셋이 클 경우 성능 영향 있음
CREATE POLICY "team_docs_select"
  ON team_documents FOR SELECT
  USING (
    get_user_team_role(team_id) IN ('admin', 'member', 'viewer')
  );
 
-- 멤버 이상: 문서 생성 가능
CREATE POLICY "team_docs_insert"
  ON team_documents FOR INSERT
  WITH CHECK (
    get_user_team_role(team_id) IN ('admin', 'member')
    AND created_by = auth.uid()
  );
 
-- 멤버: 자신이 만든 문서만 수정
CREATE POLICY "team_docs_update_member"
  ON team_documents FOR UPDATE
  USING (
    get_user_team_role(team_id) = 'member'
    AND created_by = auth.uid()
  );
 
-- 관리자: 팀 내 모든 문서 수정/삭제 가능
CREATE POLICY "team_docs_update_admin"
  ON team_documents FOR UPDATE
  USING (get_user_team_role(team_id) = 'admin');
 
CREATE POLICY "team_docs_delete_admin"
  ON team_documents FOR DELETE
  USING (get_user_team_role(team_id) = 'admin');

CREATE POLICY "team_docs_select_from_jwt"
  ON team_documents FOR SELECT
  USING (
    EXISTS (
      SELECT 1
      FROM jsonb_array_elements(
        (auth.jwt() -> 'app_metadata' -> 'team_roles')
      ) AS tr
      -- team_id를 TEXT로 캐스팅해 JWT의 문자열 team_id와 타입을 통일
      WHERE (tr->>'team_id') = team_id::TEXT
        AND (tr->>'role') IN ('admin', 'member', 'viewer')
    )
  );

팀 수 × 역할 조합이 단순하다    → JWT claims 방식 (고성능, 구현 단순)
역할이 자주 바뀌거나 즉각 반영 필요 → DB 조회 방식 (SECURITY DEFINER 함수)
두 가지 혼용                   → JWT에는 단순 플래그, 세밀한 권한은 DB 조회