User Access and Roles

Roles and permissions

The RBAC model, and how a permission reaches an access token
Report issue

Authorization in CSI Auth is role-based. Permissions are defined on an API, grouped into roles, and roles are assigned to users. An access token carries the resulting permissions as scopes, and the receiving service enforces them.

The model

API ──defines──▶ Permission ──grouped into──▶ Role ──assigned to──▶ User
                                                          │
                                                          ▼
                                              Access token scopes

Permissions

A permission belongs to one API and is named action:resource, for example read:users. Define permissions around what a caller needs to do, not around the shape of your database.

Roles

A role is a named set of permissions. Roles should describe a job, such as csi-support-agent, not a single capability.

Assigning roles

Roles can be assigned to a user directly, or scoped to an organization so the same person holds different roles in different organizations.

A change to a user’s roles takes effect on their next token. Tokens already issued keep the permissions they were minted with until they expire.

How permissions reach the token

RBAC has to be enabled on the API, with permissions added to the access token. Once it is, the authorization server includes the user’s permissions in the token’s scopes.

Enforcing permissions in a service

Validate the token, then check the specific scope the endpoint requires. Do not infer authorization from the user’s identity or from a role name embedded in a claim.

Designing a permission set

  • Start from the operations a caller performs, and name one permission per operation
  • Keep read and write separate
  • Add a permission when a new operation appears, rather than widening an existing one
  • Review what each role grants when the product changes

Anti-patterns

  • Putting entitlements in user_metadata, which the user can change
  • A single admin role that every internal tool requests
  • Checking a role name instead of a permission
  • Granting a machine-to-machine client every scope on an API so it never fails