Table of Contents

Introduction

Kong Enterprise provides an additional layer of security for the Admin API in
the form of Role-Based Access Control (RBAC). RBAC allows for fine-grained
control over resource access based on a model of User, Roles, and Permissions.
Users are assigned to one or more Roles, while each role, in turn, possesses one
or more permissions granting or denying access to endpoints or entities.
In this way, fine-grained control over specific Admin API endpoints or entities
can be enforced, while scaling to allow sophisticated, case-specific uses.

This document aims to be an introduction to Kong Admin API RBAC and its
concepts. For Admin API documentation, see the RBAC API Chapter; for
examples of RBAC operation, see the RBAC Examples Chapter.

Enforcing RBAC

RBAC policies are of little use without enforcement. By default, RBAC policies
are not enforced by Kong, meaning that the Admin API access is available
without requiring any authorization; this allows bootstrapping new Kong clusters
with the appropriate RBAC configuration. Once RBAC has been configured, enforcing
authorization and role access requires only a single configuration change via
the Kong config file.

Previous to Kong Enterprise 0.33, Admin API RBAC was limited to “resources”,
which mapped to Admin API endpoints. Starting with Kong Enterprise 0.33, RBAC
also allows Entity-Level permissions. As such, its configuration directive
enforce_rbac, previously a boolean, is now an enumeration, whose set of
possible values is:

RBAC policies are now enforced by Kong, based on the user token presented
to the request. By default, the user token is sent via the
Kong-Admin-Token request header; the name of this header is configurable via
the Kong configuration file. To test our setup, we can send a request
to the Admin API without sending an authentication. Because Kong does not
recognize a user associated with the requesting client, it rejects the
request:

User

A user identifies the actor sending the current request. Users are identified
by Kong via the user_token element, sent to the Admin API as a request header.
A user is assigned one or more Roles, the permissions of which determine what
resources the user is allowed access. Users can be quickly enabled or disabled via
the enabled flag on the User entity in the Admin API; this allows Kong
administrators to quickly enable and disable users without removing their
tokens or metadata.

Role

Roles tie together users and permissions, effectively assignment permissions to
a user based on the assignment of permissions to the roles. Roles have a
many-to-many relationship with both users, meaning that more than one user may
be assigned to any given role, and a user may be assigned to more than one
role. Likewise, roles also have a many to many relationships with endpoints and
entities permissions; a role may be associated with more than one endpoint
or entity permission. Roles are defined by a human-readable name, such as
“read-only”.

Role - Endpoints

Roles may have many Endpoint permissions, meaning users in that role will
effectively be allowed (or explicitly disallowed) access to a set of endpoints.
Role-Endpoint relationships carry many attributes, describing how the endpoint
permission apply to the role - e.g., the actions, such as read and write;
whether or not the permission is negative, meaning the actions are negatives,
that is, the role is not allowed to perform the actions described in actions,
and the endpoint itself, for instance, /rbac/users.

As concrete examples, let’s say we want to create a role implementing the
following use cases:

A permission that allows a Role (or, more precisely, users in that role), to
perform any action, over any workspace, and any endpoint:

endpoint: * - the * matches any endpoint

actions: * - the * matches any action

workspace: * - the * matches any workspace

negative: false

Now, I want to explicitly disallow write access to the /rbac/users
endpoint, so that users in the Role cannot create, update, or delete my RBAC
users:

Role - Entities

Roles can also associate with particular Kong entities, identified by their
ID field - a UUID, normally autogenerated by Kong at entity creation time.
Similarly to Role-Endpoint permissions, Role-Entity permissions have an
actions field. Additionally, Role-Entity permissions have an entity_id
field.

Default Roles and Permissions

For convenience, Kong Enterprise ships with three built-in roles This allows
for quick bootstrapping of RBAC integrations without the need to create many
boilerplate RBAC entities. The default permissions are:

read-only This role has read access to all default Kong endpoints

admin This role has read, create, update, and delete access to all Kong
endpoints, except for the RBAC Admin API

super-admin This role has read, create, update, and delete access to all
Kong endpoints, including the RBAC Admin API

Kong does not provide any users by default, as this would be a
backdoor into Admin API security. As such, it the administrator’s responsibility
to configure the appropriate RBAC users and user/role relationships.