RBAC

Uses: Kong Gateway Admin API

What is RBAC?

Roles and permissions are administered using the Kong Gateway RBAC entity, which stands for Role-Based Access Control. Roles are sets of permissions that can be assigned to admins and users and can be specific to a Workspace. Permissions are types of rules that affect Kong Gateway resources, which are the core components of an API.

RBAC in Kong Gateway conforms to the following core principles:

In Kong Gateway there are users
Every user has a role
Roles are assigned permissions
A group is a collection of roles

Kong Gateway uses a precedence model, from most specificity to least specificity, to determine if a user has access to an endpoint.

Users, roles, and permissions

Each role may have a number of permissions that determine its ability to interact with a resource. The RBAC system provides a level of granularity that works by assigning actions on a per-resource level using the principle of least privilege. This means that a user can have read permissions on /foo/bar and write permissions on /foo/bar/far.

User types in Kong Gateway

Kong Gateway has the following RBAC user types:

User type	Purpose	Most useful for	What tools does it have access to?
Admin	An admin belongs to a Workspace and has at least one role with a set of permissions. If an admin is in a Workspace without a role, they can’t see or interact with anything. Admins can manage entities inside Workspaces, including users and their roles.	Personal administrative accounts for Kong Gateway and Kong Manager	Admin API Kong Manager decK
Super admin	Specialized admins with the ability to: Manage all Workspaces Further customize permissions Create entirely new roles Invite or deactivate admins Assign or revoke admin roles	Managing RBAC	Admin API Kong Manager decK
User	RBAC users without administrator permissions. They have access to manage Kong Gateway, but can’t adjust teams, groups, or user permissions.	Service accounts for Kong Gateway, used as part of an automated process	Admin API decK

Default Kong Gateway roles

By default, when Kong Gateway is configured, the starting user is configured as a Super Admin in the default Workspace. Workspaces, by default, contain the following roles:

Role	Description
`admin`	Full access to all endpoints, across all Workspaces, except the RBAC Admin API.
`super-admin`	Full access to all endpoints, across all Workspaces, including the ability to assign and modify RBAC permissions.
`read-only`	Read access to all endpoints, across all Workspaces.

An admin has full permissions to every endpoint in Kong Gateway, but they can’t assign and modify RBAC permissions.

Workspace roles

Workspaces provide a way to logically segment configurations and entities with RBAC. Using RBAC, you can restrict access to groups of users and create roles within a Workspace so that users can manage each other. This is done using the workspaces/rbac/roles endpoint.

Role	Description
`workspace-admin`	Full access to all endpoints in the Workspace, except the RBAC Admin API.
`workspace-super-admin`	Full access to all endpoints in the Workspaces, including the ability to assign and modify RBAC.
`workspace-portal-admin`	Full access to Dev Portal related endpoints in the Workspace.
`workspace-read-only`	Read access to all endpoints in the Workspace.

A role assigned in the default Workspace has permissions across all subsequently created Workspaces unless the roles in the specific Workplace are explicitly assigned. When a Workspace has explicitly assigned roles, they take precedent over the default Workspace.

If RBAC roles and permissions are assigned from within a Workspace, they are specific to that Workspace. For example, if there are two Workspaces, Payments and Deliveries, an admin created in Payments doesn’t have access to any endpoints in Deliveries.

Kong Manager authentication

When Kong Manager authentication is enabled, RBAC must be enabled to enforce authorization rules. Otherwise, anyone who can log in to Kong Manager can perform any operation available on the Admin API.

RBAC precedence order

Kong Gateway uses a precedence model when checking if a user has sufficient permissions to access an endpoint, a resource, or a Workspace. This information is collected from the various permissions or applied across the roles and groups assigned to a user.

For each request, Kong Gateway checks for an RBAC rule assigned to the requesting user in the following order:

Allow or deny permissions against the current endpoint in the current Workspace.
Wildcard allow or deny permissions against the current endpoint in any Workspace.
Allow or deny permissions against any endpoint (wildcard) in the current Workspace.
Wildcard allow or deny permissions against any endpoint in any Workspace.

If Kong Gateway finds a matching permission for the current user, endpoint, or Workspace, it allows or denies the request based on it. Once Kong Gateway finds an applicable rule, the algorithm stops and doesn’t check less specific permissions. If no permission is found (approval or denial), the request is denied.

Wildcards in endpoint permissions

To create an endpoint permission via /rbac/roles/:role/endpoints, you must pass the parameters below, all of which can be replaced by a * character:

endpoint: * matches any endpoint
workspace: * matches any workspace
actions: * evaluates to all actions—read, update, create, delete

endpoint, in addition to a single *, also accepts * within the endpoint itself, replacing a URL segment between /. For example, all of the following are valid endpoints:

