DEV Community: Maxi Ferreira

Password Protection for Cloudflare Pages

Maxi Ferreira — Wed, 12 Jan 2022 19:46:18 +0000

Cloudflare Pages is a fantastic service for hosting static sites: it is extremely easy to set-up, it deploys your sites automatically on every commit to your GitHub or GitLab repos, and its free plan is incredibly generous; with unlimited users, sites, requests, and bandwidth.

For the purposes of deploying and previewing static sites, Pages is very similar to products like Vercel or Netlify. However, one of the features it lacks in comparison to its main competitors is the ability to protect environments using a simple password-only authorization.

You have the option to limit access to your Pages environment by integrating with Cloudflare's Access product (which is free for up to 50 users), and you should definitely look into it if you're looking for a full-blown authentication mechanism.

But if what you need is a basic layer of protection so that your sites are not immediately available to the public, a simple password-only authentication feature like the one offered by Netlify and Vercel might be exactly what you need.

In this post I'm going to talk about how you can password-protect your Cloudflare Pages site by building a small authentication server powered by Cloudflare Workers; Cloudflare's serverless platform.

You can see a demo of the final result here: https://cloudflare-pages-auth.pages.dev/ (password: password).

TLDR

If you want to add password-protection to your own Cloudflare Pages site, just head to the repo and follow the instructions there.

You basically need to do two things:

Copy the contents of the functions directory from the repo into your own project.
Add a CFP_PASSWORD environment variable to your Cloudflare Pages dashboard with the password you want to use.

And that's it! The next time you deploy, your site will be password-protected 🎉

⚠️ Note: You might want to update your Cloudflare project settings to be "Failed closed" as well. Otherwise, your site will be unprotected if you reach your daily limit of Function requests. Thanks Thomas for letting me know about this!

If you're interested in learning more about how this works, just read along!

Pages, Workers, and Functions

Cloudflare Pages is primarily a service for hosting static sites, which means that to run our small authentication application, we'll need a backend environment that can execute our server-side functions.

That's where Cloudflare Workers come in, which is a serverless execution environment (similar to AWS Lambda or Vercel Edge Functions) that we can use to run our authentication application on Cloudflare's amazingly fast edge network.

Pages and Workers are two separate products, and while they integrate really well together, if you want to build an application that uses them both, you'd typically need to create two separate projects and manage and deploy them individually. Thankfully, we can use a feature called Cloudflare Functions to make things a lot easier.

Functions are a feature of Cloudflare Pages that serve as a link between our Pages site and a Workers environment. The advantage of using Functions is that we can manage and deploy them as part of our Pages project rather than having to create a separate Workers application.

To create a function, we simply need to create a functions folder in the root of our project, and add JavaScript or TypeScript files in there to handle the function's logic. This will also generate a routing table based on the file structure of this folder. So if we create the following script as functions/api/hello-world.js:

// functions/api/hello-world.js

export async function onRequest(context) {
  return new Response("Hello, world!");
}

When we deploy our site, this function will be available under the URL: https://your-site.pages.dev/api/hello-world.

If you want to learn more about Functions and Workers, check out the various resources on the Cloudflare Docs site.

Middleware

Our small authentication application needs a way to intercept all requests to our Pages project so that we can verify that the user has access to the site, or redirect them to the login page if they don't. We can do this using Middleware, which are a special type of function that sits between the user's request and the route handler.

To create a middleware for all of the pages on our site, we need to add a _middleware.js file to the functions folder. Here's an example middleware that gives you a different response if you're trying to access the /admin route.

export async function onRequest(context) {
  const { request, next } = context;
  const { pathname } = new URL(request.url);

  if (pathname === '/admin') {
    return new Response('You need to log in!')
  }

  return await next();
}

A Simple Password-Protection Server

Now that we've seen how Functions, Workers, and Middleware work, we can start designing our application so that it works on any Pages site. We'll keep the application fairly simple:

