Better Auth로 GitHub 로그인과 온보딩 붙이기: 세션 방식과 개발·프로덕션 앱 분리

세션 기반 GitHub 로그인 구성하기

Better Auth 로 GitHub 회원가입과 로그인 시스템을 새로 구축했다. 인증 설정 파일에서 Better Auth 인스턴스를 만들고 DB 어댑터로 Drizzle 을 연결했다. 로그인은 GitHub 소셜 provider 만 허용하고 이메일과 비밀번호 가입은 껐다. GitHub provider 는 Better Auth 문서(GitHub | Better Auth)의 설정 절차대로 client ID 와 secret 을 socialProviders 설정에 넣어 구성했다.

인증을 완전히 직접 구성하면 시간이 오래 걸린다. 그렇다고 Clerk나 Supabase Auth 같은 서비스를 쓰면 그 서비스에 너무 종속된다고 판단했다. 그래서 빠르게 구성할 수 있는 라이브러리인 Better Auth를 쓰기로 했다.

로그인 인증은 토큰 대신 세션을 택해 간단하고 빠르게 처리했다. 세션은 DB 에 저장하고 쿠키에는 불투명 토큰만 담는다. 만료는 7일이며, 하루 이상 지난 세션을 사용하면 만료일을 다시 늘린다. 세션 쿠키 캐시는 껐다. 매 요청마다 DB 에서 세션을 확인하므로, 세션 행을 지우면 바로 무효화된다.

TypeScript

session: {
  expiresIn: 60 * 60 * 24 * 7, // 7일
  updateAge: 60 * 60 * 24, // 하루 이상 지난 세션을 사용하면 만료일 연장
  // 쿠키 캐시를 끄면 매 요청 DB 조회가 발생하지만, 세션 폐기가 즉시 반영됨
  cookieCache: {
    enabled: false,
  },
},

인증 요청을 모두 받는 경로는 Next.js 핸들러로 연결해, GitHub 콜백도 같은 경로에서 처리한다. 서버에서 세션을 조회하는 함수는 React cache 로 감싸서, 같은 요청 안에서 여러 곳이 불러도 DB 조회는 한 번만 한다. 사용자, 세션, 계정, 검증 값 테이블 네 개는 DB 스키마 안에 정의했다.

로그인 페이지는 이미 세션이 있으면 대시보드로 보내고, 없으면 GitHub 로그인 버튼을 보여 준다. OAuth 콜백이 넘기는 오류 코드별 안내 문구도 두어, 이메일 정보를 받지 못한 경우를 사용자에게 알린다. 대시보드 경로 앞의 요청 처리기는 세션 쿠키가 있는지만 확인하고, 실제 권한 확인은 각 페이지에서 한다.

개발용·프로덕션용 GitHub 앱 나누기

이 로그인을 테스트하려고 GitHub 앱을 개발용과 프로덕션용 두 개로 만들었다. 로컬 개발에서는 개발용 앱으로만 인증되므로 본인 계정만 로그인할 수 있다. GitHub 콜백 주소는 REDIRECT_URL 환경 변수에서 읽어 provider 설정에 넘긴다.

이메일을 비공개로 둔 사용자는 GitHub 사용자 번호와 로그인 이름으로 만든 noreply 주소를 이메일로 쓰도록 했다. 문서(GitHub | Better Auth)는 email_not_found 오류가 GitHub 앱에 이메일 읽기 권한이 없거나 기본 이메일이 비공개일 때 생긴다고 설명하고 user:email scope 를 넣으라고 안내한다. 이 코드는 scope 를 따로 지정하지 않고 GitHub 앱의 권한을 따르도록 주석에 적었다.

로그인 뒤 저장소를 연결할 수 있도록 GitHub 앱 설치 흐름도 처음 작성했다. 로그인하지 않은 사용자는 로그인 페이지로, 로그인한 사용자는 GitHub 앱 설치 페이지로 보낸다.

가입 직후 온보딩 단계 연결하기

가입 후 온보딩 과정을 추가했다. 온보딩 완료 시각을 사용자 정보에 기록하고, 보호 페이지에서 완료 시각이 없으면 온보딩 화면으로 보낸다.

TypeScript

if (!session.user.onboardedAt) {
  redirect('/onboarding');
}

온보딩 화면은 로그인만 확인하고, 이미 마친 사용자는 대시보드로 보낸다. 완료 액션은 완료 시각이 아직 없을 때만 기록하고 대시보드로 이동한다.

화면은 설치, 저장소 선택, 완료 세 단계를 한 화면에서 상태에 따라 바꿔 보여 준다. 시작 단계는 서버에서 정한다. 추적 중인 저장소가 있으면 완료 단계, 설치가 없으면 설치 단계, 설치가 있으면 저장소 선택 단계다. 설치 단계의 GitHub 앱 인증 버튼은 설치 경로로 이동시키고, 나중에 할게요 버튼은 온보딩을 완료 처리한 뒤 대시보드로 보낸다.

저장소 목록은 설치마다 포함된 저장소를 펼쳐 이름순으로 정렬하고, 일시 정지된 설치의 저장소는 뺐다. 저장소를 연동해도 온보딩은 바로 완료하지 않고, 화면을 떠날 때 완료 처리한다.

브랜치 목록은 사용자 토큰으로 설치에 포함된 저장소인지 확인한 뒤 조회하고, 기본 브랜치를 맨 앞에 둔다. 조회 중 토큰 오류는 GitHub 재로그인 안내로, 저장소 404 오류는 접근 불가 상태로 처리한다.

참고

GitHub | Better Auth