nextjs auth0 다운로드 - nextjs auth0 소스 코드 다운로드

nextjs auth0

기타 소스코드

v3.5.0

다운로드

Auth0 Next.js SDK는 Next.js 애플리케이션에서 사용자 인증을 구현하기 위한 라이브러리입니다.

설명서 - 시작하기 - API 참조 - 피드백

선적 서류 비치

QuickStart - Next.js 앱에 Auth0을 추가하기 위한 가이드입니다.
FAQ - nextjs-auth0에 대해 자주 묻는 질문입니다.
예 - 다양한 사용 사례에 대한 많은 예입니다.
보안 - 확인해야 할 몇 가지 중요한 보안 공지입니다.
아키텍처 - SDK의 아키텍처 개요입니다.
테스트 - nextjs-auth0 애플리케이션 테스트에 도움이 됩니다.
배포 - 예제 앱을 Vercel에 배포하는 방법입니다.
문서 사이트 - 문서 사이트를 탐색하고 Auth0에 대해 자세히 알아보세요.

시작하기

설치

npm 사용:

 npm 설치 @auth0/nextjs-auth0

이 라이브러리에는 Node.js 16 LTS 및 최신 LTS 버전이 필요합니다.

인증0 구성

Auth0 대시보드에서 일반 웹 애플리케이션을 생성합니다.

기존 애플리케이션을 사용하는 경우 일반 웹 애플리케이션에서 다음 설정을 구성했는지 확인하세요.
애플리케이션 페이지의 "설정" 탭을 클릭하세요.
아래로 스크롤하여 "고급 설정 표시" 링크를 클릭하세요.
"고급 설정"에서 "OAuth" 탭을 클릭하세요.
"JsonWebToken 서명 알고리즘"이 RS256 으로 설정되어 있고 "OIDC 준수"가 활성화되어 있는지 확인하세요.

그런 다음 "설정" 페이지의 "애플리케이션 URI" 섹션에서 애플리케이션에 대해 다음 URL을 구성합니다.

허용되는 콜백 URL : http://localhost:3000/api/auth/callback
허용되는 로그아웃 URL : http://localhost:3000/

'기본 정보' 섹션에서 클라이언트 ID , 클라이언트 비밀번호 및 도메인 값을 기록해 두세요. 다음 단계에서 이러한 값이 필요합니다.

기본 설정

애플리케이션 구성

Next.js 애플리케이션이 Auth0과 올바르게 통신하도록 허용해야 합니다. 다음과 같이 필요한 Auth0 구성 값을 정의하는 루트 프로젝트 디렉터리 아래에 .env.local 파일을 생성하면 됩니다.

 # 세션을 암호화하는 데 사용되는 긴 비밀 값 cookieAUTH0_SECRET='LONG_RANDOM_VALUE'# 애플리케이션의 기본 URLAUTH0_BASE_URL='http://localhost:3000'# Auth0 테넌트 도메인의 URLAUTH0_ISSUER_BASE_URL='https://YOUR_AUTH0_DOMAIN.auth0 .com'# Auth0 애플리케이션의 클라이언트 IDAUTH0_CLIENT_ID='YOUR_AUTH0_CLIENT_ID'# Auth0 애플리케이션의 클라이언트 비밀번호AUTH0_CLIENT_SECRET='YOUR_AUTH0_CLIENT_SECRET'

다음 명령을 실행하여 AUTH0_SECRET 값에 적합한 문자열을 생성할 수 있습니다.

 node -e "console.log(crypto.randomBytes(32).toString('hex'))"

"모듈 구성" 문서의 "구성 속성" 섹션에서 Auth0 구성 옵션의 전체 목록을 볼 수 있습니다.

Next.js에서 환경 변수를 로드하는 방법에 대한 자세한 내용은 "환경 변수" 문서를 참조하세요.

인증 흐름의 다양한 부분을 수행하는 내부적으로 다음 경로 핸들러를 생성하는 앱에 handleAuth() 추가합니다.

/api/auth/login : Next.js 애플리케이션은 사용자가 로그인할 수 있도록 ID 공급자로 리디렉션합니다. 선택적으로 returnTo 매개변수를 전달하여 로그인 후 사용자 정의 상대 URL로 돌아갈 수 있습니다(예: /api/auth/login?returnTo=/profile ).
/api/auth/callback : ID 공급자는 사용자가 성공적으로 로그인한 후 이 경로로 리디렉션합니다.
/api/auth/logout : Next.js 애플리케이션이 사용자를 로그아웃합니다.
/api/auth/me : 사용자 프로필 정보를 JSON 형식으로 가져올 수 있습니다.

