No-code permissions with Kong and Permit.io

Introduction

Kong is one of the most popular API gateways out there; but managing access to API and services behind it can be quite a bit of work especially as the application evolves requiring more and more advanced permissions models (RBAC, ABAC, ReBAC, …) 
Enter Permit - a full stack permissions service, that can empower you to never have to build permissions again.
With a recent update - Permit can now seamlessly integrate with Kong Gateway. And you can add permissions to your API within minutes without having to write a single line of code (unless you want to ;-) ).

If you have Kong Gateway properly configured to relay requests from your users to your backend, you can easily use Permit.io to authorize requests as they go in, with a real time administration layer that has a nice user interface for everybody in your organization but is policy-as-code behind the scenes.

What is Authorization?

Authorization means answering the question:

Can some_user do some_action on some_resource?

The simplest way to implement permissions (that is, other than dummy permissions such as “allow everyone who is authenticated”) is called Role-Based Access Control, or RBAC. In RBAC, each user is assigned one or more roles, and roles can have permissions to perform actions on classes of resources. For example, in a policy, we say that:

• Role admin can read, write and delete on repository
• Role power_user can read and write on repository
• Role viewer can read on repository

And then we define the following facts:

• User annie@example.com has role admin
• User bill@example.com has role power_user
• User carol@example.com has role viewer

Not shown is that users may have more than one role, in which case they get the sum of their roles’ permissions.

Then, let’s say bill wants to write to a repo, we’ll ask the question:

• Can bill@example.com perform write on repository?

Since bill@example.com has the role power_user which can write on repository, the answer is yes, this is allowed.

Though not shown in this tutorial, Permit.io also supports ABAC.

How This Applies to Kong-Based Applications

You’re probably wondering how this applies to HTTP requests, which is what Kong sees. To integrate Permit.io, which works with resources and actions, with Kong, which works with HTTP requests built from paths and methods, we use the methods as actions and translate request paths into resource names. These are the defaults (which obviously you can customize):

For example, using the default translation table, consider the following request:

POST /v2/repository

Authorization: Bearer [bearer token for annie@example.com]

This will be translated into:

Can annie@example.com do post on repository?

How to Integrate Permit.io with your Kong-Based Application

Since Permit.io uses OPA internally, you can use the standard Kong OPA plugin.

This guide assumes that you already have Kong configured, and your authentication is done through Kong.

First, you’ll need to set up your Policy Decision Point, or PDP, next to your Kong Gateway. In the Permit.io architecture, the PDP is a small container that makes authorization decisions. You configure it through Permit.io’s cloud service, but once running it’s completely independent (so it keeps running even if disconnected from the Internet) and can make decisions extremely quickly, on the order of 1-5 ms.

To run the PDP, you can use the following command:

docker run \
⁠  -p 7766:7000 \
⁠  --env PDP_API_KEY=your_api_key \
⁠  --env PDP_KONG_INTEGRATION=true \
⁠  permitio/pdp-v2:latest

To get your API key, go to the Permit.io administration interface and click “Copy SDK secret key” in the user menu:

Once running, you can configure your runtime instance to authorize requests through the PDP. In your Kong Route configuration, add a plugin:

In the plugin configuration, set the following values:

• “Config.include Consumer In Opa Input” should be checked
• “Config.Opa Host” = The PDP’s IP address
• “Config.Opa Path” = “/kong”
• “Config.Opa Port” = 7766
• “Config.Opa Protocol” = “http”

Obviously if you changed any of these values in the PDP configuration, they’ll need to be changed to match in Kong’s configuration as well.

If you need to customize the resource translation table, you can use the following format (shown here is the default table):

[
	["/v\\d+/([^/]+).*", 0],
	["/([^/]+).*", 0],
	["/", "index"]
]

Entries are processed in order. In each entry, the first value is a regular expression to match, while the second is the resource name. For the resource name, a string is used as is, while an integer refers to a capture group in the regular expression.

To override the default table, simply mount the table’s json file at /config/kong_routes.json. The docker run command would be:

docker run \
  -p 7766:7000 \
  --env PDP_API_KEY=your_api_key \
  --env PDP_KONG_INTEGRATION=true \
  -v /path/to/your/kong_routes.json:/config/kong_routes.json \
  permitio/pdp-v2:latest

You should now see your http requests being authorized in the PDP’s log, and in the decision logs in Permit.io’s cloud interface. For any denied requests, Kong will return 403s.

Summary

As you see, Permit.io makes it easy to add permissions to Kong-based applications. You can easily configure Kong Gateway to use Permit’s powerful permission engine to decide whether requests are allowed, and empower non technical people in your organization to manage permissions themselves.