Authenticating Vuepress Apps with Auth0

TL;DR: Vuepress is a static site generator that was initially developed privately for the documentation needs of the Vue.js framework. It was later made public for anyone to use and optimized for writing technical documentation. Vuepress is built on Vue.js and uses markdown for writing pages, so you have the simplicity of content writing with markdown combined with the powerful capabilities of the Vue.js framework. Vuepress also comes bundled with a Vue-powered theming system and a Plugin API for extending its capabilities. In this tutorial, you will learn and demonstrate how to authenticate Vuepress sites using Auth0.

Prerequisites

To get started, you will need to have a few things set up:

1. Node.js installed on your system (version >= 10 is recommended)
2. Yarn installed.

With these in place, you are good to go.

Creating the Auth0 Application

First, you will set up your Auth0 application to handle authentication in your Svelte application. If you don't already have an Auth0 account, you can sign up for a free account here.

Once logged in, click on Applications on the left-hand side menu. On the Applications page, click on the big orange CREATE APPLICATION button.

On the Create Application dialog that pops up, enter an appropriate name for your application and select Single Page Web Applications from the options below the application name field.

Click the Create button to complete the process.

After the successful creation of the application, go to the Settings section of your newly created app. In the Allowed Callback URLs, Allowed Web Origins, Allowed Logout URLs, and Allowed Origins (CORS) fields, enter http://localhost:8080. This address is the default address of the Vuepress site you will be creating later on. Make sure you update these settings once your application moves to production.

Once you're done entering these values, scroll down and hit the SAVE CHANGES button.

Scaffolding the Vuepress Project

Your next task is to scaffold a new Vuepress project by running the following command:

yarn create vuepress-site my-vuepress-site

This will prompt you to answer a few questions to set up your site. You can use the answers below for this exercise for quickly scaffolding a demo project:

• What's the name of your project?: my-vuepress-site
• What's the description of your project?: A sample App for Authentication with Auth0
• What's your email?: demo@test.com
• What's your name?: Vuepress User
• What's the repo of your project?: my-vuepress-site

This should then scaffold a new Vuepress project inside the my-vuepress-site folder. By default, the scaffolding process packs all the project's code into a docs folder. Move all the contents of the docs folder into the root project folder and delete the docs folder.

Next, install the project dependencies by running yarn at the root of the project. Once the dependencies are completely downloaded, run the Vuepress app by running the following command:

yarn dev

This will compile the code and boot up a development server at http://localhost:8080. Visit this URL in your browser, and you will see a default home page similar to the one below:

Setting Up Authentication with Auth0

Creating the Authentication Service

The first step to adding authentication to the application using Auth0 is to bring in the Auth0 javascript SPA library. Go to src/.vuepress/config.js and add a new entry to the end of the head array as shown below:

// src/.vuepress/config.js

...
head : [
  ....,
  ["script", {src : "https://cdn.auth0.com/js/auth0-spa-js/1.13/auth0-spa-js.production.js"}]
]

With this in place, the next task is to create an authentication service. Inside the src/.vuepress folder, create a new folder auth and in this folder, create the file auth_config.js and enter the following code:

// src/auth/auth_config.js
const config = {
  domain: "YOUR_AUTH0_DOMAIN",
  clientId: "YOUR_CLIENT_ID"
};

export default config;

Ensure you replace YOUR_AUTH0_DOMAIN with your Auth0 domain and YOUR_CLIENT_ID with the Client ID of your application. To find these values, go back into the Applications page of your Auth0 dashboard. Find the application you created at the beginning of the tutorial, and click on "Settings." You'll find Domain and Client ID listed there.

Make sure you also add this file to your .gitignore file so that you don't mistakenly push your details to a public repository.

With this file in place, you can now create the authentication service. Create the file index.js inside the auth folder and place the following code in it:

// src/auth/index.js
import config from "./auth_config";

async function createClient() {
  let auth0Client = await createAuth0Client({
    domain: config.domain,
    client_id: config.clientId
  });

  return auth0Client;
}

async function loginWithPopup(client, options) {
  try {
    await client.loginWithPopup(options);
  } catch (e) {
    // eslint-disable-next-line
    console.error(e);
  }
}

function logout(client) {
  return client.logout();
}

const auth = {
  createClient,
  loginWithPopup,
  logout
};

export default auth;

The above service exports 3 methods that do the following:

