Nuxt authorization: How to implement fine-grained access control
Tags: webdev, programming, nuxt, tutorial
Published: 2024-01-15 10:12:26

In this tutorial you will learn how to use [Cerbos](https://cerbos.dev/) to add fine-grained access control to any [Nuxt](https://nuxt.com/) web application, simplifying authorization as a result.

Check out a working example of a Cerbos integration in a Nuxt application on [GitHub](https://github.com/cerbos/nuxtjs3-cerbos-iron-session).


## Prerequisites
* A working [Nuxt](https://nuxt.com/docs/getting-started/introduction) web application
* [Docker](https://www.docker.com/) installed in your working environment


## Steps
Having met the prerequisites, the steps are as follows:
* Set up the Cerbos policy repository
* Set up the Cerbos PDP
* Add the Cerbos client to your Nuxt application
* Create an API route
* Make permission checks across your Nuxt pages and components

## Set up the Cerbos policy repository
A Cerbos policy repository is a collection of YAML files that define access control rules for your application. It's essential for specifying who can do what within your app. These policies dictate the actions different user roles can perform on various resources. 

A resource is an application-specific concept that applies to anything that requires access rules. For example, a document is a resource that can be altered, viewed, deleted, etc. by different users depending on the access control rules. Read more about the best practices for structuring your policy repository in our [documentation](https://docs.cerbos.dev/cerbos/latest/policies/best_practices.html#_policy_repository_layout).

Your Cerbos policy repository can be stored on your disk, on git, or any S3-compatible storage system. To set up a Cerbos policy repository on the disk, within the Nuxt application, do the following:
* In your project's root, create a `cerbos` folder, then a `policies` sub-folder within it.
* Within the `policies` folder, create a YAML file which will contain the rules for performing permission checks in your Nuxt application. For example, create a `documents.yaml` resource policy file.
* Populate the `documents.yaml` file with rules for actions that can be performed on a document, check the example below. Learn more in Cerbos [resource policies documentation](https://docs.cerbos.dev/cerbos/latest/policies/resource_policies).

```yml
---
apiVersion: api.cerbos.dev/v1
resourcePolicy:
  version: default
  resource: document
  rules:
    - actions: ['view', 'change', 'destroy']
      effect: EFFECT_ALLOW
      roles:
        - admin
    - actions: ['view', 'change']
      effect: EFFECT_ALLOW
      roles:
        - user
      condition:
        match:
          expr: request.resource.attr.author == request.principal.id
```

Now we’ve defined a simple resource policy file `documents.yaml` which allows admin users to `view`, `change`, and `destroy` any `document` resource within the system. Non-admin users are allowed to `view` and `change` the `document` resource if the condition is matched that the given user is also the document author.

Note that a separate policy file is expected for different types of resources and principals we want to create policies about. To showcase this, in the linked demo [GitHub ](https://github.com/cerbos/nuxtjs3-cerbos-iron-session)example there is a `contacts.yaml` resource policy file alongside the `documents.yaml` one.

Cerbos policy repository can be further enriched with defining [context-aware roles](https://docs.cerbos.dev/cerbos/latest/policies/derived_roles), [schemas](https://docs.cerbos.dev/cerbos/latest/policies/schemas), [scopes](https://docs.cerbos.dev/cerbos/latest/policies/scoped_policies), [tests](https://docs.cerbos.dev/cerbos/latest/policies/compile), and various other features explained in comprehensive [Cerbos documentation](https://docs.cerbos.dev/cerbos/latest/policies/).


## Set up the Cerbos PDP

Cerbos PDP is the Policy Decision Point, a component that evaluates application requests against authZ policies to make access decisions; determining whether a user action on a resource is allowed.

In this demo, we’ll set a Cerbos PDP within your repository, as a separate module, using the previously created `cerbos` directory. To run Cerbos PDP locally, do the following:

* Create a Cerbos PDP server configuration file within `cerbos` directory. You can name it `conf.yaml`.
* For simplest configuration, within the `conf.yaml` file define the port exposed for listening to HTTP (and/or gRPC) requests and the location of the Cerbos policy repository. The simplest `conf.yaml` file would look like the one shown below:

```yml
---
server:
  httpListenAddr: ":3592"
storage:
  driver: "disk"
  disk:
    directory: /policies
```

For more robust configuration, make sure to check our [Cerbos PDP configuration documentation](https://docs.cerbos.dev/cerbos/latest/configuration/).

Your file Cerbos-related file structure now might look like the following:

```sh
.
├── cerbos
│   └── policies
│       ├── documents.yaml
│       └── contacts.yaml
└── conf.yaml
```

Position your terminal within the `cerbos` directory. If you have Docker installed, you can simply run the following command to start Cerbos PDP locally in a Docker container.

```sh
docker run --rm --name cerbos -t \
  -v $(pwd)/policies:/policies \
  -p 3592:3592 \
  ghcr.io/cerbos/cerbos:latest server
  --config=conf.yaml 
```

Cerbos PDP runs as a separate process from your Nuxt application. Here, we ran it as a standalone service within a docker container, but this is not a requirement. Cerbos is designed to be adaptable to your infrastructure. So if you want to run Cerbos PDP as a service, a sidecar, or a lambda function, for instance, check the Cerbos deployment documentation to learn more about Cerbos [deployment patterns](https://docs.cerbos.dev/cerbos/latest/deployment/).

## Add the Cerbos client to your Nuxt application

Adding a Cerbos client is essential for simplifying the communication between your Nuxt application and the Cerbos PDP. The Client will allow you to make user permission checks from your Nuxt application in an elegant manner.

To add the Cerbos client to your Nuxt application, follow these steps:
* Select the Cerbos client you want to use.
    * Choose between `@cerbos/http` for HTTP interactions or `@cerbos/grpc` for gRPC in server-side applications.
* Install the chosen client package using the `npm install` command
* In your Nuxt project, within the `utils` folder, create a utility file `cerbos.ts` to instantiate the Cerbos client.
* Export the instance for reuse across your Nuxt application.

The above mentioned `cerbos.ts` file would look like this:

```ts
import { HTTP as Cerbos} from "@cerbos/http";

export const cerbos = new Cerbos("localhost:3592");
```

## Create an API route

A Nuxt API route is a feature in Nuxt.js used to define server-side logic and handle HTTP requests within the Nuxt application. These routes allow developers to create various back-end functionalities in the Nuxt project, such as data fetching, form submissions, or in this case authorization.

To create an API route in Nuxt for Cerbos permission checks:
* Create an `isAllowed.ts` file within the `server/api` folder of your Nuxt application.
* Define and export the event handler
    * In `isAllowed.ts` file, use `defineEventHandler` from `nuxt-helpers` to export your API handling function.
    * Within this function, call the Cerbos `.isAllowed(...)` method to check user permissions based on the request's user and resource details.

```ts
import { cerbos } from "../utils/cerbos";
// Pull the user info from the session in your Nuxt applications

const user = {
    id: "000012345",
    roles: ["user"]
  }

export default defineEventHandler(async (event) => {
    const query = getQuery(event)

    const document = {
        id: query.documentId as string
    }

    const requestBody = {
        principal: user,
        resource: { // Pull the resource info from the data storage in your Nuxt applications. Pass Resource ID within the event as a query param, like we did here.
          kind: "document",
          id: document.id,
          attributes: {
            author: "000012347"
          }
        },
        action: "approve"
      }    

    const isAllowed = await cerbos.isAllowed(requestBody)
    .catch( (error)=> {
      console.log( error );
      return false;
    })
})
```

That’s it! You can now universally call this API as `/api/isAllowed` across your Nuxt application pages and components.


## Make permission checks across your Nuxt pages and components

Let’s see the usage of Cerbos permission checks across your Nuxt application pages in action. Let’s say we’ve created a page for each of our documents on the path `/documents/[id]`. To do that:
* Create  a `documents` folder under the `pages` folder of your application.
* Within the `documents` folder, create an `[id].vue` file.

Nuxt offers route validation via the `validate` property in `definePageMeta()` in each page you wish to validate. The `validate` property accepts the route as an argument. 

To use the `/api/isAllowed` route defined in the previous step you can add the following snippet to the bottom of your recently created `[id].vue` (or any other vue) file.

```ts
definePageMeta({
  validate: async (route) => {
    const { data: isAllowed } = await useFetch('/api/isAllowed', 
    {
      headers: useRequestHeaders(),
      query: { documentId: route.params.id }
    })
    return isAllowed.value;
  }
})

```

It’s that simple!

## To sum up

All you have to do to use Cerbos authorization in your Nuxt application is to:
* create Cerbos policies you will be using to make decisions over who should be able to do what within your application,
* run a Cerbos PDP which upon being called will be checking those policies,
* install the Cerbos client within your Nuxt application,
* create an API route to enable its usage across your Nuxt application,
* start invoking the exported API route to perform Cerbos `.isAllowed(...)` checks and determine whether your application user should be allowed to make a certain action on a certain resource.

## Further steps
In this tutorial you saw how to add fine-grained access control with Cerbos to your Nuxt applications. If you liked it make sure to check out [Cerbos Hub](https://hub.cerbos.cloud/).

Cerbos Hub saves time managing and synchronizing every Cerbos PDP and policy repository across all your applications and services. It helps connect your Cerbos policy repository and your Cerbos PDP instances and manage them collaboratively and smoothly from a single place.

We also published a series of articles with step-by-step instructions on how to [Get started with Cerbos Hub](https://cerbos.dev/blog/get-started-with-cerbos-hub). Take a look if you’re interested in seeing how it works!