For those new to the term, authorization and authentication can be easy to confuse. So, let's first clear up which is which. Authentication deals with logging users in and out, registering new users, determining who a user is, etc. Authorization, on the other hand, deals more with permission checking. Things like, can the user view a page, create a record, and so on.

In this series, we'll be learning AdonisJS' first-party package to handle authorization, called Bouncer. Bouncer allows us to define authorization checks in one place and use those checks anywhere within an HTTP request, including within the Edge template engine.

Prerequisites

Bouncer relies heavily on the AdonisJS Auth package. So, you're going to need to ensure you're application is using the first-party auth package in order to utilize Bouncer. You don't need an authenticated user to use it, it can work with guests, but you do need the auth package.

Starter Project

Since we need a project with authentication up and running already and we need some reason to do some authorization checking, I've created a blog project for us to start from. You can find it on GitHub, called adonisjs-bouncer.

Getting Up & Running

So, if you're looking to follow along, go ahead and clone down the repository.

git clone https://github.com/jagr-co/adonisjs-bouncer

Then, change into its directory.

cd adonisjs-bouncer

Install its already defined dependencies.

npm i

Open the project in your text editor of choice and copy the .env.example file and paste it, renaming it to just .env. Then, update the database connection to match your needs. The project is currently set to use Postgres, so you may need to change that as well, depending on your needs.

To serve as an example here's my complete .env.

# .env

PORT=3333
HOST=0.0.0.0
NODE_ENV=development
APP_KEY=_N6tZMFshID3rH2UIqIcgf0WRV3oMPFL
DRIVE_DISK=local
SESSION_DRIVER=cookie
CACHE_VIEWS=false
DB_CONNECTION=pg
PG_HOST=localhost
PG_PORT=5432
PG_USER=postgres
PG_PASSWORD=password
PG_DB_NAME=adonisjs-blog

Once you've got your .env created and your database variables are defined, jump back into your terminal and let's run the migrations.

node ace migration:run

# ❯ migrated database/migrations/1639232007772_users
# ❯ migrated database/migrations/1639529610746_posts
# ❯ migrated database/migrations/1639529648792_comments

# Migrated in 134 ms

Lastly, if you'd like to use Git on this project, go ahead and delete the .git repository and re-initialize Git within the project

# Make sure you're in the project directory!

rm -rf .git

git init

Current State & Our Authorization Goal

In its current state, it allows users to register, login, and logout. It also currently allows any authenticated user to create a post, edit any post, delete any post, create a comment, and delete any comment.

In addition to this, the application also contains four different roles, which are defined within contracts/enums/Role.ts, user, moderator, editor, and admin. Using bouncer, we'll be authorizing each role to perform certain actions.

• User

  • View published posts

  • Create comments on posts

  • Delete any comment the user has created

• Moderator

  • View published posts

  • Create comments on posts

  • Delete any comment, this allows them to moderate the comment section

• Editor

  • Create comments on posts

  • Delete any comment the user has created

  • Create posts

  • View published posts

  • View unpublished posts the user has created

  • Edit and delete posts the user has created

• Admin

  • View, create, edit, and delete anything

Starting in the next lesson, we'll learn about Bouncer actions and how we can use them to take our blog from the free-range, anything-goes badlands, to the orderly blog our roles are there to enforce. Before we can do that though, we need to get Bouncer installed and configured within our application.

Install & Configure

The first step here is to get Bouncer installed and configured within your project. So first let's install it.

npm i @adonisjs/bouncer

Then, configure it within your project. This is going to create the main file our actions will be defined within, start/bouncer.ts. It's also going to configure the Bouncer provider, add in a Bouncer specific Ace CLI command, and a few other things.

node ace configure @adonisjs/bouncer

# CREATE: start/bouncer.ts
# CREATE: contracts/bouncer.ts
# UPDATE: tsconfig.json { types += "@adonisjs/bouncer" }
# UPDATE: .adonisrc.json { commands += "@adonisjs/bouncer/build/commands" }
# UPDATE: .adonisrc.json { providers += "@adonisjs/bouncer" }
# UPDATE: .adonisrc.json { preloads += "./start/bouncer" }
# CREATE: ace-manifest.json file

With that, we now have Bouncer successfully installed and configured.

Bouncer Starter File

Before we dive into using Bouncer in the next lesson, let's first digest the start/bouncer.ts file that was created when we configured Bouncer into our project. This file contains a lot of useful comments to help introduce you to Bouncer, so definitely give them a read-through! For brevity, I'll be cutting them out and focusing specifically on the code.

So, this file contains three main lines. First, we import the Bouncer module from @ioc:Adonis/Addons/Bouncer. If you're here learning about authorization, nothing should feel foreign yet.

import Bouncer from '@ioc:Adonis/Addons/Bouncer'

Next, a constant called actions is being extracted out of the Bouncer module and exported.

export const { actions } = Bouncer

We'll be learning about actions in the next lesson, but it's here that we'll be defining our actions. You're always going to want to ensure you're exporting this actions variable from this bouncer file!

Lastly, we have another constant, called policies, that's also being extracted out of the Bouncer module and exported.

export const { policies } = Bouncer.registerPolicies({})

Two lessons from now, we'll cover policies and we'll use this section to register the policies we create. Same with actions, you're also always going to want to ensure you're exporting the policies variable from this bouncer file as well.

Next Up

Now that we have our start application cloned down and set up and we've installed and configured Bouncer within this project, we're now ready to start learning about and adding Bouncer. So, in the next lesson, we'll be specifically focusing on actions to accomplish all the authorization checks we have defined for our roles above.