• createClient: Uses Auth0's createAuth0Client function and the authentication configuration to create a new authentication client and returns it.
• loginWithPopup: Takes in an authentication client instance with defined options and uses these to call the loginWithPopup on the client to sign-in and user. It then sets isAuthenticated to true and user to the user details returned by the logged-in client.
• logout: This is simply a proxy to the Auth0 client's logout method that ends a logged-in user's session.

Creating the Login button component

Next, you need to create a LoginButton component that would hold, you guessed it, the sign-in logic for the application. Being a reusable component, it can be used in different parts of the application. Inside src/.vuepress/components folder, create the file LoginButton.vue and enter the following code:

<template>
    <button @click="login()">Login</button>
</template>

<script>
import auth from "../auth";
export default {
    props : ['client'],
    methods : {
        async login () {
            await auth.loginWithPopup(this.client);

            this.$emit('login-complete');
        }
    }
}
</script>

The component above takes in the Auth0 client instance as a prop and uses it to call the loginWithPopup method from the authentication service. Once the login process is complete, it emits a login-complete event to the calling code to take action. The template contains a Login button that calls the login method defined in the methods object of the component.

Creating the Logout button component

Just as you have created a reusable login component, you will also be creating a component for signing out of the application also.

In the same location as the LoginButton component, create a new file LogoutButton.vue and enter the following code:

<template>
    <button @click="logout()">Log Out</button>
</template>

<script>
import auth from "../auth";
export default {
    props : ['client'],
    methods : {
        async logout () {

            await auth.logout(this.client);
        }
    }
}
</script>

Similar to LoginButton, the LogoutButton component also takes in the client as a prop and uses it to call the logout on the authentication service.

Adding Authentication to the Application

It's now time to bring everything together to add authentication to the application. Locate the file src/index.md and replace the content with the following code:

---
home: true
footer: Made by Auth0 User with ❤️
---

<template>
  <div class="main-content">
    <div v-if="user">
      <p align="center">
        Hi {{user.given_name}} {{user.family_name}}, Welcome to the Vuepress Blog
      </p>
      <p align="center">
        <LogoutButton :client="auth0client" />
      </p>
    </div>
    <div v-else>
      <p align="center">
        You are currently not logged-in to the Application. Please use the login button below to sign in
      </p>
      <p align="center">
        <LoginButton :client="auth0client" @login-complete="getUser()" />
      </p>
    </div>
  </div>

</template>

<script>
import auth from "./.vuepress/auth";
import LoginButton from "./.vuepress/components/LoginButton";
import LogoutButton from "./.vuepress/components/LogoutButton";

export default {
  data() {
    return {
      auth0client : null,
      user : null
    }
  },
  async mounted(){
    this.auth0client = await auth.createClient();

    this.user = await this.auth0client.getUser();
  },
  methods : {
    async login () {
      await auth.loginWithPopup(this.auth0client);
    },
    async getUser(){
      this.user = await this.auth0client.getUser();
    }
  }
}
</script>

The code above contains two sections, one for authenticated users and the other for non-authenticated users using the v-if directive with a user variable defined in the data object.

The authenticated section contains the login button, while the non-authenticated section contains the logout button. In the script section, the authentication service, LoginButton, and LogoutButton components are imported.

The LoginButton component handles the login-complete event by calling the getUser function that fetches user data once the login process is complete.

In the mounted lifecycle method, the Auth0 client is initialized and set in the auth0Client data variable; the user details are also fetched from the Auth0 service by calling getUser on the Auth0 client instance. If there is a user session active, the user data variable will contain the data and validate the authenticated state.

In the methods object, the login and getUser methods are defined to call the login method of the authentication service and fetch the user, respectively.

Running the Application

It's now time to put the application to test. Save all changes and relaunch the application using yarn dev; you will see a screen like the one below:

Now, click the Login button to prompt the Auth0 authentication dialog box as shown below:

The dialog might ask that you give the application permissions; go ahead and approve this request to complete the sign-in process. Once signed in, your homepage should now display the authenticated message as shown below:

If you reload the page, the user data will be requested in the mounted lifecycle hook to fetch the user and persist the session. Click the logout button to end the user session; once logged out, the login button is once again displayed.

Conclusion

Vuepress is an amazing tool for generating static sites with Vue.js, and in this tutorial, you have learned and demonstrated how to authenticate users on Vuepress sites. Rolling your own authentication from scratch for every application built can be a very laborious and routine task, but with Auth0, it's a breeze.

Happy Coding :)