Загрузка nextjs auth0 - Загрузка исходного кода nextjs auth0

nextjs auth0

Другой исходный код

v3.5.0

Скачать

Auth0 Next.js SDK — это библиотека для реализации аутентификации пользователей в приложениях Next.js.

Документация – Начало работы – Справочник по API – Обратная связь

Документация

QuickStart — наше руководство по добавлению Auth0 в ваше приложение Next.js.
Часто задаваемые вопросы — часто задаваемые вопросы о nextjs-auth0.
Примеры — множество примеров для разных вариантов использования.
Безопасность — некоторые важные уведомления о безопасности, которые вам следует проверить.
Архитектура — архитектурный обзор SDK.
Тестирование. Некоторая помощь в тестировании вашего приложения nextjs-auth0.
Развертывание — как мы развертываем наш пример приложения в Vercel.
Сайт документации — посетите наш сайт документации и узнайте больше об Auth0.

Начиная

Установка

Использование НПМ:

 npm установить @auth0/nextjs-auth0

Для этой библиотеки требуется Node.js 16 LTS и более новые версии LTS.

Конфигурация аутентификации 0

Создайте обычное веб-приложение на панели управления Auth0.

Если вы используете существующее приложение , убедитесь, что вы настроили следующие параметры в своем обычном веб-приложении:
Нажмите на вкладку «Настройки» на странице вашего приложения.
Прокрутите вниз и нажмите ссылку «Показать дополнительные настройки».
В разделе «Дополнительные настройки» перейдите на вкладку «OAuth».
Убедитесь, что для параметра «Алгоритм подписи JsonWebToken» установлено значение RS256 и включен параметр «Соответствующий OIDC».

Затем настройте следующие URL-адреса для своего приложения в разделе «URI приложения» на странице «Настройки»:

Разрешенные URL-адреса обратного вызова : http://localhost:3000/api/auth/callback
Разрешенные URL-адреса выхода из системы : http://localhost:3000/

Обратите внимание на значения Client ID , Client Secret и Domain в разделе «Основная информация». Эти значения понадобятся вам на следующем шаге.

Базовая настройка

Настройте приложение

Вам необходимо разрешить вашему приложению Next.js правильно взаимодействовать с Auth0. Вы можете сделать это, создав файл .env.local в корневом каталоге проекта, который определяет необходимые значения конфигурации Auth0 следующим образом:

 # Длинное секретное значение, используемое для шифрования сеанса cookieAUTH0_SECRET='LONG_RANDOM_VALUE'# Базовый URL-адрес вашего приложенияAUTH0_BASE_URL='http://localhost:3000'# URL-адрес вашего домена клиента Auth0AUTH0_ISSUER_BASE_URL='https://YOUR_AUTH0_DOMAIN.auth0 .com'# Ваш Auth0 IDAUTH0_CLIENT_ID приложения = 'YOUR_AUTH0_CLIENT_ID'# Секрет клиента вашего приложения Auth0AUTH0_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 перенаправляет пользователей к вашему поставщику удостоверений, чтобы они могли войти в систему (при желании вы можете передать параметр returnTo , чтобы вернуться к пользовательскому относительному URL-адресу после входа в систему, например /api/auth/login?returnTo=/profile ).
/api/auth/callback : ваш провайдер удостоверений перенаправляет пользователей на этот маршрут после успешного входа в систему.
/api/auth/logout : ваше приложение Next.js осуществляет выход пользователя из системы.
/api/auth/me : вы можете получить информацию профиля пользователя в формате JSON.

Продолжите настройку в зависимости от вашего маршрутизатора:

Маршрутизатор страниц
Маршрутизатор приложений

Маршрутизатор страниц

Добавьте динамический маршрут API

Создайте обработчик динамического маршрута API в каталоге /pages/api :

Создайте каталог auth в каталоге /pages/api/ .
Создайте файл [auth0].js во вновь созданном каталоге auth .

Путь к файлу динамического маршрута API будет /pages/api/auth/[auth0].js . Заполните этот файл следующим образом:

 импортировать { handleAuth } из '@auth0/nextjs-auth0'; экспортировать handleAuth по умолчанию ();

Добавьте UserProvider в пользовательское приложение

Оберните pages/_app.js компонентом UserProvider :

 //pages/_app.jsimport React from 'react';import { UserProvider } from '@auth0/nextjs-auth0/client';export function default App({ Component, pageProps }) {
  return (<UserProvider> <Component {...pageProps} /></UserProvider>
  );}

Использовать аутентификацию

Теперь вы можете определить, аутентифицирован ли пользователь, проверив, определен ли объект user , возвращаемый ловушкой useUser() . Вы также можете войти или выйти из системы своих пользователей на внешнем уровне вашего приложения Next.js, перенаправив их на соответствующий автоматически сгенерированный маршрут:

 // страницы/index.jsimport { useUser } from '@auth0/nextjs-auth0/client';экспортируем функцию по умолчанию 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>;}