We'll use a middleware to intercept all request to the site and redirect them to a login page if they're not authenticated.
We'll create a route that handles submissions to the login form, and verifies that the user has provided the right password (which is stored in an environment variable).
If they provide the right password, we'll set a cookie with a hash that subsequent requests will use to verify that they're authenticated.

Here's what the overall design looks like:

You can see the complete implementation that powers this password-protection server in the functions folder of the example-repo. The folder contains 5 files (written in TypeScript, but you can remove the types and rename to .js if you feel more comfortable with plain JavaScript):

_middleware.ts -> the middleware that intercepts all requests to our Pages site.
cfp_login.ts -> the function that handles POST request to the /cfp_login route.
constants.ts -> a few constants you can use to customize the service to your liking.
template.ts -> the HTML template for the login page.
utils.ts -> a couple of utility functions for encrypting passwords and working with cookies.

There is nothing too interesting going on in the constants.ts, template.ts and utils.ts files, so I'm going to focus on the other two:

_middleware.ts

// functions/_middleware.ts

import { CFP_ALLOWED_PATHS } from './constants';
import { getCookieKeyValue } from './utils';
import { getTemplate } from './template';

export async function onRequest(context: {
  request: Request;
  next: () => Promise<Response>;
  env: { CFP_PASSWORD?: string };
}): Promise<Response> {
  const { request, next, env } = context;
  const { pathname, searchParams } = new URL(request.url);
  const { error } = Object.fromEntries(searchParams);
  const cookie = request.headers.get('cookie') || '';
  const cookieKeyValue = await getCookieKeyValue(env.CFP_PASSWORD);

  if (
    cookie.includes(cookieKeyValue) ||
    CFP_ALLOWED_PATHS.includes(pathname) ||
    !env.CFP_PASSWORD
  ) {
    // Correct hash in cookie, allowed path, or no password set.
    // Continue to next middleware.
    return await next();
  } else {
    // No cookie or incorrect hash in cookie. Redirect to login.
    return new Response(getTemplate({ withError: error === '1' }), {
      headers: {
        'content-type': 'text/html'
      }
    });
  }
}

As we talked about before, this function intercepts all requests to our Pages site. If you look at the body of the function, it's nothing more than a big if/else statement:

