Configure a Kong Gateway RBAC user with custom permissions

Uses: Kong Gateway

Deployment Platform:

Prerequisites

Start Kong Gateway with RBAC

This tutorial requires Kong Gateway Enterprise.

Export your license to an environment variable:

 export KONG_LICENSE_DATA='LICENSE-CONTENTS-GO-HERE'

Run the quickstart script with RBAC enabled:

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

Once Kong Gateway is ready, you will see the following message:

 Kong Gateway Ready

For more information about the values, see the Bootstrap RBAC guide.

Create an RBAC user

An RBAC user has the ability to access the Kong Gateway Admin API. The permissions assigned to their role will define the types of actions they can perform with various Admin API objects.

Create an RBAC user by sending a POST request to the /rbac/users endpoint:

curl -X POST "http://localhost:8001/rbac/users" \
     -H "Kong-Admin-Token:kong" \
     --json '{
       "name": "alex",
       "user_token": "alex-token"
     }'

By omitting the Workspace in the request, the user gets added to the default Workspace.

Create a role with endpoint permissions

Let’s say that in our environment, we need a subset of users to access Gateway Services only. Create a new role:

curl -X POST "http://localhost:8001/rbac/roles" \
     -H "Kong-Admin-Token:kong" \
     --json '{
       "name": "dev"
     }'

Then, assign endpoint permissions to the role, allowing access only to the /services endpoint:

curl -X POST "http://localhost:8001/rbac/roles/dev/endpoints" \
     -H "Kong-Admin-Token:kong" \
     --json '{
       "endpoint": "/services/",
       "workspace": "default",
       "actions": [
         "*"
       ]
     }'

Assign role to user

Assign the dev role to the user you created earlier:

curl -X POST "http://localhost:8001/rbac/users/alex/roles" \
     -H "Kong-Admin-Token:kong" \
     --json '{
       "roles": "dev"
     }'

Validate

You can validate that the user has correct permissions by trying to access entities with the user’s access token. First, try to access /routes, which this user doesn’t have permissions for:

curl "http://localhost:8001/routes" \
     -H "Kong-Admin-Token:alex-token"

If RBAC was enabled correctly, this request returns the following error message:

{"message":"alex, you do not have permissions to read this resource"}%

Now, try adding a Service using the /services endpoint:

curl -X POST "http://localhost:8001/services" \
     -H "Kong-Admin-Token:alex-token" \
     --json '{
       "name": "test-service",
       "host": "httpbin.konghq.com"
     }'

This time, the request succeeds with a 200 and creates a new Service.

Cleanup

Destroy the Kong Gateway container

curl -Ls https://get.konghq.com/quickstart | bash -s -- -d

FAQs

When accessing a restricted resource with an RBAC user via the Admin API, why do I get Invalid RBAC credentials instead of a permissions error?

If you see an Invalid RBAC credentials error, this means that the user token you provided is incorrect or doesn’t exist. Check your credentials and try again.