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.

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:

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:

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

 

flowchart LR
    A((fa:fa-user Super-admin user
permissions
CRUD))
    B(Kong Manager)
    C(Admin API)
    D(RBAC)
    E(Routes)
    F(Services)
    G(Plugins)
    H(Workspaces)
    A--> B & C
    subgraph id1 [Control Plane]
        B --> C
    direction LR
        subgraph id2 [Kong Entities]
        direction LR
        D
        E
        F
        G
        H
        end
    C --> D & E & F & G & H
    end

  

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.

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 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:

1. Allow or deny permissions against the current endpoint in the current Workspace.
2. Wildcard allow or deny permissions against the current endpoint in any Workspace.
3. Allow or deny permissions against any endpoint (wildcard) in the current Workspace.
4. 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

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


  

The following table describes the different RBAC entities:

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"}'

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.