このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。
最新のドキュメントはこちらをご参照ください。
Manage Administrative Teams
In this topic, you’ll learn how to manage and configure user authorization using workspaces and teams in Kong Gateway.
If you are following the getting started workflow, make sure you have completed Set Up Intelligent Load Balancing before moving on.
Overview of workspaces and Teams
Many organizations have strict security requirements. For example, organizations need the ability to segregate the duties of an administrator to ensure that a mistake or malicious act by one administrator doesn’t cause an outage. Kong Gateway provides a number of security capabilities to help customers secure the administration environment.
Workspaces enable an organization to segment objects and admins into namespaces. The segmentation allows teams of admins sharing the same Kong Gateway cluster to adopt roles for interacting with specific objects. For example, one team (Team A) may be responsible for managing a particular service, whereas another team (Team B) may be responsible for managing another service. Teams should only have the roles they need to perform the administrative tasks within their specific workspaces.
Kong Gateway does all of this through Role-Based Access Control (RBAC). All administrators can be given specific roles, whether you are using Kong Manager or the Admin API, which control and limit the scope of administrative privileges within specific workspaces.
In this example, you’ll start by creating a simple workspace called SecureWorkspace
. Then, you’ll create an administrator for that workspace, with rights to administer only the objects in the SecureWorkspace and nothing else.
Note: The steps in this topic cannot be performed using declarative
configuration.
Securing your Gateway Installation
At a high level, securing Kong Gateway administration is a two-step process:
- Turn on RBAC.
- Create a workspace and an admin for segregated administration.
At this point in the Getting Started Guide, you have been interacting with your environment as the built-in Super Admin, kong_admin
. The password for this kong_admin
user was “seeded” during the installation process using the KONG_PASSWORD environment variable. After RBAC is enabled, you will need to authenticate to the Kong Manager and the Kong Gateway Admin API using the proper credentials.
In the following sections, you will need the kong_admin
account’s password to log in to Kong Gateway, and the kong_admin_uri
needs to be configured to avoid getting CORS errors.
Turn on RBAC
To enable RBAC, you will need the initial KONG_PASSWORD that was used when you first installed Kong Gateway and ran migrations. This is also the default password for the Super Admin, and will be required once RBAC is on.
UNIX-based system or Windows
Docker
- Modify configuration settings below in your
kong.conf
file. Navigate to the file at /etc/kong/kong.conf
:
- Copy the
kong.conf.default
file so you know you have a working copy to fall back to.
cp kong.conf.default kong.conf
-
Now, edit the following settings in kong.conf
:
echo >> “enforce_rbac = on” >> /etc/kong/kong.conf
echo >> “admin_gui_auth = basic-auth” >> /etc/kong.conf
echo >> “admin_gui_session_conf = {"secret":"secret","storage":"kong","cookie_secure":false}”
This turns on RBAC, tells Kong Gateway to use basic authentication (username/password), and tells the Sessions plugin how to create a session cookie.
The cookie is used for all subsequent requests to authenticate the user until it expires. The session has a limited duration and renews at a configurable interval, which helps prevent an attacker from obtaining and using a stale cookie after the session has ended.
- Restart Kong Gateway and point to the new config file:
kong restart -c /etc/kong/kong.conf
If you have a Docker installation, run the following command to set the needed environment variables and reload the gateway’s configuration.
Note: Make sure to replace {KONG-CONTAINER-ID}
with the ID of your container.
echo "KONG_ENFORCE_RBAC=on
KONG_ADMIN_GUI_AUTH=basic-auth
KONG_ADMIN_GUI_SESSION_CONF='{\"secret\":\"secret\",\"storage\":\"kong\",\"cookie_secure\":false}'
kong reload exit" | docker exec -i {KONG_CONTAINER_ID} /bin/sh
This turns RBAC on, tells Kong Gateway to use basic authentication (username/password), and tells the Sessions plugin how to create a session cookie.
The cookie is used for all subsequent requests to authenticate the user, until it expires. The session has a limited duration and renews at a configurable interval, which helps prevent an attacker from obtaining and using a stale cookie after the session has ended.
Outside of this guide, you will likely want to modify these settings differently, depending on your installation. You can read more about these settings here: Basic Auth for Kong Manager.
Create a workspace
Using Kong Manager
Using the Admin API
Log into Kong Manager
- Go to Kong Manager, or reload the page if you already have it open and you will see the following login screen.
-
Log in to Kong Manager with the built-in Super Admin account, kong_admin
, and its password.
Remember, this is the initial KONG_PASSWORD you used when you ran migrations during installation.
-
If you have logged in successfully, then you can start administering your Kong Gateway cluster.
If this step did not work, and you know the credentials are correct, then something is likely wrong with your Kong Gateway configuration. Double-check the settings. If the cause of the problem still isn’t clear, work with your Kong Konnect account team and Kong Support for assistance.
Create the Workspace
- Access your Kong Manager instance.
- On the workspaces tab, click on New Workspace.
-
Create a workspace named SecureWorkspace
and select a color for the workspace avatar.
Note: Each workspace name should be unique, regardless of letter case. For example, naming one workspace “Payments” and another one “payments” will create two different workspaces that appear identical.
WARNING: Do not give a workspace the same name as any of these major routes in Kong Manager:
Admins |
APIs |
Certificates |
Consumers |
Plugins |
Portal |
Routes |
Services |
SNIs |
Upstreams |
Vitals |
PermalinkStep |
- Click Create New workspace.
- On the new workspace, click Teams.
- From the Teams page, click the Roles tab to view the default roles that come with Kong Gateway.
- Next to SecureWorkspace, click View to see its assigned roles.
-
There are different roles available for the SecureWorkspace. By default, each new workspace has the following roles and privileges:
Role |
Description |
workspace-admin |
Can administer the objects in a workspace but can’t add new administrators to the workspace. |
workspace-portal-admin |
Can manage the Dev Portal. |
workspace-read-only |
Can view anything in the workspace, but can’t make any changes. |
workspace-super-admin |
Can do anything inside the workspace. |
Notes:
-
Be careful: Granting access to the default workspace gives access to all workspaces in the organization.
-
The default workspace only has three roles: workspace-admin, workspace-super admin, and workspace-read-only. Every other workspace will have the four roles mentioned above.
-
You can also create custom roles by clicking on the Add Role button and specifying the endpoints that the administrator with the role will be able to interact with.
Create a new workspace called SecureWorkspace, substituting the kong_admin
account’s password in place of <super-user-token>
:
curl -X POST http://localhost:8001/workspaces \
-H Kong-Admin-Token:<super-user-token> \
--data 'name=SecureWorkspace'
http :8001/workspaces \
name=SecureWorkspace \
Kong-Admin-Token:<super-user-token>
Note: Each workspace name should be unique, regardless of letter case. For example, naming one workspace “Payments” and another one “payments” will create two different workspaces that appear identical.
WARNING:
If you are unable to log in with kong_admin
’s token, and you know the credentials are correct, then something is likely wrong with your Kong Gateway configuration. Double-check the settings, or, if the cause of the problem still isn’t clear, work with your Kong Konnect account team and Kong support for assistance.
Create an Admin
Next, create an admin for the SecureWorkspace, granting them permissions to manage only that workspace.
Using Kong Manager
Using the Admin API
Invite a New Admin
If you also use the Admin API, once you’ve created this admin, you can find it under the /admins
endpoint.
- From the Teams > Admins tab, click Invite Admin.
- Enter the new administrator’s Email address, Username, and Custom Id.
-
Ensure that Enable RBAC Token is enabled.
Note: This setting lets the admin use the Admin API as well as Kong Manager. If you don’t want this user to access the Admin API, uncheck this box.
- Click Add/Edit Roles.
- In the Workspace Access dialog, select the SecureWorkspace.
-
Select the workspace-admin role, which makes this user the workspace administrator for the SecureWorkspace.
When you are done adding roles, you are redirected back to the Invite Admin dialog.
Important: Before you move on, make sure the Enable RBAC Token checkbox is checked. The RBAC token is what allows the new admin to send a token to the Admin API to configure the system programmatically.
-
Click Invite Admin to send the invite.
At this point in the getting started guide, you likely haven’t set up SMTP yet, so no email will be sent. Instead, you’ll later generate a registration link for the new administrator manually.
Register the Admin
- Back on the Teams page, click View for the administrator you just created.
-
Click the Generate registration link button.
Using this link, the new administrator can go to a web browser and paste it in to initiate his/her account and create an initial password. Again, normally, this would happen through SMTP, and the user would get this link through an email.
- Click the copy icon to copy the registration link, then save it.
- Email or SMS the registration link to the new administrator — or use it yourself to test the login in the following steps.
- Open a different browser or an incognito tab in the current browser so your existing login session is ignored.
-
Enter the registration link you copied previously into the new browser to log in with the new administrator (secureworkspaceadmin
).
If the registration link has expired, you can generate a new one by logging in with your kong_admin
administrator and generating a new link.
-
Enter a new password for your new administrator (save this in a secure place) and click on the Register button.
If everything went well, you should see an “Account Setup Success” message.
Note The following method refers to the /users
endpoint and creates an Admin API user that won’t be visible (or manageable) through Kong Manager. If you want to later administer the admin through Kong Manager, create it under the /admins
endpoint instead.
Create a new user named secureworkspaceadmin
with the RBAC token
secureadmintoken
:
curl -X POST http://localhost:8001/SecureWorkspace/rbac/users \
-H Kong-Admin-Token:<super-user-token> \
--data 'name=secureworkspaceadmin' \
--data 'user_token=secureadmintoken'
http :8001/SecureWorkspace/rbac/users \
name=secureworkspaceadmin \
user_token=secureadmintoken \
Kong-Admin-Token:<super-user-token>
Create a blank role in the workspace and name it admin
:
curl -X POST http://localhost:8001/SecureWorkspace/rbac/roles \
-H Kong-Admin-Token:<super-user-token> \
--data 'name=admin' \
http :8001/SecureWorkspace/rbac/roles/ \
name=admin \
Kong-Admin-Token:<super-user-token>
Give the admin
role permissions to do everything on all endpoints in the
workspace:
curl -X POST http://localhost:8001/SecureWorkspace/rbac/roles/admin/endpoints/ \
-H Kong-Admin-Token:<super-user-token> \
--data 'endpoint=*'
--data 'workspace=SecureWorkspace' \
--data 'actions=*'
http :8001/SecureWorkspace/rbac/roles/admin/endpoints/ \
endpoint='*' \
workspace=SecureWorkspace \
actions='*' \
Kong-Admin-Token:<super-user-token>
Grant the admin
role to secureworkspaceadmin
:
curl -X POST http://localhost:8001/SecureWorkspace/rbac/users/secureworkspaceadmin/roles/ \
-H Kong-Admin-Token:<super-user-token> \
--data 'role=admin'
http :8001/SecureWorkspace/rbac/users/secureworkspaceadmin/roles/ \
roles=admin \
Kong-Admin-Token:<super-user-token>
Verify the New Admin
Using Kong Manager
Using the Admin API
- Click the Login button to be taken to a new screen to log in with your new administrator.
-
Enter the Username and Password of your new administrator and click Login again.
Once you log in, you’ll notice that you can only see the SecureWorkspace.
- You can also verify that this user’s administration rights are limited. As this user, if you open the Teams tab and try to add new administrators, Admin API users (RBAC users), Groups, or Roles, you won’t have the permissions to do so.
-
Try to access the default
workspace using secureworkspaceadmin
’s user token.
Using cURL:
curl -H Kong-Admin-Token:secureadmintoken -X GET http://localhost:8001/default/rbac/users
Or using HTTPie:
http :8001/default/rbac/users Kong-Admin-Token:secureadmintoken
You should get a 403 Forbidden
error message:
{
“message”: “secureworkspaceadmin, you do not have permissions to read this resource”
}
-
Then, try to access the same endpoint, but this time in the SecureWorkspace
.
Using cURL:
curl -H Kong-Admin-Token:secureadmintoken -X GET http://localhost:8001/SecureWorkspace/rbac/users
Or using HTTPie:
http :8001/SecureWorkspace/rbac/users Kong-Admin-Token:secureadmintoken
This time, you should get a 200 OK
success message and a list of users.
That’s it! You are now controlling access to Kong Gateway administration with RBAC.
Reference: Using decK with RBAC and Workspaces
RBAC
Once RBAC is enabled, you will have to pass the kong-admin-token
in a header
any time you use decK:
deck sync --headers "kong-admin-token:mytoken"
Note: You should not use an RBAC token with Super Admin
privileges for decK. Always scope down to the exact permissions you need to
give decK.
Workspaces
When you have multiple workspaces, decK creates a file for each one. Export
them as follows:
deck dump --all-workspaces
Or, to export the configuration for only one workspace:
deck dump --workspace SecureWorkspace
You can use these flags with any decK commands to update and export your
configuration.
Summary and next steps
In this topic, you:
- Enabled RBAC.
- Created a workspace named
SecureWorkspace
.
- Created an admin named
secureworkspaceadmin
and granted them permissions to manage to everything in the SecureWorkspace
.
Next, set up the Dev Portal.