라우터에 따라 설정을 계속하세요.

페이지 라우터
앱 라우터

페이지 라우터

동적 API 경로 추가

/pages/api 디렉터리 아래에 동적 API 경로 처리기를 만듭니다.

/pages/api/ 디렉터리 아래에 auth 디렉터리를 만듭니다.
새로 생성된 auth 디렉터리 아래에 [auth0].js 파일을 생성합니다.

동적 API 경로 파일의 경로는 /pages/api/auth/[auth0].js 입니다. 해당 파일을 다음과 같이 채웁니다.

 import { handlerAuth } from '@auth0/nextjs-auth0';export 기본 handlerAuth();

사용자 정의 앱에 UserProvider 추가

pages/_app.js 구성 요소를 UserProvider 구성 요소로 래핑합니다.

 // 페이지/_app.jsimport React from 'react';import { UserProvider } from '@auth0/nextjs-auth0/client';export 기본 함수 App({ Component, pageProps }) {
  return (<UserProvider> <Component {...pageProps} /></UserProvider>
  );}

인증 사용

이제 useUser() 후크에서 반환된 user 개체가 정의되었는지 확인하여 사용자가 인증되었는지 확인할 수 있습니다. 자동 생성된 적절한 경로로 사용자를 리디렉션하여 Next.js 애플리케이션의 프런트엔드 계층에서 사용자를 로그인하거나 로그아웃할 수도 있습니다.

 // 페이지/index.jsimport { useUser } from '@auth0/nextjs-auth0/client';export 기본 함수 Index() {
  const { 사용자, 오류, isLoading } = useUser();

  if (isLoading) return <div>로드 중...</div>;
  (오류)인 경우 <div>{error.message}</div>를 반환합니다.

  if (user) {return ( <div>{user.name}님을 환영합니다! <a href="/api/auth/logout">로그아웃</a> </div>);
  }

  <a href="/api/auth/login">로그인</a>;}을 반환합니다.

다음 Linting 규칙에서는 앵커 태그 대신 Link 구성 요소를 사용하도록 제안할 수 있습니다. Link 구성 요소는 페이지 간 클라이언트 측 전환을 수행하기 위한 것입니다. 링크는 페이지가 아닌 API 경로를 가리키므로 이를 앵커 태그로 유지해야 합니다.

앱 라우터

계속하기 전에 React Server 구성 요소와 함께 이 SDK 사용을 확인하세요.

동적 API 경로 추가

/app/api 디렉터리 아래에 포괄적인 동적 API 경로 처리기를 만듭니다(엄격히 말하면 API 경로를 /api 아래에 넣을 필요는 없지만 단순화를 위해 규칙을 유지합니다).

/app/ 디렉터리 아래에 api 디렉터리를 만듭니다.
새로 생성된 /app/api/ 디렉터리 아래에 auth 디렉터리를 만듭니다.
새로 생성된 auth 디렉터리 아래에 [auth0] 디렉터리를 만듭니다.
새로 생성된 [auth0] 디렉터리에 route.js 파일을 생성합니다.

동적 API 경로 파일의 경로는 /app/api/auth/[auth0]/route.js 입니다. 해당 파일을 다음과 같이 채웁니다.

 import { handlerAuth } from '@auth0/nextjs-auth0';export const GET = handlerAuth();

레이아웃에 `UserProvider` 추가하세요.

app/layout.js 구성요소를 UserProvider 구성요소로 래핑합니다.

 // app/layout.jsimport React from 'react';import { UserProvider } from '@auth0/nextjs-auth0/client';export 기본 함수 App({ children }) {
  반환(<UserProvider> <body>{children}</body></UserProvider>
  );}

인증 사용

이제 useUser() 후크에서 반환된 user 개체가 정의되었는지 확인하여 사용자가 인증되었는지 확인할 수 있습니다. 자동 생성된 적절한 경로로 사용자를 리디렉션하여 Next.js 애플리케이션의 프런트엔드 계층에서 사용자를 로그인하거나 로그아웃할 수도 있습니다.

 // 페이지/index.js'클라이언트 사용';import { useUser } from '@auth0/nextjs-auth0/client';export 기본 함수 Index() {
  const { 사용자, 오류, isLoading } = useUser();

  if (isLoading) return <div>로드 중...</div>;
  (오류)인 경우 <div>{error.message}</div>를 반환합니다.

  if (user) {return ( <div>{user.name}님을 환영합니다! <a href="/api/auth/logout">로그아웃</a> </div>);
  }

  <a href="/api/auth/login">로그인</a>;}을 반환합니다.

