Have ideas to improve npm?Join in the discussion! »

    @auth0/nextjs-auth0
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.1 • Public • Published

    @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 function Index() {
      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.

    Install

    npm i @auth0/nextjs-auth0

    DownloadsWeekly Downloads

    31,658

    Version

    1.3.1

    License

    MIT

    Unpacked Size

    354 kB

    Total Files

    209

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar