RFC: Client Certificate Authentication

[ealexhaywood]

Goals

• Enable server-side data fetching with getServerSideProps() and getStaticProps() to services that require client certificate authentication
• Enable API routes to require client certificate authentication from the browser, and similarly enable API routes to make HTTPS requests to other services that require client certificate authentication
• Minimize the need to manage an HTTPS proxy (e.g. nginx, httpd, Amazon CloudFront, etc.) for incoming requests with self-hosting deployment options

Background

Some large enterprise companies and government organizations require client certificate authentication (i.e. two-way TLS) for all internal network traffic. As Next.js currently exists, the only way a developer can achieve this is by using a custom server and configuring it to use an instance of https.Server instead.

The problem is that this opts you out of Automatic Static Optimization and it appears features of the integrated Next router as well:

Before deciding to use a custom server, please keep in mind that it should only be used when the integrated router of Next.js can't meet your app requirements.

Depending on the network scale and its geographic locations, a user's connection to the network can be quite slow usually as a result from limited bandwidth or high latency. Getting first class TLS/HTTPS support from Next.js would enable developers building internal systems at these enterprises to deliver next-generation experiences to their users.

Implementation

I am more than happy to take a shot at implementation, opening a PR, and iterating on an acceptable solution with the Next.js maintainers and community. I am open to any and all suggestions for how we can achieve this and I figured you all probably know best (assuming I get the greenlight to go ahead and get started 😆).

I was thinking something along the lines of adding an optional https object to some part of the next.config.js that allows for some subset of tls.connect() options to be specified, at a minimum something like this:

// next.config.js
module.exports = {
  https: {
    cert: 'path/to/cert',
    key: 'path/to/key',
    ca: 'path/to/ca'
  }
}

We would also allow other acceptable values string[] (or even Buffer/Buffer[] if your config exports a function) for cert, key, and ca. Other config options could also be pfx and passphrase for users who have keystores instead.

The idea would be to then pass along these values to dev/production Next.js servers and if the https object exists:

• substitute the http module with the https module
• pass the values along as options to an https.Agent
• pass the values along as options to https.createServer

I'm not sure what makes the most sense in the context of Next, but I am eager to take a stab at this with some guidance and the go-ahead. It wouldn't let me select the RFC category, but let me know what you think!

[renrawse]

@ealexhaywood any headway on this?

[michal-mad]

Is there any update on the matter?

[yaronhb]

Personally, I wish this would be given a higher priority.
Client side carts are certainly the best way to lock up a website while still allowing for access from anywhere.

This is appealing for any private use website and business use cases. And, it could be potentially useful during development for when you don’t want anyone snooping your dev-website.

Without any support for this in next.js vercel hoisting becomes irrelevant… in addition to the inconvenience of using a custom server

Also, in addition to the suggested access / no access behavior of mTLS, it could also be interesting to use client certificates to serve different versions of pages than ones served to anonymous visitors.
i.e. use client certs as an alternative method of authentication to logging-in (explicit username-password prompts).

[Fakerko]

Any update? Need to use PFX certificate with passphrase. Can't find any solution for it.

[alyssadicarlo]

Any updates here? Could really use this implementation and can't find a solution.

[ealexhaywood]

Hey all, I haven't done any work towards this, but I have been able to make it work in an environment where TLS client certificate authentication is required:

• for incoming requests to your Next.js app, use an https proxy (like nginx or httpd) that requires client cert auth to my Next.js node container
  • for docker, I've done this using docker-compose where the only entrypoint into the docker network is through this proxy
  • for k8s, you can set it up so that your cluster ingress proxy requires client cert auth. another option is to make your deployment run two containers in a pod, one being the proxy and the other being your node container
• for outgoing requests (using server components or pages router functions like getServerSideProps()) you can provide credentials to whichever http client you're using.

// alternatively you can use pfx + password as well here
const httpsAgent = new https.Agent({
  cert: fs.readFileSync(process.env.PUBLIC_CERTIFICATE_PATH),
  key: fs.readFileSync(process.env.PRIVATE_KEY_PATH),
  ca: fs.readFileSync(process.env.CA_CHAIN_PATH)
})

axios.get(url, { httpsAgent })

Keep in mind you'll be making this request with the server's TLS credentials. If you are making a request on behalf of a user, you'll need to come up with some sort of mechanism to pass that credential along, like a custom HTTP header, or setting a cookie, both of which you can access with headers() or cookies().

A downside is you can't use native fetch() on the server and get the automatic caching and revalidation Next.js provides because it's impossible to pass your TLS credentials to fetch(). The API simply doesn't support it. You can cache responses yourself with React's cache() function though

[kchojhu]

Yeah, I tried to make NextJs fetch work to use httpsAgent and couldn't make it happen. What I don't get is their fetch is an extended version of node fetch...so how is it possible to not support that. I hope someone figures out a way.

[ealexhaywood]

I believe the Node.js's fetch() implementation is based on undici, which you can pass a custom agent configured with a cert, key, and ca through their dispatcher option, however you would need to install undici yourself.

The dispatcher option is non-standard though and may opt you out of Next's patched fetch, and Node.js seems to want their implementation to remain true to the original browser-based Fetch API. I'd be curious to know if it works though, I haven't tried

[kchojhu]

Thanks I got to try to that! Hope it works...

[showduhtung]

have you been able to implement nextjs fetch with undici?