/rbac/*: where * replaces any possible segment, for example /rbac/users and /rbac/roles
/services/*/plugins: * matches any service name or ID

Note * is not a generic, shell-like, glob pattern. Therefore, /rbac/* or /workspaces/* alone don’t match all of the RBAC and Workspaces endpoints.

For example, to cover all of the RBAC API, you would have to define permissions for the following endpoints:

/rbac/*

/rbac/*/*

/rbac/*/*/*

/rbac/*/*/*/*

/rbac/*/*/*/*/*

If workspace is omitted, it defaults to the current request’s workspace. For example, a role-endpoint permission created with /teamA/roles/admin/endpoints is scoped to workspace teamA.

Wildcards in entity permissions

For entity permissions created via /rbac/roles/:role/entities, the following parameter accepts a * character:

entity_id: * matches any entity ID

Role configuration

This diagram helps explain how individual Workspace roles and cross-Workspace roles interact:

 
flowchart LR
    subgraph team-a-roles [Team A Roles]
        Admin2["Admin"]
        RO2["Read Only"]
        C2["Custom"]
    end 
    subgraph team-b-roles [Team B Roles]
        Admin3["Admin"]
        RO3["Read Only"]
        C3["Custom"]
    end 
    subgraph cross-workspace-roles [Platform Admins]
        SA["Super Admin"]
        Admin["Admin"]
        RO["Read Only"]
        C["Custom"]
    end 

    subgraph defaultWorkspace [Default Workspace]
        routes["Route"]
        service["Service"]
        plugin["Plugin"]
    end

    subgraph teamAworkspace [Team A Workspace]
        routes2["Route"]
        service2["Service"]
        plugin2["Plugin"]
    end
    subgraph teamBworkspace [Team B Workspace]
       routes3["Route"]
        service3["Service"]
        plugin3["Plugin"]
    end

    team-a-roles --> teamAworkspace
    team-b-roles --> teamBworkspace
    cross-workspace-roles --> defaultWorkspace
    cross-workspace-roles --> teamAworkspace
    cross-workspace-roles --> teamBworkspace

RBAC entities

The following table describes the different RBAC entities:

RBAC Entity	Description
`User`	The entity interacting with the system. Can be associated with zero, one, or more roles.
`Role`	A set of permissions
`role_source`	Specifies where the user role is defined, either locally or through an identity provider (IdP).
`role_endpoint`	The endpoint associated with the RBAC role.
`role_entity`	The ID of the entity associated with the RBAC role. For example: The role developer has one `role_entity` attached to a UUID.

Enable RBAC

This command creates a Kong Gateway instance, sets the Kong super admin password to kong, and sets up RBAC. This command assumes you have a valid license in the environment variable KONG_LICENSE_DATA:

curl -Ls get.konghq.com/quickstart | bash -s -- -e "KONG_LICENSE_DATA" \
   -e "KONG_ENFORCE_RBAC=on" \
   -e "KONG_ADMIN_GUI_AUTH=basic-auth" \
   -e "KONG_PASSWORD=kong" \
   -e 'KONG_ADMIN_GUI_SESSION_CONF={"secret":"kong", "cookie_lifetime":300000, "cookie_renew":200000, "cookie_name":"kong_cookie", "cookie_secure":false, "cookie_samesite": "off"}'

Copied to clipboard!

Before enforcing RBAC on your Kong Gateway instance, create a super-admin user:
```
 curl -i -X POST http://localhost:8001/rbac/users \
   --data name=super-admin \
   --data user_token=$SUPER_ADMIN_USER_TOKEN
```
Copied to clipboard!
Creating the super-admin username automatically adds the user to the super-admin role.
In the location where Kong Gateway is running, enable RBAC with the auth method of your choice.

Set the following parameters in kong.conf:
- enforce_rbac: Set to on to enable RBAC.
- admin_gui_auth: Required for Kong Manager. Set this value to the desired authentication, for example basic-auth.
- admin_gui_session_conf: Required for Kong Manager. Adds a session secret.
For example, to set these parameters using environment variables, run:
```
 export KONG_ENFORCE_RBAC=on && \
 export KONG_ADMIN_GUI_SESSION_CONF='{"secret":"kong", "cookie_lifetime":300000, "cookie_renew":200000, "cookie_name":"kong_cookie", "cookie_secure":false, "cookie_samesite": "off"}' && \
 export KONG_ADMIN_GUI_AUTH=basic-auth
```
Copied to clipboard!
Restart or reload Kong Gateway.

From here, you can use the super-admin user to manage your RBAC hierarchy. For an in-depth walkthrough of how to do this, review the Enable RBAC with the Admin API documentation.

The super-admin user only has permissions to manage RBAC. You must create other admins or users to be able to interact with other Kong Gateway entities, such as Gateway Services and Routes.