다음 Linting 규칙에서는 앵커 태그 대신 Link 구성 요소를 사용하도록 제안할 수 있습니다. Link 구성 요소는 페이지 간 클라이언트 측 전환을 수행하기 위한 것입니다. 링크는 페이지가 아닌 API 경로를 가리키므로 이를 앵커 태그로 유지해야 합니다.

React 서버 구성 요소와 함께 이 SDK 사용

앱 디렉토리의 서버 구성요소(페이지 및 레이아웃 포함)는 쿠키에 쓸 수 없습니다 .

세션을 읽고 업데이트하기 위해 서버 구성 요소 에만 의존하는 경우 다음 사항에 유의해야 합니다.

롤링 세션(이 SDK의 기본값)이 있는 경우 사용자가 사이트를 방문할 때 만료가 업데이트되지 않습니다. 따라서 세션이 예상보다 빨리 만료될 수 있습니다( withMiddlewareAuthRequired 사용하여 이를 완화할 수 있음).
액세스 토큰을 새로 고치면 새 액세스 토큰이 세션에 유지되지 않습니다. 따라서 이후에 액세스 토큰을 얻으려고 시도하면 항상 세션에서 만료된 액세스 토큰이 새로 고쳐집니다.
세션에 다른 업데이트를 수행하면 요청 간에 유지되지 않습니다.

쿠키는 미들웨어, 경로 처리기 및 서버 작업에서 작성할 수 있습니다 .

다른 포괄적인 예를 보려면 EXAMPLES.md 문서를 참조하세요.

API 참조

섬기는 사람

노드용

import * from @auth0/nextjs-auth0

Edge 런타임의 경우

import * from @auth0/nextjs-auth0/edge

구성 옵션 및 환경 변수
초기화인증0
핸들 인증
핸들로그인
핸들콜백
핸들로그아웃
핸들 프로필
withApiAuth필수
withPageAuth필수
getSession
업데이트세션
getAccessToken
withMiddlewareAuthRequired(Edge에만 해당)

클라이언트(브라우저용)

import * from @auth0/nextjs-auth0/client

사용자 제공자
사용사용자
withPageAuth필수

테스트 도우미

import * from @auth0/nextjs-auth0/testing

generateSessionCookie

자세한 내용은 자동 생성된 API 문서를 참조하세요.

쿠키 및 보안

모든 쿠키는 HttpOnly, SameSite=Lax 로 설정되고 애플리케이션의 AUTH0_BASE_URL 이 https 인 경우 Secure 로 설정됩니다.

HttpOnly 설정은 클라이언트 측 JavaScript가 쿠키에 액세스할 수 없도록 하여 XSS 공격의 공격 표면을 줄입니다.

SameSite=Lax 설정은 CSRF 공격을 완화하는 데 도움이 됩니다. "향후 브라우저 동작 변경 사항: 개발자가 알아야 할 사항" 블로그 게시물을 읽고 SameSite에 대해 자세히 알아보세요.

캐싱 및 보안

많은 호스팅 제공업체는 사용자에게 가능한 한 빨리 데이터를 제공하기 위해 엣지에서 콘텐츠를 캐시하도록 제안합니다. 예를 들어 Vercel은 응답에 필요한 캐싱 헤더를 제공하는 경우 모든 정적 콘텐츠 및 서버리스 기능에 대해 Vercel Edge Network에서 콘텐츠를 캐시합니다.

일반적으로 인증이 필요한 응답을 캐시하는 것은 좋지 않은 생각입니다. 응답의 콘텐츠가 캐시해도 안전해 보이더라도 응답에 그렇지 않은 다른 데이터가 있을 수 있습니다.

이 SDK는 기본적으로 롤링 세션을 제공합니다. 즉, 세션을 읽는 모든 응답에는 쿠키 만료를 업데이트하는 Set-Cookie 헤더가 있음을 의미합니다. Vercel 및 기타 호스팅 제공업체는 캐시된 응답에 Set-Cookie 헤더를 포함하므로 응답 콘텐츠를 공개적으로 캐시할 수 있다고 생각하더라도 응답 Set-Cookie 헤더는 캐시할 수 없습니다.