If the request includes a cookie with the correct authentication hash, or if the path is on the list of allowed paths (paths that you don't want to password-protect), or if the CFP_PASSWORD environment variable is not set, continue to the next middleware, which in our case means respond with the route we were intercepting.
Otherwise, respond with the contents of the getTemplate() function, which is the HTML template of the login page.

cfp_login.ts

The other interesting component of the application is the cfp_login.ts function, which is yet another big if/else block:

// functions/cfp_login.ts

import { CFP_COOKIE_MAX_AGE } from './constants';
import { sha256, getCookieKeyValue } from './utils';

export async function onRequestPost(context: {
  request: Request;
  env: { CFP_PASSWORD?: string };
}): Promise<Response> {
  const { request, env } = context;
  const body = await request.formData();
  const { password } = Object.fromEntries(body);
  const hashedPassword = await sha256(password.toString());
  const hashedCfpPassword = await sha256(env.CFP_PASSWORD);

  if (hashedPassword === hashedCfpPassword) {
    // Valid password. Redirect to home page and set cookie with auth hash.
    const cookieKeyValue = await getCookieKeyValue(env.CFP_PASSWORD);

    return new Response('', {
      status: 302,
      headers: {
        'Set-Cookie': `${cookieKeyValue}; Max-Age=${CFP_COOKIE_MAX_AGE}; Path=/; HttpOnly; Secure`,
        'Cache-Control': 'no-cache',
        Location: '/'
      }
    });
  } else {
    // Invalid password. Redirect to login page with error.
    return new Response('', {
      status: 302,
      headers: {
        'Cache-Control': 'no-cache',
        Location: '/?error=1'
      }
    });
  }
}

Notice that we're exporting a function called onRequestPost as opposed to the onRequest function of the previous file. This is because we want this route to react to POST requests to the /cfp_login path.

The body of the function compares the hash of the password provided by the user via the login form with the hash of the password in the CFP_PASSWORD environment variable. If they match, they've entered the right password, so we redirect them to the home page while also setting a cookie with the password's hash as the value.

Otherwise, we'll redirect to the home page with the ?error=1 query param set, which in our template we use to show an error message.

The cookie we set has an expiration time of one week by default (which can be customized in the constants.ts file). The cookie will be included on every subsequent request to our site, and as long as it has the correct value, it will pass the condition on the _middleware.ts function, which will serve the request page directly without asking for the password again.

Setting the Password

The last thing we need to do is create the CFP_PASSWORD environment variable with the password we want to use to protect our site. You can do this on your Page's site Dashboard under Settings -> Environment Variables. You can set a different password for the Production and Preview environments if you want to.

Changing the Password

Our simple authentication server doesn't have actual "sessions", so there's nothing to invalidate if you decide to change the CFP_PASSWORD environment variable with a different password.

Changing the password will cause the hash from the cookie to no longer match the hash on the server, which will in turn prompt the user for the new password the next time they try to access a page.

Running Locally

To run your functions locally and test the password-protection on your own computer, you can use the wrangler CLI using npx:

npx wrangler pages dev build -b CFP_PASSWORD=password

Notice that you'll need to pass the CFP_PASSWORD environment variable when running the CLI command. If you don't pass it, the site will be served but it will not be password-protected.

And that's all I've got!

I hope you find this article and the example project useful. If you give it a try on your own Pages site, please let me know how it goes in the comments!

Thank you for reading~ <3

Getting Started with Lighthouse User Flows

Maxi Ferreira — Fri, 19 Nov 2021 22:37:52 +0000

The Google Chrome Team recently announced two big features coming to Lighthouse 9.0 and Chrome DevTools: User Flow Reports in Lighthouse, and a new Recorder panel in DevTools that can capture and replay user journeys with just a few clicks.

I've been experimenting with both of these tools for the past couple of weeks, and I've been genuinely impressed by how powerful they are and the possibilities they bring when you use them together.

In this post, I want to share a quick overview of what these features are and how they work, and finally walk you through an example that combines them to unlock their full potential. Let's dive in!

Lighthouse User Flow Reports

Unlike traditional Lighthouse reports (which only audit a website during its initial page-load), user flow reports can analyze a page at any point during its life-cycle. We can take "snapshots" of a page at a particular moment, or even collect metrics over a period of time that includes user interactions.

User flows are available as a new API in the Lighthouse Node module, and we can use them alongside tools like Puppeteer which allow us to control the browser and trigger synthetic events programmatically.

Here's an example of how we can generate a user flow report using Puppeteer and the Lighthouse API (you can see the complete code here).

async function captureReport() {
  // Puppeteer initialization
  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  // Start user flow
  const flow = await lighthouse.startFlow(page, { name: 'My User Flow' });

  // ... Caputure reports here ...

  // End user flow
  return flow.generateReport();
}

Within a user flow, there are three types of reports that we can capture:

Navigations – to audit cold and warm page-loads,
Snapshots – to audit the exact state of the page at any point in time, and
Timespans – to audit a page during any period of time.

We're going to see concrete examples of each one of them in the last section, but here's a quick overview of what they do and how their APIs look like.

Navigations

These are the standard Lighthouse reports that audit a page during page-load, except that now we can measure both cold page-loads (clearing caches and local storage), and warm page-loads (without clearing the cache). We can even capture multiple navigation reports as part of the same user flow report see how they compare.

This is how we can capture a navigation report with this new API:

await flow.navigate('https://www.nytimes.com')

We can also give the report a descriptive name with the stepName option:

await flow.navigate('https://www.nytimes.com', {
    stepName: 'Cold navigation'
})

And we can capture a warm load by setting the disableStorageReset flag:

await flow.navigate('https://www.nytimes.com', {
    stepName: 'Warm navigation',
    configContext: {
        settingsOverrides: { disableStorageReset: true },
    }
})

Snapshots

We can take a snapshot at any point during the user flow, and Lighthouse will analyze the page in its exact state. This is useful for when we want to audit a particular state of the UI that only appears after a user interaction – like a modal that shows up when the user clicks a button.

await flow.snapshot({ stepName: 'Checkout modal opened' });

Since we're only analyzing a single moment and not a period of time, the metrics in the snapshot report are not terribly useful for performance, but they're a great way to get accessibility and best practices insights based on the state of the page after the user interacts with it, which is something that wasn't possible before.

Timestamps

These reports audit a website over a period of time, which can contain user interactions as well. From a performance perspective, they're useful to measure Total Blocking Time (TBT) and Cumulative Layout Shift (CLS) while a user interacts with a page.


await flow.startTimespan({ stepName: 'Checkout flow' });

// ... user interactions here ...

await flow.endTimespan();

Measuring CLS beyond the initial page is particularly useful because it gives us a more accurate measure of this metric in the lab, that is closer to what we'll see in our field data.

For a much more detailed overview of Lighthouse user flows with complete code examples, I highly recommend checking out the official tutorial on web.dev.

Chrome DevTools Recorder Panel

The Recorder panel is a new feature coming to Chrome DevTools (currently available in Chrome 97), which allow us to record and replay user journeys with just a few clicks.

At the time of writing, the Recorder panel is only available in the Chrome Dev and Canary builds, so make sure you have one of those installed if you'd like to follow along.

You can find the Recorder panel in DevTools under More options > More tools > Recorder, or by opening the Command Menu (with Cmd + Shift + P) and searching for Recorder.

With the Recorder panel opened, you can click the Start new recording button, give the recording a name, and start interacting with the page in any way you want (for example, completing an sign up or checkout flow). Once you're done with the recording, you'll be able to replay it, modify it, run a performance profile for the entire journey, or export the recording as a Puppeteer script.

This last feature is what we're mostly interested in. We can use the auto-generated Puppeteer script as a starting point for creating user flow reports with Lighthouse, which will save us a ton of time and effort. We'll explore this approach next.

Lighthouse Reports on User Journeys

Now that we've seen what Lighthouse user flow reports are and how we can record user journeys and export them as Puppeteer scripts with the DevTools Recorder panel, let's explore how we can use them together to capture a user flow report based on a user journey.

The process is simple: we'll record a user journey in DevTools, export it as a Puppeteer script, and we'll modify the script by adding a few calls to the Lighthouse user flow APIs in the right places. In the end, we'll be able to run the script with Node.js and get shiny new User Flow Report back.

1. Project setup

The first thing we need to do is initialize a new npm project (ideally in a new folder) and install the dependencies we're going to be using:

mkdir lighthouse-reports
cd lighthouse-reports
npm init -y
npm install lighthouse puppeteer open --save

We'll use the open package so that we can automatically open the HTML report in the browser once the script finishes, but this is an optional dependency (and you definitely don't need it if your running the script in CI).

