How to secure your Remix app routes with Cerbos?

Published by Mark Schenouda on March 06, 2023

In this tutorial, we will show you how to secure your Remix app routes with Cerbos. Cerbos is an open-source policy engine for authorizing access to resources. We gonna walk you through the steps of applying authorization in your Remix app with Cerbos. We will also show you how to use Cerbos to secure your routes and APIs. For more information checkout The Cerbos + Remix showcase on Github

What’s Cerbos?

Cerbos is an open-source policy engine for authorizing access to resources. It is designed to be used in microservices and serverless environments. Cerbos is a policy engine that can be used to enforce authorization policies in your application. It is designed to be used in microservices and serverless environments.

When you integrate Cerbos with your Remix app you will enjoy some important advantages in terms of access control, security and the user experience. Those advantages include:

Centralized policy management

Cerbos enables centralized policy management that allows you to manage access policies from a single central location. This provides various benefits including:

Simplifying your Remix code: By integrating Cerbos you are able to remove authorization from your Remix code. This, in turn, greatly simplifies the Remix code making it easier to troubleshoot and modify as your needs change.
Application-wide policy definitions: Cerbos enables you to define all access policies for your Remix app and related services in a single place, thereby reducing the chance of redundancies and ensuring consistent application of those policies.
Unlimited scalability: As your needs evolve and grow and the complexity and number of users of your Remix app grow, Cerbos allows you to adapt and scale effortlessly without having to place unhealthy burdens on your Remix server.

Fine-grained access control

Fine-grained access control in Cerbos is expressed through:

Attributes: Cerbos enables you to grant access based on user roles, the particular digital asset, permissions granted the user and other attributes.
Dynamic considerations: Access decisions can be tailored to account for real-time considerations such as geographical location, API usage patterns, time of day and whether the user is attempting access via a company computer, personal smartphone or other device.
Comprehensive data integration: Cerbos allows you to achieve unparalleled levels of fine-grained control by integrating data from external databases and other resources into your access policies.

Additional benefits

Improved developer experience: Cerbos provides an enhanced and simplified developer experience that enables managers not conversant in computer languages to better comprehend access policies being implemented.
Seamless integration of microservices architectures: Microservices architectures can include shopping cart services, inventory management services, content management services, streaming services, rider and driver apps, payment services, routing services and much more.
Continuous development/community support: Cerbos’ open source nature typically means reduced maintenance costs when compared to proprietary software and greater flexibility in adapting the software to your particular needs.

By integrating Cerbos with your Remix application you will be able to build a more secure, user friendly, flexible and scalable application that will serve your ever-evolving needs. Although the precise benefits you enjoy will depend to some extent on the nature of your application, there is no doubt Cerbos will enable it to be more secure, more versatile and more cost-effective.

Authentication vs authorization

Authentication is the process of verifying who a user is. It is the process of identifying users if they signed in or not like Clerk , AWS Amplify Authentication and Auth0. However, Cerbos is to handle authorization. Authorization is the process of verifying what a user can access. It is the process of giving permissions to users to access resources. Authentication and authorization are two separate but equally important concepts when it comes to system security. Understanding the difference between them is essential for creating a secure system. Proper configuration of both authentication and authorization is necessary for a secure solution. here's an example that illustrates the difference between authorization and authentication:

Imagine you're at a party and you're trying to get into the VIP section. The bouncer at the door asks you to show your ID before he lets you in. In this scenario, the act of showing your ID is the authentication step, where you're proving your identity to the bouncer. Once the bouncer verifies your ID and confirms that you're on the guest list, he'll allow you to enter the VIP section. This is the authorization step, where the bouncer is granting you access to a restricted area based on your verified identity.

To summarize, authentication is the act of proving your identity, while authorization is the act of granting or denying access to a resource or area based on your authenticated identity. In this example, the bouncer used authentication to verify the guest's identity and authorization to grant them access to the VIP section.

Authorization challenges

Authorization is a very important part of any application. However, it is not an easy task to implement it. There are many challenges when it comes to authorization. Some of them are:

Scalability:
Policy management:
Monitoring and reporting:
Distributed IT systems:

How do Remix routes work?

Routing in Remix is very unique and powerful. Not like most of the other frameworks where you have to define routes in a separate file for each page, Remix does that and more. Remix introduced the nested routes concept. You can split your route into multiple files each is responsible for a smaller section in the page. This makes it easy to manage your routes and also makes it easy to add routes to your application. Also if a route crashes, it will not crash the whole application. It will only crash that route. This makes it easy to develop large applications. This interactive example in the Remix home page explained it very well

Remix Cerbos integration

In this section, we are going to introduce Cerbos to our Remix application and see how easily it can be used to add an Authorization layer to make our app more secure and flexible, you can connect to Cerbos server in two ways:

Using the GRPC client
Using the HTTP client

But, what is the difference between the two?

The GRPC client is faster and more efficient than the HTTP client. But, the GRPC client is only available in NodeJS. So, if you are using Remix with Deno, you can only use the HTTP client, however both clients are similar and you can use them in the same way.

It's prefered to use the GRPC client, you need to install the @cerbos/grpc package.

npm install @cerbos/grpc

Or if your server doesn't support GRPC, use the HTTP client. Install the @cerbos/http package.

npm install @cerbos/http

Then, you need to create a client instance. You can do that by importing the client from the package you installed.

