Roles and grants

A role is a named set of verbs, such as read, author, operate, deploy or reveal. A grant gives a person or an API key one role in one project, optionally limited to some environments and to some integrations or APIs of that project. Access is denied by default on every route of the API, so a request is served only when a grant allows it. The admin UI and the weikio CLI call the same API, so the same rule applies wherever a person works.

The roles that ship#

Four roles ship with every installation. Any key may list them, so a developer can see what a grant means:

$ weikio get roles

NAME       VERBS                                                                 SEEDED
viewer     read                                                                  yes
editor     read, author, operate, reveal                                         yes
deployer   read, author, operate, reveal, deploy, entity-store-policy            yes
admin      read, author, operate, reveal, deploy, entity-store-policy, members   yes
helpdesk   read                                                                  no

helpdesk in this list is a custom role of the installation. The shipped roles can be edited by a platform administrator and are never deleted.

The verbs#

Create a custom role#

A custom role is created from the verbs above, with the CLI or as a document in Git:

$ weikio role create helpdesk --verbs read --description "Reads production for support cases"

apiVersion: weik.io/v1
kind: role
metadata: { name: helpdesk }
spec: { verbs: [read] }

$ weikio apply -f platform/roles/helpdesk.yaml

Target: https://hub.example
role helpdesk created (verbs read)

weikio role set helpdesk --verbs read,operate replaces a role’s verbs, and weikio describe role helpdesk shows the projects where it’s granted. Deleting a custom role ends what the grants that use it give. A role created later under the same name is another role and gives those grants nothing.

How a grant works#

A grant is a role, a project, the environments it covers and optionally the integrations and APIs it covers. The CLI writes it as project/role@environments, such as finance/deployer@devtest,production:

• A grant with no environments covers every environment.
• A grant that lists no integrations and no APIs covers the whole project.
• A grant that lists some covers exactly those, their definitions, deployments, logs, metrics and traces, and nothing else of the project.
• What the project shares, its kamelets and its own variables and secrets, can be seen by every member and changed only through a grant that lists nothing.

A grant refers to its project, role, environments, integrations and APIs by their IDs, so a rename changes nothing for it. A record created later under an old name isn’t one the grant covers. Projects and access shows how to give a grant to a person.

Platform administrators#

Platform administrator is a setting on a user, apart from roles and verbs. A platform administrator creates projects, environments, agents, users and providers and reads the whole audit trail:

$ weikio user set pekka.niemi@example.com --platform-admin=true

A role with the verb platform is refused, with the command above in the error. An API key acts as a platform administrator only when it was created with --platform-admin and its owner still is one. Platform administrators give a second factor at every local sign-in.

Check what you can do#

weikio whoami prints who you are to the hub: the server, the key, the user, whether the key acts as a platform administrator, and the key’s grants as a table with its environments, integrations and APIs.

$ weikio whoami

In the admin UI, Settings › Access has Users, Roles, Project access, API keys, Providers and Claim mappings. A reader sees the pages their grants open: Project access and the audit log to a platform administrator and to a project’s admin, and Users, Agents, Providers and Health to a platform administrator alone.