Следующие правила линтинга могут предложить использовать компонент Link вместо тега привязки. Компонент Link предназначен для выполнения переходов между страницами на стороне клиента. Поскольку ссылки указывают на маршрут API, а не на страницу, вам следует сохранять их как теги привязки.

Маршрутизатор приложений

Прежде чем продолжить, ознакомьтесь с разделом «Использование этого SDK с компонентами сервера React».

Добавьте динамический маршрут API

Создайте универсальный обработчик динамических маршрутов API в каталоге /app/api (строго говоря, вам не нужно размещать маршруты API в каталоге /api но мы сохраняем соглашение для простоты):

Создайте каталог api в каталоге /app/ .
Создайте каталог auth в вновь созданном каталоге /app/api/ .
Создайте каталог [auth0] в только что созданном каталоге auth .
Создайте файл route.js во вновь созданном каталоге [auth0] .

Путь к файлу динамического маршрута API будет /app/api/auth/[auth0]/route.js . Заполните этот файл следующим образом:

 импортировать { handleAuth } из '@auth0/nextjs-auth0'; экспортировать const GET = handleAuth();

Добавьте `UserProvider` в свой макет

Оберните свой компонент app/layout.js компонентом UserProvider :

 // app/layout.jsimport React from 'react';import { UserProvider } from '@auth0/nextjs-auth0/client';экспортируем функцию по умолчанию App({ Children }) {
  return (<UserProvider> <body>{дети</body></UserProvider>
  );}

Использовать аутентификацию

Теперь вы можете определить, аутентифицирован ли пользователь, проверив, определен ли объект user , возвращаемый ловушкой useUser() . Вы также можете войти или выйти из системы своих пользователей на внешнем уровне вашего приложения Next.js, перенаправив их на соответствующий автоматически сгенерированный маршрут:

 // страницы/index.js'use client';import { useUser } from '@auth0/nextjs-auth0/client';экспортируем функцию по умолчанию 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>;}

Следующие правила линтинга могут предложить использовать компонент Link вместо тега привязки. Компонент Link предназначен для выполнения переходов между страницами на стороне клиента. Поскольку ссылки указывают на маршрут API, а не на страницу, вам следует сохранять их как теги привязки.

Использование этого SDK с серверными компонентами React

Серверные компоненты в каталоге приложений (включая страницы и макеты) не могут записывать файлы cookie.

Если вы полагаетесь исключительно на серверные компоненты для чтения и обновления сеанса, вам следует знать следующее:

Если у вас скользящий сеанс (по умолчанию для этого SDK), срок действия не будет обновляться, когда пользователь посещает ваш сайт. Таким образом, сеанс может истечь раньше, чем вы ожидаете (вы можете использовать withMiddlewareAuthRequired чтобы смягчить это).
Если вы обновите токен доступа, новый токен доступа не будет сохранен в сеансе. Таким образом, последующие попытки получить токен доступа всегда будут приводить к обновлению токена доступа с истекшим сроком действия в сеансе.
Если вы внесете какие-либо другие обновления в сеанс, они не будут сохраняться между запросами.

Файл cookie может быть записан из промежуточного программного обеспечения, обработчиков маршрутов и действий сервера.

Другие подробные примеры см. в документе EXAMPLES.md.

Справочник по API

Сервер

Для узла

import * from @auth0/nextjs-auth0

Для среды выполнения Edge

import * from @auth0/nextjs-auth0/edge

Параметры конфигурации и переменные среды
initAuth0
handleAuth
handleВойти
handleОбратный вызов
handleВыйти
ручкаПрофиль
сApiAuthRequired
с PageAuthRequired
getSession
updateSession
getAccessToken
withMiddlewareAuthRequired (только Edge)

Клиент (для браузера)

import * from @auth0/nextjs-auth0/client

Пользовательский поставщик
использоватьПользователь
с PageAuthRequired

Помощники по тестированию

import * from @auth0/nextjs-auth0/testing

генерироватьSessionCookie

Посетите автоматически созданную документацию по API для получения более подробной информации.

Файлы cookie и безопасность

Для всех файлов cookie будет установлено значение HttpOnly, SameSite=Lax и будет установлено значение Secure если AUTH0_BASE_URL приложения — https .

Параметр HttpOnly гарантирует, что клиентский JavaScript не сможет получить доступ к файлу cookie, чтобы уменьшить поверхность атаки XSS-атак.

Параметр SameSite=Lax поможет смягчить атаки CSRF. Узнайте больше о SameSite, прочитав публикацию в блоге «Предстоящие изменения в поведении браузера: что нужно знать разработчикам».

Кэширование и безопасность

Многие хостинг-провайдеры предлагают кэшировать ваш контент на периферии, чтобы как можно быстрее доставлять данные вашим пользователям. Например, Vercel будет кэшировать ваш контент в сети Vercel Edge для всего статического контента и бессерверных функций, если вы предоставите необходимые заголовки кэширования в своем ответе.