호스팅 공급자의 캐싱 규칙을 확인하세요. 그러나 일반적으로 인증이 필요한 응답을 캐시하거나 인증을 확인하기 위해 세션을 터치해서는 안 됩니다(예: withApiAuthRequired , withPageAuthRequired 또는 심지어 getSession 또는 getAccessToken 사용하는 경우).

오류 처리 및 보안

redirect_uri 콜백의 Auth0에서 발생하는 오류에는 OpenID Connect error 및 error_description 쿼리 매개변수를 통해 반영된 사용자 입력이 포함될 수 있습니다. 이로 인해 우리는 IdentityProviderError 의 message , error 및 error_description 속성에 대해 몇 가지 기본 이스케이프를 수행합니다.

그러나 자체 오류 핸들러를 작성하는 경우 먼저 다른 HTML 컨텍스트에 대해 적절하게 이스케이프하는 템플릿 엔진을 사용하지 않고 오류 message 또는 error 및 error_description 속성을 렌더링해서는 안 됩니다.

기본 경로 및 국제화된 라우팅

Next.js를 사용하면 기본 경로를 사용하여 도메인의 하위 경로 아래에 Next.js 애플리케이션을 배포하고 국제화된 라우팅을 사용하여 국제화된(i18n) 경로를 제공할 수 있습니다.

이러한 기능을 사용하면 애플리케이션의 URL이 변경되므로 nextjs-auth0 경로에 대한 URL도 변경됩니다. 이를 수용하기 위해 SDK에는 URL을 사용자 정의할 수 있는 다양한 위치가 있습니다.

예를 들어 basePath: '/foo' 인 경우 Auth0Provider 에 지정된 loginUrl 및 profileUrl 앞에 이를 추가해야 합니다.

 // _app.jsxfunction App({ Component, pageProps }) {
  반환(<UserProvider loginUrl="/foo/api/auth/login" profileUrl="/foo/api/auth/me"> <Component {...pageProps} /></UserProvider>
  );}

또한 로그인 또는 로그아웃에 대한 모든 링크에는 basePath 포함되어야 합니다.

 <a href="/foo/api/auth/login">로그인</a><br /><a href="/foo/api/auth/logout">로그아웃</a>

baseUrl(또는 AUTH0_BASE_URL 환경 변수)을 구성해야 합니다. 예를 들어:

 # .env.localAUTH0_BASE_URL=http://localhost:3000/foo

Server Side withPageAuthRequired로 보호되는 모든 페이지의 경우 필요한 경우 basePath 및 locale 에 따라 returnTo 매개변수를 업데이트해야 합니다.

 // ./pages/my-ssr-page.jsxexport 기본값 MySsrPage = () => <></>;const getFullReturnTo = (ctx) => {
  // TODO: ctx.resolvedUrl, ctx.locale을 기반으로 getFullReturnTo를 구현합니다.
  // 그리고 next.config.js의 basePath 및 i18n 설정.
  return '/foo/en-US/my-ssr-page';};export const getServerSideProps = (ctx) => {
  const returnTo = getFullReturnTo(ctx.req);
  return withPageAuthRequired({ returnTo })(ctx);};

Auth0 React SDK와의 비교

또한 Next.js 애플리케이션에 적합할 수 있는 Auth0 React SDK인 auth0-react도 제공합니다.

auth0-react 에서 사용하는 SPA 보안 모델은 이 SDK에서 사용하는 웹 애플리케이션 보안 모델과 다릅니다. 즉, 이 SDK는 쿠키 세션을 통해 페이지와 API 경로를 보호합니다("쿠키 및 보안" 참조). auth0-react 와 같은 SPA 라이브러리는 사용자의 ID 토큰과 액세스 토큰을 브라우저에 직접 저장하고 이를 사용하여 외부 API에 직접 액세스합니다.

두 모델 모두 보안에 미치는 영향을 알고 있어야 합니다. 그러나 다음 시나리오 중 하나를 충족하는 경우 auth0-react가 요구 사항에 더 적합할 수 있습니다.

Next.js와 함께 정적 HTML 내보내기를 사용하고 있습니다.
서버 측 렌더링 중에는 사용자 데이터에 액세스할 필요가 없습니다.
외부 API를 호출하기 위한 프록시로 Next.js API 경로를 사용하는 대신 액세스 토큰을 얻고 프런트엔드 계층에서 직접 외부 API를 호출하려고 합니다.