Custom roles
A custom role is a named set of permissions that you pick from G8's permission dictionary. It fills the gaps between the four built-in roles, for example a team that may change routes but only read consumers. Users, roles and access describes the built-in roles and how a person or a directory group gets a role. This page covers what a role can hold and how to make one.
Who may open it
The Roles tab under Users & access belongs to the Platform administrator. Anyone else who opens it by its address sees a page that says Platform administrators manage it.
The server holds the same line. Reading, creating, changing and deleting roles, and reading the dictionary, all need the permission to manage roles (roles.manage). It is a platform permission, and only the Platform administrator holds platform permissions.
The permission dictionary
The dictionary and the four built-in roles come with G8, and nobody can edit them. A server start that finds its database disagreeing with them stops, with an error in the server log.
Each permission pairs a resource with an action, view or manage. Manage includes view. A permission has one of two scopes.
- Environment scope. The permission applies inside an environment. A role made of these permissions is given in one environment or in all of them.
- Platform scope. The permission applies to the installation as a whole: users, service accounts, the directory connection, roles, environments and the platform audit log. Only the built-in Platform administrator holds these, and a custom role cannot.
The environment permissions, with what the built-in environment roles hold of each:
| Resource in the console | Resource | Actions | Environment administrator | Editor | Viewer |
|---|---|---|---|---|---|
| Routes | routes | view, manage | Manage | Manage | View |
| Services | services | view, manage | Manage | Manage | View |
| Upstreams | upstreams | view, manage | Manage | Manage | View |
| Consumers | consumers | view, manage | Manage | Manage | View |
| Certificates | certificates | view, manage | Manage | View | View |
| Plugins | plugins | view | View | View | View |
| Consumer groups | consumer_groups | view, manage | Manage | Manage | View |
| Global rules | global_rules | view, manage | Manage | Manage | View |
| Plugin configs | plugin_configs | view, manage | Manage | Manage | View |
| Environment-wide settings | plugin_metadata | view, manage | Manage | Manage | View |
| Protos | protos | view, manage | Manage | Manage | View |
| Stream routes | stream_routes | view, manage | Manage | Manage | View |
| Secrets | secrets | view, manage | Manage | View | View |
| Audit log | audit | view | View | None | None |
| Traffic Explorer | traffic | view, manage | Manage | None | None |
| Request bodies | traffic_bodies | view | View | None | None |
| Analytics | analytics | view | View | None | None |
| Alerts | alerts | view, manage | Manage | None | None |
A few resources cover more than their name.
- Consumers also covers the credentials stored under each consumer. A role that views consumers without managing them sees the secrets inside every credential masked.
- Services also covers the Cost decorations stored under a service. Each one weights a field or type of the GraphQL schema the service fronts, for the graphql-limit-count plugin.
- Plugins has view only. It opens the plugin catalog of the environment and the pages that show where each plugin is used. Adding a plugin to a route, a service, a consumer or any other object is a change to that object, so it needs that object's manage permission. An Editor therefore adds and changes plugins on every object it manages.
- Environment-wide settings are the settings a plugin applies across the whole environment. An Editor manages them. They are not the environment's own record of addresses and keys, which only the Platform administrator changes.
- Traffic Explorer with view opens Traffic Explorer. With manage it also turns request logging on and sets how long records are kept. Opening a request or response body needs Request bodies as well.
The Platform administrator holds every permission of both scopes, in every environment.
The built-in roles are fixed
The four built-in roles cannot be edited or deleted. Their row menu offers View instead of Edit, and no Delete role. The console opens a built-in role read-only, under the banner Built-in role. The banner goes on: Its permissions cannot be changed. Create a custom role to adjust them.
The banner's New role from this opens a new custom role with the built-in role's environment permissions already ticked. Duplicate in the row menu of any role does the same. The name and the description start empty.
Make a custom role
- On the Roles tab, select New role.
- Enter a Name and, if you like, a Description.
- Under Permissions, tick View or Manage for each resource. Ticking manage ticks view as well, marked Included with manage. A resource that has no manage action shows Not applicable in that column.
- Select Create role.
The server checks the role again before it saves it.
- The name is required, at most 128 characters, without line breaks or tabs.
- No two roles share a name, whatever the case. When the name is taken, the field says: This name is taken.
- The description is at most 512 characters.
- The role holds at least one permission, and every permission is one the dictionary knows.
- A manage permission comes with its view permission.
- No platform permission is accepted. The form says why: Platform permissions belong to the built-in Platform administrator and cannot be part of a custom role.
Creating, changing and deleting a role each leave a row in the platform audit log. The rows of a created or changed role list the permissions it holds.
Give, change and delete a custom role
A custom role is given like a built-in environment role, in one environment or in All environments, to a person, a directory group or a service account. Users, roles and access shows how.
A change to a role reaches every user and service account that holds it at their next request, because the server reads their permissions again on every request. The form says so while the role is assigned.
A role cannot be deleted while it is assigned. In the row menu, Delete role stays unavailable until the last assignment is removed, and the server refuses such a delete as well.
What a role sees masked
Some fields of a gateway object are secrets: an API key on a consumer, a password, a certificate's private key, a key inside a plugin's configuration. The server decides per kind of object who sees them.
- A role that holds the manage permission of the object's kind sees every value as the gateway stores it.
- A role that holds only view gets each secret value replaced by
••••. Lists, single objects, forms, the Overview and the Raw JSON tab all show the replaced value.
The fields replaced are those the gateway's plugin schemas mark as encrypted, plus the fields G8's own list adds. When an object carries a plugin the server's plugin catalog does not know, every value inside that plugin's configuration is replaced by ••••. Its field names stay visible.
So an Editor sees a certificate's private key and the values of a secret manager masked, because the Editor views certificates and secrets without managing them. A custom role with view on Consumers and no manage sees every credential's key masked.
The mask cannot be written back. The server refuses any save that still carries •••• in a secret field, and answers with the paths it found.
Related
- Users, roles and access: the built-in roles and how a role is given.
- Service accounts and the API: roles held by a script or a pipeline.
- Raw JSON and copy to environment: what a role without manage sees in the Raw JSON tab.
- Audit log: the rows that role changes leave.