carbonplan / auth

adding simple password authentication to sites

A library for adding simple password authentication to next.js sites. Rather than use a full-blown user-based authentication system, we adopt a password-only model that is well suited to sharing content previews and similar use cases that do not involve user accounts or other forms of user data.

usage

To use, install the package with

npm i @carbonplan/auth

You then need to follow four steps to incorporate auth into your site. For these purposes, we assume you have a fairly standard next.js app setup. Feel free to check out the example in this repo to follow along.

step 01

Create an api route in your pages folder e.g. api/auth.js. This file needs to define a secret key for use with the jsonwebtoken package, and also define a mapping from one or more user ids to passwords, and then pass these to the api function which returns a handler. Typically, you will source these from environmental variables so that they are only accessible on the server. Remember to never commit these keys to GitHub or otherwise make them public!

import { api } from '@carbonplan/auth'

const secret = process.env.JWT_SECRET

const users = [
  {
    username: 'user',
    password: process.env.USER_PASSWORD,
  },
]

const handler = api({ secret, users })

export default handler

The handler accepts one additional option, expiration, which controls the expiration time for the JSON webtokens. The default is 1hr but you can provide either a number to specify in seconds e.g. {expiration: 60} or as a string e.g. {expiration: '5hrs'}. See the jsonwebtoken docs for more details.

step 02

Wrap your app in an AuthProvider by adding the following to your _app.js file.

import { AuthProvider } from '@carbonplan/auth'

const App = ({ Component, pageProps }) => {
  return (
    <AuthProvider>
      <Component {...pageProps} />
    </AuthProvider>
  )
}

The AuthProvider component also accepts a config property. Currently the only configuration is whether to use localStorage to store JSON webtokens, which enables authentication to persist so long as the key is valid. You can turn this on using config={{ useLocalStorage: true }}.

step 03

Create a login.js page with the following content in your pages folder.

import { Login } from '@carbonplan/auth'

export default Login

step 04

For any page where you want to require authentication for access, wrap the page component using the withAuth higher-order component. For example, we could define a page pages/protected.js as follows.

import { withAuth } from '@carbonplan/auth'

const Protected = () => {
  return <div>This page is protected</div>
}

export default withAuth(Protected, ['user'])

Whenever someone routes to /protected they will first be redirected to the login page to enter their password, and then if the password is valid they will be directed back to /protected to see its content.

The second argument to withAuth specifies a list of valid user ids, which correspond to the ids used when defining the list of valid passwords in step 01. For example, if in that step we defined

const users = [
  {
    username: 'user',
    password: 'foo',
  },
  {
    username: 'admin',
    password: 'duh',
  },
]

Then a page using withAuth(Protected, ['user']) would be accessible with the password foo (but not duh) and a page using withAuth(Protected, ['admin']) would be accessible with the password duh (but not foo). A page using withAuth(Protected, ['user', 'admin']) would be accessible with either password. Because we set the list of users for every page, this pattern creates a lot of flexibility in terms of who gets access to which page, but without requiring an explicit model of user accounts or user data.

license

All the code in this repository is MIT licensed, but we request that you please provide attribution if reusing any of our digital content (graphics, logo, articles, etc.).

about us

CarbonPlan is a non-profit organization that uses data and science for climate action. We aim to improve the transparency and scientific integrity of climate solutions with open data and tools. Find out more at carbonplan.org or get in touch by opening an issue or sending us an email.