Roles and permissions

Two things decide whether a member may call a route:

• The route lists the permissions it needs, as required_labels.
• The member’s role grants permissions, from your deployment’s roles file.

The gateway checks them before your service is called. Your service never sees a role.

The roles file

roles.yml

roles:
  owner: ["*"]
  admin: [org:write, org:members:write, org:service-accounts:write, org:audit:read, projects:write]
  member: [projects:write]
creator_role: owner
default_role: member

• Each role grants a list of labels. ["*"] grants every label.
• creator_role is given to whoever creates an organization. default_role is given when a member is added without one.
• Plat5 names no roles. owner, admin and member are the starter file’s; rename or replace them.

Identity reads the file at boot. Edit it and restart identity (plat5 start does this for you locally). Credentials pick up a role change within the gateway’s cache window, five minutes by default.

Route permissions

routes.yml

- path: /org/projects/{project_id}
  upstream: /organizations/{subject.organization_id}/projects/{path.project_id}
  methods:
    GET:
    PATCH:
      required_labels: [projects:write]
    DELETE:
      required_labels: [projects:write]

A member needs any one of a route’s labels. A route without required_labels admits any member of the organization. A missing label is a 403 that names the labels the route needed.

Roles off

Leave out the roles file and roles are off for the whole deployment: no member has a role, and every member holds every label. Use this when something else decides who may call what.

Per-resource access

Roles decide which routes a member may call, not which project they may touch. Access to individual resources, like private projects, is planned through an optional policy engine.

More: roles.md.