import { GRPC } from "@cerbos/grpc";

const cerbos = new GRPC("localhost:3593", { tls: false });

the tls option is set to false because we are using a local server. If you are using a remote server, you need to set it to true.

TLS stands for Transport Layer Security It is a widely adopted security protocol designed to facilitate privacy and data security for communications over the Internet. A primary use case of TLS is encrypting the communication between web applications and servers, such as web browsers loading a website.

Or if you are using the HTTP client, you need to import it like this:

import { HTTP } from "@cerbos/http";

const cerbos = new HTTP("http://localhost:3593");

Guarded pages

When Remix server receives a request, it prepares the page and then sends it to the client. But, what if you want to check if the user is authenticated and has the correct permission t before sending the page to the client? In Remix we can do so by implementing the loader function.

The first step required to achieve this goal is to create a guard that will throw a 403 Error is the user is unauthenticated.

import { json } from '@remix-run/node';
import { useLoaderData } from '@remix-run/react';
import { cerbos } from '../cerbos';
import { user } from 'MyMockedAuth';

export const loader = async () => {

  if (!user) {
    return json({ redirect: "/login" }, { status: 403 });
  }

  return json({ message: "Hello world!" });
};

At this stage, the route will be guarded and just shown to people are are authenticated. This is great for normal pages, but what if you have a specific page that may require further permission, like an Admin dashboard or ensuring sensitive document are just accessible by its author or a super admin. To do so, we are going to add cerbos to handle a layer of authorization:

import { json } from '@remix-run/node';
import { useLoaderData } from '@remix-run/react';
import { cerbos } from '../cerbos';
import { user } from 'MyMockedAuth';

export const loader = async () => {

  if (!user) {
    return json({ redirect: "/login" }, { status: 403 });
  }

  const isAuthorizated = await cerbos.isAllowed({
   principal: {
    id: user.email,
    roles: [user.role],
    attributes: { tier: user.tier },
  },
  resource: {
    kind: "document",
    id: "1",
    attributes: { owner: "user@example.com" },
  },
  action: "view",
  });

  if (!isAuthorizated) {
    return json({ redirect: "/login" }, { status: 403 });
  }

  return json({ message: "Hello world!" });
};

In the example above, we are using the isAllowed function to check if the user is authenticated or not. The isAllowed function takes an object as an argument. The object has the following properties:

principal: is the user who is trying to access the resource. It has the following properties:
id: Id of the principal. It can be an email, username, or any other unique identifier.
roles: The roles of the principal. It can be an array of roles.
attributes: The attributes of the principal. It can be an object of attributes.
resource: The resourse the user is trying to access. It has the following properties:
kind: The type of the resource. It can be any string.
id: The id of the resource. It can be any string.
attributes: The attributes of the resource. It can be an object of attributes.
action: The action is the action the user is trying to perform on the resource. It can be any string.

If the user is authenticated, the isAllowed function will return true. If the user is not authenticated, the isAllowed function will return false.

Head over to this Remix Cerbos showcase for an in-depth look at how Cerbos can help you easily manage your application's access control policies!

Guarded APIs

Remix routing system isn't only capable of building pages, it can also build APIs to use for different apps like mobile apps. You can create an API by creating a route file and exporting a load function from it. The load function will be called when the API is called. You can use the json function to return a JSON response.

For example, if you want to create an API that returns the user's name, you can do that like this:

import { json } from '@remix-run/node';
import { cerbos } from '../cerbos';

export const loader = async () => {
  const isAuthorizated = await cerbos.isAllowed({
   principal: {
    id: "user@example.com",
    roles: ["USER"],
    attributes: { tier: "PREMIUM" },
  },
  resource: {
    kind: "document",
    id: "1",
    attributes: { owner: "user@example.com" },
  },
  action: "view",
  });

    if (!isAuthorizated) {
        return json({ message: "You are not authenticated" }, { status: 403 });
    }

    return json({ name: "John Doe" });
};

Debug cerbos

Because Cerbos is a policy engine and it runs on a separate server (mostly), it's hard to debug it. But in this section, we will show you ways to debug Cerbos.

Audit block

The audit block configures the audit logging settings for the Cerbos instance and is defined in the audit section of the configuration file. The audit block has the following property:

audit:
  enabled: true

to learn more about the audit block, you can read the Cerbos Audit Block Documentation.

Debuging deployed instances

You can debug deployed instances by tracing the requests. Cerbos supports distributed tracing to provide insights into application performance and request lifecycle.

Tracing block configures the tracing settings for the Cerbos instance and is defined in the tracing section of the configuration file. The tracing block has the following properties:

tracing:
  serviceName: cerbos
  sampleProbability: 0.5
  exporter: jaeger
  jaeger:
    agentEndpoint: "localhost:6831"

Set sampleProbability to a value between 0.0 and 1.0. Setting the probability to 1.0 makes Cerbos capture tracing information for all requests and setting it to 0.0 disables capturing any traces.

To learn more about the tracing block, you can read the Cerbos Tracing Block Documentation.

Conclusion

In this tutorial, we learned what is Cerbos and how Remix routes work. We also discussed how to use Cerbos with Remix to guard the app’s routes for both pages and APIs, and finally, we learned how to debug the Cerbos server in multiple ways.

DOCUMENTATION

GUIDE

INTEGRATION

Book a free Policy Workshop to discuss your requirements and get your first policy written by the Cerbos team