2022-04-13 13:35:35 +00:00
# Authz
Package `authz` implements AuthoriZation for Coder.
## Overview
Authorization defines what **permission** a **subject** has to perform **actions** to **objects** :
2023-01-03 13:11:13 +00:00
- **Permission** is binary: _yes_ (allowed) or _no_ (denied).
2022-04-13 13:35:35 +00:00
- **Subject** in this case is anything that implements interface `authz.Subject` .
- **Action** here is an enumerated list of actions, but we stick to `Create` , `Read` , `Update` , and `Delete` here.
- **Object** here is anything that implements `authz.Object` .
## Permission Structure
A **permission** is a rule that grants or denies access for a **subject** to perform an **action** on a **object** .
A **permission** is always applied at a given **level** :
- **site** level applies to all objects in a given Coder deployment.
- **org** level applies to all objects that have an organization owner (`org_owner`)
- **user** level applies to all objects that have an owner with the same ID as the subject.
**Permissions** at a higher **level** always override permissions at a **lower** level.
The effect of a **permission** can be:
2023-01-03 13:11:13 +00:00
2022-04-13 13:35:35 +00:00
- **positive** (allows)
- **negative** (denies)
- **abstain** (neither allows or denies, not applicable)
**Negative** permissions **always** override **positive** permissions at the same level.
Both **negative** and **positive** permissions override **abstain** at the same level.
2023-01-03 13:11:13 +00:00
This can be represented by the following truth table, where Y represents _positive_ , N represents _negative_ , and \_ represents _abstain_ :
2022-04-13 13:35:35 +00:00
| Action | Positive | Negative | Result |
2023-01-03 13:11:13 +00:00
| ------ | -------- | -------- | ------ |
| read | Y | \_ | Y |
2022-04-13 13:35:35 +00:00
| read | Y | N | N |
2023-01-03 13:11:13 +00:00
| read | \_ | \_ | \_ |
| read | \_ | N | Y |
2022-04-13 13:35:35 +00:00
## Permission Representation
**Permissions** are represented in string format as `<sign>?<level>.<object>.<id>.<action>` , where:
- `negated` can be either `+` or `-` . If it is omitted, sign is assumed to be `+` .
- `level` is either `site` , `org` , or `user` .
- `object` is any valid resource type.
- `id` is any valid UUID v4.
- `action` is `create` , `read` , `modify` , or `delete` .
## Example Permissions
2022-06-04 20:13:37 +00:00
- `+site.*.*.read` : allowed to perform the `read` action against all objects of type `app` in a given Coder deployment.
2022-04-13 13:35:35 +00:00
- `-user.workspace.*.create` : user is not allowed to create workspaces.
## Roles
2023-01-03 13:11:13 +00:00
A _role_ is a set of permissions. When evaluating a role's permission to form an action, all the relevant permissions for the role are combined at each level. Permissions at a higher level override permissions at a lower level.
2022-04-13 13:35:35 +00:00
The following table shows the per-level role evaluation.
Y indicates that the role provides positive permissions, N indicates the role provides negative permissions, and _ indicates the role does not provide positive or negative permissions. YN_ indicates that the value in the cell does not matter for the access result.
2023-01-03 13:11:13 +00:00
| Role (example) | Site | Org | User | Result |
| --------------- | ---- | ---- | ---- | ------ |
| site-admin | Y | YN\_ | YN\_ | Y |
| no-permission | N | YN\_ | YN\_ | N |
| org-admin | \_ | Y | YN\_ | Y |
| non-org-member | \_ | N | YN\_ | N |
| user | \_ | \_ | Y | Y |
| | \_ | \_ | N | N |
| unauthenticated | \_ | \_ | \_ | N |