NetlifyCMS with GitHub OAuth authentication hosted on Vercel
Tags: nextjs, netlifycms, vercel, github
Published: 2021-05-23 20:05:53

---
title: NetlifyCMS with GitHub OAuth authentication hosted on Vercel
published: true
description: To use a GitHub backend with NetlifyCMS, you have to run your own server to handle OAuth or use serverless provider like Vercel. This post explains how to setup NetlifyCMS when hosting on Vercel.
tags: Nextjs, NetlifyCMS, Vercel, GitHub
canonical_url: https://www.component-driven.dev/articles/netlify-cms-github-oauth-vercel
---

Recently, I was moving [www.danielamulle.at](http://www.danielamulle.at) to Vercel while transitioning to Next.js from Gatsby. The transition went quite smooth in general, but one thing I didn't expect troubles with was  making NetlifyCMS work on Vercel.

[NetlifyCMS](https://www.netlifycms.org) is a great headless content management system that has good defaults, is flexible enough to fulfill most needs, has a pluggable API, and works well if you host your content on GitHub. [I have also contributed](https://github.com/netlify/netlify-cms/graphs/contributors) to the project when it was at the very early stage. For obvious reasons, Netlify CMS works really well when you host on Netlify but unfortunately things become a bit more complicated if you decide to move to another hosting provider.

> This is due to a requirement of GitHub’s authentication flow. To use a GitHub backend with NetlifyCMS, you have to run your own server to handle OAuth or use serverless provider like Vercel.

Netlify substitutes the need for the server and makes it work out-of-the-box but it also might feel like a verndor lock-in. Fortunately, there are open source solutions that implement everything needed but setting everything up can take some time. This is a step-by-step guide of things that worked for me.

## Step 1. Configure Netlify CMS

Put you `config.yml` file to `/public` so it's accessible by NetlifyCMS when deployed to production. Open the file and additionally to your existing config you need to:

1. Set `repo` to your GitHub repo that contains the source code of your site.
2. Set `base_url` to the production domain with HTTPS protocol, for example, `https://www.danielamulle.at` in my case.
3. Add `auth_endpoint: api/auth`. This is the URL that NetlifyCMS will open when you click "Authenticate" button. We'll implement this endpoint in our next.js app later.

I've also enabled `local_backend: true` in the config to make CMS work with the local git without going over the server when in development mode. You can read about [making NetlifyCMS to work with a local git repository](https://www.netlifycms.org/docs/beta-features/#working-with-a-local-git-repository). 

## Step 2. Create GitHub App

Go to GitHub and navigate to Settings → Developer settings → GitHub Apps → New GitHub App or use this [direct link](https://github.com/settings/apps/new).

It's not important how you'll name the app since it will not be published. Fill `User authorization callback URL` with the URL `https://<domain>/api/callback`. Use *exactly the URL* that you entered as  `base_url` at the previous step.

Disable Webhook checkbox and set permissions to `Read & Write` for "Contents":

Hit "Create app" and on the next page you'll see the app details with `Client ID` and `Client secret`. We will need those on the next step.

## Step 3. Set environment secrets

Add those values to Vercel environment variables:

```bash
vercel env add secret OAUTH_CLIENT_ID <client-id-of-GitHub-App>
vercel env add secret OAUTH_CLIENT_SECRET <client-secret-of-GitHub-App>
```

## Step 4. Setup OAuth client in Next.js app

Install [https://github.com/bericp1/netlify-cms-oauth-provider-node](https://github.com/bericp1/netlify-cms-oauth-provider-node) as a dependency to your project:

```bash
npm install netlify-cms-oauth-provider-node
```

and create a `.env` file to add following configuration options:

```bash
OAUTH_CLIENT_ID=
OAUTH_CLIENT_SECRET=
COMPLETE_URL=https://<domain>/api/callback
ORIGIN=<domain>
```

where `<domain>` is your domain without https. It's important to match `COMPLETE_URL` here and in the GitHub App so make sure they are the same.

Then create 2 files: `/src/pages/api/auth.js` and `/src/pages/api/callback.js` 

```jsx
import { createVercelBeginHandler } from "netlify-cms-oauth-provider-node"

module.exports = createVercelBeginHandler({}, { useEnv: true })
```

```jsx
import { createVercelCompleteHandler } from "netlify-cms-oauth-provider-node"

module.exports = createVercelCompleteHandler({}, { useEnv: true })
```

After that, push the code to production branch on Vercel and wait till it's deployed. Navigate to your site and go to the CMS URL. You should be able to authenticate with GitHub now.

## Credits

Huge thanks to @bericp1 for [https://github.com/bericp1/netlify-cms-oauth-provider-node](https://github.com/bericp1/netlify-cms-oauth-provider-node) and @robinpokorny for [https://github.com/robinpokorny/netlify-cms-now](https://github.com/robinpokorny/netlify-cms-now). Robin's solution didn't work for me but it led me to the right direction.