/nextjs-auth0

Next.js SDK for signing in with Auth0

Primary LanguageTypeScriptMIT LicenseMIT

@auth0/nextjs-auth0

Auth0 SDK for signing in to your Next.js applications.

CircleCI NPM version License

Table of Contents

Installation

Using npm:

npm install @auth0/nextjs-auth0

Note that this package supports the following versions of Node.js: ^10.13.0 || >=12.0.0 and the following versions of Next.js: >=10.

Getting Started

Auth0 Configuration

Create a Regular Web Application in the Auth0 Dashboard. If you're using an existing application you'll want to verify that the following settings are configured as follows.

In your application's Advanced Settings (click "Show Advanced Settings"):

  • Json Web Token Signature Algorithm: RS256
  • OIDC Conformant: True

Go ahead and configure the following URLs for your application under Application URIs:

Take note of the Client ID, Client Secret and Domain of your application because you'll need it in the next step.

Basic Setup

The library needs the following required configuration keys. These can be configured in a .env.local file in the root of your application (See more info about loading environmental variables in Next.js):

# A long secret value used to encrypt the session cookie
AUTH0_SECRET='LONG_RANDOM_VALUE'
# The base url of your application
AUTH0_BASE_URL='http://localhost:3000'
# The url of your Auth0 tenant domain
AUTH0_ISSUER_BASE_URL='https://YOUR_AUTH0_DOMAIN.auth0.com'
# Your Auth0 application's Client ID
AUTH0_CLIENT_ID='YOUR_AUTH0_CLIENT_ID'
# Your Auth0 application's Client Secret
AUTH0_CLIENT_SECRET='YOUR_AUTH0_CLIENT_SECRET'

For a full list of configuration options see the docs.

Then, create a Dynamic API Route handler at /pages/api/auth/[...auth0].js.

import { handleAuth } from '@auth0/nextjs-auth0';

export default handleAuth();

This will create the following urls: /api/auth/login, /api/auth/callback, /api/auth/logout and /api/auth/me.

Wrap your pages/_app.js component in the UserProvider component.

// pages/_app.js
import React from 'react';
import { UserProvider } from '@auth0/nextjs-auth0';

export default function App({ Component, pageProps }) {
  return (
    <UserProvider>
      <Component {...pageProps} />
    </UserProvider>
  );
}

Check whether a user is authenticated by checking that user has a value, and log them in or out from the front end by redirecting to the appropriate automatically-generated route.

// pages/index.js
import { useUser } from '@auth0/nextjs-auth0';

export default () => {
  const { user, error, isLoading } = useUser();

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>{error.message}</div>;

  if (user) {
    return (
      <div>
        Welcome {user.name}! <a href="/api/auth/logout">Logout</a>
      </div>
    );
  }

  return <a href="/api/auth/login">Login</a>;
};

For more extensive examples see EXAMPLES.md.

Documentation

API Reference

Server Side methods:

Client Side methods/components:

Generated API Docs

Cookies and Security

All cookies will be set as HttpOnly, SameSite=Lax and will be forced to HTTPS (Secure) if the application's AUTH0_BASE_URL is https.

The HttpOnly setting will make sure that client-side javascript is unable to access the cookie to reduce the attack surface of XSS attacks while SameSite=Lax will help mitigate CSRF attacks. Read more about SameSite here.

Comparison with auth0-react

We also provide a SPA React library auth0-react, which may also be suitable for your Next.js application.

The SPA security model used by auth0-react is different to the Web Application security model used by this SDK. In short, this SDK protects pages and API routes with a cookie session (See Cookies and Security) whereas a SPA library like auth0-react will store the user's ID Token and Access Token directly in the browser and use them to access external APIs directly.

You should be aware of the security implications of both, but if you are:

  • Using Static HTML Export
  • You do not need to access user data during server-side rendering
  • You want to get the Access Token and call external API's directly from the frontend rather than using Next.js API Routes as a proxy to call external APIs

Then auth0-react may be more suitable for your needs.

Testing

By default, the SDK creates and manages a singleton instance to run for the lifetime of the application. When testing your application you may need to reset this instance, so its state does not leak between tests. If you're using Jest, we recommend using jest.resetModules() after each test. Alternatively, you can look at creating your own instance of the SDK so it can be recreated between tests.

Contributing

We appreciate feedback and contribution to this repo! Before you get started, please see the following:

Run NPM install first to install the dependencies of this project:

npm install

In order to build a release, you can run the following commands and the output will be stored in the dist folder:

npm run clean
npm run lint
npm run build

Additionally, you can also run tests:

npm run build:test # Build the Next.js test app
npm run test
npm run test:watch

Vulnerability Reporting

Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

What is Auth0?

Auth0 helps you to easily:

  • Implement authentication with multiple identity providers, including social (e.g., Google, Facebook, Microsoft, LinkedIn, GitHub, Twitter, etc), or enterprise (e.g., Windows Azure AD, Google Apps, Active Directory, ADFS, SAML, etc.)
  • Log in users with username/password databases, passwordless, or multi-factor authentication
  • Link multiple user accounts together
  • Generate signed JSON Web Tokens to authorize your API calls and flow the user identity securely
  • Access demographics and analytics detailing how, when, and where users are logging in
  • Enrich user profiles from other data sources using customizable JavaScript rules

Why Auth0?

License

This project is licensed under the MIT license. See the LICENSE file for more info.