Deployment

환경 변수

Auth.js 라이브러리를 사용하려면 AUTH_SECRET 환경 변수를 설정해야 합니다. 이는 쿠키와 토큰을 암호화하는 데 사용되며, 암호학적으로 안전한 최소 32자 이상의 랜덤 문자열이어야 합니다:

npm exec auth secret

pnpm exec auth secret

yarn auth secret

bunx auth secret

OAuth 프로바이더를 사용하는 경우, 프로바이더에서 클라이언트 ID와 클라이언트 시크릿을 제공하며, 이를 환경 변수로 설정해야 합니다 (Auth0과 같은 OIDC 프로바이더의 경우, 세 번째 값인 issuer도 필요할 수 있으며, 프로바이더의 문서를 참조하세요).

AUTH_OKTA_ID=abc
AUTH_OKTA_SECRET=abc
AUTH_OKTA_ISSUER=abc

AUTH_SECRET

이 환경 변수는 필수적으로 설정해야 하는 유일한 변수입니다. JWT를 인코딩하고 전송 중인 데이터를 암호화하는 데 사용되는 비밀 키입니다. 앞서 언급했듯이, 최소 32자 길이의 무작위 문자열을 사용하는 것을 권장합니다. 이 값은 npm exec auth secret 커맨드라인 명령어를 통해 생성하거나, openssl rand -base64 33 명령어를 사용해 생성할 수 있습니다.

AUTH_TRUST_HOST

애플리케이션을 리버스 프록시 뒤에 배포할 때, AUTH_TRUST_HOST를 true로 설정해야 합니다. 이 설정은 Auth.js에게 리버스 프록시의 X-Forwarded-Host 헤더를 신뢰하도록 지시합니다. Auth.js는 애플리케이션이 지원되는 호스팅 제공자 중 하나에서 실행 중임을 나타내는 환경 변수를 감지하면 자동으로 이 값을 true로 추론합니다. 현재 VERCEL과 CF_PAGES(Cloudflare Pages)가 지원됩니다.

AUTH_URL

v5에서는 호스트가 요청 헤더에서 자동으로 추론되기 때문에 이 환경 변수는 대부분 필요하지 않습니다. 하지만 다른 기본 경로를 사용하는 경우, 이 환경 변수를 설정할 수도 있습니다. 예를 들어, AUTH_URL=http://localhost:3000/web/auth 또는 AUTH_URL=https://company.com/app1/auth와 같이 설정할 수 있습니다.

AUTH_REDIRECT_PROXY_URL

참고: 일부 프로바이더(예: Apple)는 리다이렉트 프록시 사용을 지원하지 않습니다.

이 환경 변수는 고급 사용 사례를 위해 설계되었으며, 예를 들어 프리뷰 배포를 위한 프록시로 Auth.js를 사용할 때 활용됩니다. 자세한 내용은 아래의 프리뷰 배포 보안 섹션을 참고하세요.

Serverless

1. 원하는 환경에 필요한 환경 변수를 생성하세요. 선택한 프로바이더(예: OAuth clientId / clientSecret 등)에 필요한 환경 변수도 추가하는 것을 잊지 마세요.
2. OAuth 프로바이더를 사용할 때, 프로덕션 URL에 대한 콜백 URL이 올바르게 설정되었는지 확인하세요. 많은 OAuth 프로바이더는 OAuth 애플리케이션당 하나의 callbackUrl만 설정할 수 있도록 허용합니다. 이 경우, 각 환경(개발, 프로덕션 등)에 대해 별도의 애플리케이션을 생성해야 합니다. Google과 같은 다른 프로바이더는 하나의 애플리케이션에 여러 callbackUrl을 추가할 수 있도록 허용합니다.
   • 기본적으로, next-auth(Next.js) 애플리케이션의 콜백 URL은 다음과 같이 보일 것입니다: https://company.com/api/auth/callback/[provider] (company.com을 도메인으로, provider를 프로바이더 이름(예: github)으로 대체하세요).
   • 다른 프레임워크(@auth/sveltekit, @auth/express 등)는 기본적으로 /auth/callback/[provider] 경로를 사용합니다.
3. 배포하세요! 이 두 가지 전제 조건을 설정한 후, Netlify, Vercel 등에서 Auth.js 애플리케이션을 배포하고 실행할 수 있어야 합니다.

Observability

현재 사용자의 세부 정보를 관찰 도구로 전달하려면 Auth.js에서 제공하는 콜백을 사용할 수 있습니다. 예를 들어, session 콜백에서 user.id를 Sentry로 전달할 수 있습니다.

import * as Sentry from "@sentry/browser"
import NextAuth from "next-auth"
 
export const { handlers, auth, signIn, signOut } = NextAuth({
  callbacks: {
    session({ session, user }) {
      const scope = Sentry.getCurrentScope()
 
      scope.setUser({
        id: user.id,
        email: user.email,
      })
 
      return session
    },
  },
})