2. Record and export a user journey

For this tutorial, I'm going to use this coffee shopping demo app (borrowed from Google's documentation) to record a simple user journey: adding a couple of items to the cart, navigating to the shopping cart, and going through the (fake) checkout process.

I encourage you to do something similar to keep things simple, but you can of course use any website you want and go wild with your user journey. Simply hit the "Start recording" button on the Recorder panel and start interacting with the page by clicking around, scrolling, or filling out forms. Make sure you stop the recording once you're done.

Once you've finished recording, make sure you can replay it by hitting the Replay button on the top right. This is important. If the flow can't be replayed consistently, you might run into issues generating the Lighthouse reports later on.

For more details on how to use the Recorder panel, check you this great article in the Chrome DevTools documentation site.

Once you're happy with your recording, export the user flow as a Puppeteer script by clicking the Export icon on the top (be careful not to click the delete icon by mistake, they're dangerously close together!), and save it in the project folder as user-flow.js.

3. Edit the script

Now comes the fun part. If you open the user-flow.js script, you'll find that it consists of a bunch of utility functions at the top, followed by a series of code blocks, each one representing a "step" in our user journey (clicks, scrolls, keyboard events, etc.)

We're going to make a few modifications to this script to generate a Lighthouse user flow report consisting of four "sub-reports":

