Secure Your Express Application APIs in Minutes with Amazon Verified Permissions

More Info

In a recent update, Amazon Verified Permissions has introduced the @verifiedpermissions/authorization-clients-js package, an open-source tool that empowers developers to implement external fine-grained authorization for Express.js web application APIs swiftly. Express is a lightweight and versatile Node.js framework that offers a comprehensive range of features for web and mobile applications. By leveraging this standardized integration with Verified Permissions, developers can externalize authorization using up to 90% less code than if they were to create custom implementations, thus saving valuable time and enhancing application security by minimizing the amount of custom code.

The Importance of Externalizing Authorization

Traditionally, authorization has been embedded directly within application code, which is manageable for simple permissions. However, as applications grow, the need to update this embedded logic to accommodate more complex requirements often leads to code that is convoluted and hard to maintain. Increased complexity not only makes it challenging to evolve the security model but also complicates permission audits, ultimately hindering the application’s long-term maintainability.

By externalizing authorization, you can separate authorization logic from your application, resulting in multiple benefits. This shift allows development teams to concentrate on application logic while simplifying the software audit process. One effective method for externalizing authorization is through Cedar, an open-source language and software development kit (SDK) designed for formulating and enforcing authorization policies.

For instance, in a pet store application, you can define a Cedar policy that permits only users with a job level of “employee” to access the POST /pets API:

permit (
    principal,
    action in [Action::"POST /pets"], 
    resource
) when {
    principal.jobLevel = "employee"
};

Organizations can choose to manage Cedar themselves, as discussed in a previous blog post, Secure your application APIs in 5 minutes with Cedar. While self-managed Cedar provides the benefits of externalizing authorization, it also requires ongoing operational management, including version upgrades, security patches, policy management, and authorization audits. Alternatively, Verified Permissions offers a managed service for Cedar, eliminating these operational burdens. This service handles scaling, policy governance, and logs policy changes, making audits simpler.

This article will guide web application developers on using the new Express package to streamline the integration of their Express web applications with Verified Permissions. The step-by-step guide features a sample Pet Store application that demonstrates how to restrict API access based on user groups. The sample can be found in the verifiedpermissions repository on GitHub.

Overview of the Pet Store Application API

The Pet Store application manages a virtual pet store built with Express and Node.js, exposing the following APIs:

• GET /api/pets: Lists available pets
• GET /api/pets/{petId}: Retrieves a specific pet
• POST /api/pets: Adds a new pet to the store
• PUT /api/pets/{petId}: Updates an existing pet
• DELETE /api/pets/{petId}: Removes a pet from the store

This application enforces access rules based on user roles:

• Administrators: Full access to pets and management functions
• Employees: Can view, create, and update pets
• Customers: Can view pets and create new pets

Implementing Authorization for the Pet Store APIs

Now, let’s go through securing your application APIs with Verified Permissions and the new Express package. The initial version of the application, which lacks authorization, can be found in the start folder; you can use this version to follow along. The completed application is available in the finish folder.

Upon completion, your architecture will resemble the structure shown in Figure 1. It features a React frontend that utilizes Amazon Cognito for authentication. The identity token returned from Cognito is included as an authorization header in requests to the Express APIs. The Express backend, utilizing the new Verified Permissions middleware package, calls Verified Permissions to authorize user requests.

Prerequisites

Before diving in, ensure you have the following prerequisites in place:

1. Set Up the AWS CLI
   Some commands will require the AWS Command Line Interface (AWS CLI). Refer to this link for an excellent resource on installing or updating the AWS CLI.
2. Set Up an OpenID Connect Identity Provider and a Database
   The Pet Store application uses an OpenID Connect (OIDC) identity provider to manage users. For this example, utilize an Amazon Cognito user pool named PetStoreUserPool with three users: one Admin, one Employee, and one Customer. The application also employs an Amazon DynamoDB database for pet storage. You can set up Amazon Cognito and DynamoDB in your AWS account by executing the following command in the /start directory:

./scripts/setup-infrastructure.sh

This setup script will prompt you for passwords for the three users (passwords must contain at least 8 characters, including one number, one uppercase letter, and one lowercase letter). Remember to note the outputs of running this script, as you will need them in the next steps.

3. (Optional) Run the Application
   With the infrastructure set up, you can run the application. In two separate terminals, execute the following commands in the /start directory:

./scripts/run-backend-dev.sh
./scripts/run-frontend-dev.sh

You can now test the application by creating some pets.

Integrate Verified Permissions

With the prerequisites sorted out, the next step is to integrate Verified Permissions into your application. This integration can be accomplished in six steps:

1. Create a Verified Permissions policy store…

By adopting this approach, you can significantly enhance your Express application’s security while streamlining the development process.