Self-hosted

Auth.js는 여러분이 선택한 프레임워크를 배포할 수 있는 어디든지 배포할 수 있습니다. 프레임워크 문서에서 셀프 호스팅에 대한 내용을 확인해 보세요.

Docker

Docker 환경에서 Auth.js 설정 파일에 trustHost: true를 설정하거나 AUTH_TRUST_HOST 환경 변수를 true로 설정해야 합니다.

예제 애플리케이션은 Docker를 통해 여기에서 호스팅되고 있습니다 (소스 코드 참조). 아래는 Auth.js를 사용하는 Next.js 애플리케이션을 위한 Dockerfile 예제입니다.

# syntax=docker/dockerfile:1
# syntax=docker/dockerfile:1
FROM node:20-alpine AS base
 
# 필요한 경우에만 의존성 설치
FROM base AS deps
# libc6-compat가 필요한 이유는 https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine 참조
RUN apk add --no-cache libc6-compat
WORKDIR /app
 
# 의존성 설치
COPY package.json pnpm-lock.yaml* ./
RUN corepack enable pnpm && pnpm i --frozen-lockfile
 
# 필요한 경우에만 소스 코드 재빌드
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
 
# Next.js는 일반적인 사용에 대한 완전히 익명의 원격 측정 데이터를 수집합니다.
# 자세한 내용은 https://nextjs.org/telemetry 참조
# 빌드 중 원격 측정을 비활성화하려면 다음 줄의 주석을 해제하세요.
# ENV NEXT_TELEMETRY_DISABLED 1
 
RUN corepack enable pnpm && pnpm build
 
# 프로덕션 이미지, 모든 파일 복사 및 Next.js 실행
FROM base AS runner
WORKDIR /app
 
ENV NODE_ENV production
# 런타임 중 원격 측정을 비활성화하려면 다음 줄의 주석을 해제하세요.
# ENV NEXT_TELEMETRY_DISABLED 1
 
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
 
COPY --from=builder /app/public ./public
 
# 사전 렌더링 캐시에 대한 올바른 권한 설정
RUN mkdir .next
RUN chown nextjs:nodejs .next
 
# 출력 트레이스를 자동으로 활용하여 이미지 크기 줄이기
# https://nextjs.org/docs/advanced-features/output-file-tracing
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 
USER nextjs
 
EXPOSE 3000
 
ENV PORT 3000
ENV HOSTNAME "0.0.0.0"
 
# server.js는 standalone 출력에서 next build에 의해 생성됨
# https://nextjs.org/docs/pages/api-reference/next-config-js/output
CMD ["node", "server.js"]

프리뷰 배포 보안 설정

참고: 일부 프로바이더(예: Apple)는 리다이렉트 프록시 사용을 지원하지 않습니다.

대부분의 OAuth 프로바이더는 여러 콜백 URL을 설정하거나 와일드카드를 사용할 수 없습니다.

하지만 Auth.js는 프리뷰 배포를 지원하며, 대부분의 OAuth 프로바이더와 함께 사용할 수 있습니다. 핵심 아이디어는 인증 요청을 메인 애플리케이션의 동적 URL로 프록시하는 하나의 배포를 만드는 것입니다. 예를 들어, auth.company.com과 같은 안정적인 배포를 만들고, 모든 OAuth 프로바이더의 callbackUrl을 이 주소로 설정합니다. 이 애플리케이션은 인증이 성공하면 사용자를 프리뷰 배포 URL(예: https://git-abc123-myapp.vercel.app)로 리다이렉트합니다. Auth.js를 사용해 프리뷰 배포를 보호하려면 다음 단계를 따르세요.

1. 안정적인 배포 URL을 결정합니다. 예를 들어, 빌드 간에 URL이 변경되지 않는 배포를 선택합니다. 예를 들어 auth.yourdomain.com(서브도메인을 사용할 필요는 없으며, 메인 사이트의 URL도 가능합니다).
2. 프리뷰 환경과 안정적인 환경 모두에서 AUTH_REDIRECT_PROXY_URL을 안정적인 배포 URL로 설정합니다. 이때 Auth.js가 라우트를 처리하는 경로도 포함해야 합니다. 예: (https://auth.yourdomain.com/api/auth). 안정적인 환경에서 이 변수를 설정하지 않으면 프록시 기능이 활성화되지 않습니다!
3. OAuth 프로바이더 설정에서 callbackUrl을 안정적인 배포 URL로 업데이트합니다. 예를 들어, GitHub의 경우 https://auth.yourdomain.com/api/auth/callback/github로 설정합니다.

재미있는 사실: 모든 예제 앱은 이 프록시 기능을 사용하고 있습니다!