Two navigation reports (to measure both cold and warm page-loads),
A snapshot report to capture the state of the page when the checkout modal is open, and
A timespan report to capture the entire checkout flow.

You might find it easier to see the modifications to the script in this annotated file or in this diff, but if you prefer a step-by-step guide, just read on and code along!

3.1 Import dependencies

First off, let's import the rest of our dependencies right after the puppeteer require in the first line:

const open = require('open');
const fs = require('fs');
const lighthouse = require('lighthouse/lighthouse-core/fraggle-rock/api.js');

3.2 Create the user flow

Right at the top of the script's main function, you'll find a couple of lines that create the Puppeteer browser and page instances. We'll create our user flow instance right after that:

const flow = await lighthouse.startFlow(page, { name: 'My User Flow' });

3.3 Add the Navigation reports

Now we need to scroll down to where the code blocks start. We'll add the two navigation reports right after the block with the targetPage.goto('https://coffee-cart.netlify.app/') call:

// Cold navigation report
{
  const targetPage = page;
  await flow.navigate('https://coffee-cart.netlify.app/', {
    stepName: 'Cold navigation'
  });
}

// Warm navigation report
{
  const targetPage = page;
  await flow.navigate('https://coffee-cart.netlify.app/', {
    stepName: 'Warm navigation',
    configContext: {
      settingsOverrides: { disableStorageReset: true },
    }
  });
}

3.4 Add the Snapshot report

You can add this call between any two steps in the script, but for demonstration purposes, we want to take the snapshot once the Checkout modal opens. Add the following code right after the code block with the waitForSelector call that waits for the "aria/Proceed to checkout" element:

{
  await flow.snapshot({ stepName: 'Checkout modal opened' });
}

3.5 Add the Timespan report

We'll start the timespan right after the snapshot() call from the previous step:

{
  await flow.startTimespan({ stepName: 'Checkout flow' });
}

And we'll end it at the end of the flow, right before the call to browser.close():

{
  await flow.endTimespan();
}

3.6 Generate the user flow report

Finally, we need to generate the report, save it as an HTML file, and open it in the browser. Add the following lines right before the end of the main function (after the call to browser.close()):

const reportPath = __dirname + '/user-flow.report.html';
const report = flow.generateReport();
fs.writeFileSync(reportPath, report);
open(reportPath, { wait: false });

And we're done! If you save and run the script (with node user-flow.js), you should see the report coming up on your browser after a few moments.

If you didn't follow the steps with me but would like to see how the report looks like, you can open the live report and play with it here. You'll see a timeline with our four reports in the order we captured them, and you can click in each one for a more detailed view. How cool is that?!

Final thoughts

Lighthouse user flows and the new DevTools Recorder panel are like milk and cookies: they're both amazing on their own, but they're definitely better together.

The new Lighthouse APIs enable new ways to measure the performance and accessibility of our websites, generating lab data that is more representative of what real users experience in the field. And with the auto-generated Puppeteer scripts, the process of capturing these data is a breeze.

The Recorder panel also has many interesting use cases in addition to measuring performance. We can use the Puppeteer scripts as a starting point for running automated end-to-end tests, or even use them directly as a quick way to assert that user journeys can be completed correctly. And of course, since these are just Node scripts, we can run them as an additional step in our CI pipelines.

Finally, I think it's important to keep in mind that these features are still quite young, so you may run into a few issues here and there (if you do, be sure to share your feedback with the Chrome team!). I still encourage you to give them a try and explore the cool things you can do with them.

Resources

For more information about Lighthouse user flow reports, check out the official tutorial on web.dev.
For detailed instructions about the DevTools Recorder panel, take a look at the official documentation on Chrome Developers.

I would love to hear your thoughts about this process if you give it a try! Please let me know in the comments, or reach out on Twitter.

Thank you for reading ❤️