Как правило, кэшировать любой ответ, требующий аутентификации, — плохая идея, даже если содержимое ответа кажется безопасным для кэширования, в ответе могут быть другие данные, которые не являются таковыми.

Этот SDK по умолчанию предлагает повторяющийся сеанс, что означает, что любой ответ, читающий сеанс, будет иметь заголовок Set-Cookie для обновления срока действия файла cookie. Vercel и, возможно, другие хостинг-провайдеры включают заголовок Set-Cookie в кэшированный ответ, поэтому, даже если вы считаете, что содержимое ответа может быть кэшировано публично, заголовок Set-Cookie ответа не может.

Проверьте правила кэширования вашего хостинг-провайдера, но, как правило, вам никогда не следует кэшировать ответы, которые либо требуют аутентификации, либо даже касаются сеанса для проверки аутентификации (например, при использовании withApiAuthRequired , withPageAuthRequired или даже просто getSession или getAccessToken ).

Обработка ошибок и безопасность

Ошибки, возникающие из Auth0 в обратном вызове redirect_uri могут содержать отраженный пользовательский ввод через error OpenID Connect и параметр запроса error_description . По этой причине мы выполняем базовое экранирование свойств message , error и error_description IdentityProviderError .

Но если вы пишете свой собственный обработчик ошибок, вам не следует отображать message об ошибке или свойства error и error_description без использования механизма шаблонов, который сначала правильно экранирует их для других контекстов HTML.

Базовый путь и интернационализированная маршрутизация

С помощью Next.js вы можете развернуть приложение Next.js на подпути домена, используя базовый путь, и обслуживать интернационализированные маршруты (i18n), используя интернационализированную маршрутизацию.

Если вы используете эти функции, URL-адреса вашего приложения изменятся, и поэтому изменятся URL-адреса маршрутов nextjs-auth0. Для этого в SDK есть различные места, где вы можете настроить URL-адрес.

Например, если basePath: '/foo' вам следует добавить его к loginUrl и profileUrl указанным в вашем Auth0Provider :

 // _app.jsxfunction App({ Component, pageProps }) {
  return (<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, при необходимости следует обновить параметр returnTo в зависимости от basePath и locale .

 // ./pages/my-ssr-page.jsxexport default MySsrPage = () => <></>;const getFullReturnTo = (ctx) => {
  // TODO: реализовать getFullReturnTo на основе ctx.resolvedUrl, ctx.locale
  // и настройки basePath и i18n вашего next.config.js.
  return '/foo/en-US/my-ssr-page';};export const getServerSideProps = (ctx) => {
  const returnTo = getFullReturnTo(ctx.req);
  return withPageAuthRequired({ returnTo })(ctx);};

Сравнение с Auth0 React SDK

Мы также предоставляем Auth0 React SDK, auth0-react, который может подойти для вашего приложения Next.js.

Модель безопасности SPA, используемая auth0-react отличается от модели безопасности веб-приложения, используемой этим SDK. Короче говоря, этот SDK защищает страницы и маршруты API с помощью сеанса cookie (см. «Файлы cookie и безопасность»). Библиотека SPA, такая как auth0-react будет хранить токен идентификатора пользователя и токен доступа непосредственно в браузере и использовать их для прямого доступа к внешним API.

Вы должны знать о последствиях для безопасности обеих моделей. Однако auth0-react может быть более подходящим для ваших нужд, если вы соответствуете любому из следующих сценариев:

Вы используете статический экспорт HTML с Next.js.
Вам не требуется доступ к пользовательским данным во время рендеринга на стороне сервера.
Вы хотите получить токен доступа и вызывать внешние API непосредственно с внешнего уровня, а не использовать маршруты API Next.js в качестве прокси для вызова внешних API.

Тестирование

По умолчанию SDK создает и управляет одноэлементным экземпляром, который будет работать в течение всего срока службы приложения. При тестировании вашего приложения вам может потребоваться сбросить этот экземпляр, чтобы его состояние не пропадало между тестами.

Если вы используете Jest, мы рекомендуем использовать jest.resetModules() после каждого теста. Альтернативно вы можете создать собственный экземпляр SDK, чтобы его можно было воссоздавать между тестами.

Для сквозных тестов посмотрите, как мы используем макет поставщика OIDC.

Развертывание

Что касается развертывания, посмотрите, как мы развертываем наш пример приложения в Vercel.

Содействие

Мы ценим отзывы и вклад в это репо! Прежде чем начать, пожалуйста, прочтите следующее:

Общие рекомендации Auth0 по вкладу
Правила поведения Auth0
Руководство по вкладам этого репозитория

Отчеты об уязвимостях

Пожалуйста, не сообщайте об уязвимостях безопасности в общедоступном трекере проблем GitHub. Программа ответственного раскрытия подробно описывает процедуру раскрытия проблем безопасности.