# The Phonograph Authorization Model Postgres provides a sophisticated role based access control (RBAC) system, which Phonograph leverages to apply permissions consistently across the web UI and inbound PostgreSQL connections. In order to efficiently pool database connections from the application server, most actions initiated via the web UI are run as the corresponding database user role using the [`SET ROLE` command](https://www.postgresql.org/docs/current/sql-set-role.html). `SET ROLE` **does not** provide great insulation against privilege escalation. **Queries which are not thoroughly validated and escaped must only be run via a dedicated connection initiated with the user-level role's credentials.** Given complete freedom it is possible, in fact easy, to configure a Postgres table into what would be considered an "invalid" state by Phonograph, so table creation and ownership is restricted to the "root" Phonograph role, which acts on the behalf of the user in order to facilitate schema updates via the web interface. ## Permissions Granted via User Roles ### Accessing workspace databases `GRANT CONNECT ON TO ;` This permission is granted when initially creating the workspace, as well as when accepting an invitation to a table. Access to workspaces is controlled via the `CONNECT ON DATABASE` permission. However, it is unreasonable to query every backing cluster to compute the set of workspaces to which a user has access, so Phonograph caches workspace-level "connect" permissions in its own centralized table (`workspace_memberships`). `workspace_memberships` rows are added whenever the `GRANT CONNECT` command is run, and are deleted after a `REVOKE CONNECT` command is run. It is possible that an error occurs after `REVOKE CONNECT` but before the membership record is deleted. Therefore for authorization purposes, membership of a workspace is not a guarantee that the user has `CONNECT` privileges, just that they might. The user's actual ability to connect to the database should always be confirmed before actually fetching data or metadata from a backing database. **Caution!** The Postgres database `CONNECT` privilege has no effect after a connection has been established, and _it is not re-checked by Postgres when running the `SET USER` command_. **The Phonograph server is solely responsible for managing top-level workspace permissions when accessing data via established, pooled connections.** ### Accessing the `phono` schema `GRANT USAGE ON TO ;` This permission is granted when initially creating the workspace, as well as when accepting an invitation to a table. ## Creating, updating, and deleting columns `GRANT TO ;` This permission is granted when initially creating the table, as well as when accepting an invitation to a table, if the invitation includes "owner" permissions. **This permission is only used via the web UI and must not be granted to service credentials, lest users alter table structure in unsupported ways.** ### Reading table data `GRANT SELECT ON
TO ;` This permission is granted when initially creating the table, as well as when accepting an invitation to the table. Phonograph uses `SELECT` permissions to infer whether a table should be accessible to a user via the web UI. ### Inserting rows `GRANT INSERT () ON
TO ;` Write-protected columns (`_id`, etc.) are excluded. This permission is granted when initially creating the table, as well as when accepting an invitation to the table, if the invitation includes "edit" permissions. These permissions must be updated for each relevant user role whenever a column is added; this is simplified by maintaining a single "writer" role per table. Note that granting insert or update privileges on specific columns will be reflected in relation ACLs (that is, in the `pg_class` table) as the corresponding privilege on the relation overall. In other words, a role listed as having insert and/or update permissions in a relation's ACL items might not have insert and/or update permissions to all columns. ### Updating rows `GRANT UPDATE () ON
TO ;` Write-protected columns (`_id`, etc.) are excluded. This permission is granted when initially creating the table, as well as when accepting an invitation to the table, if the invitation includes "edit" permissions. These permissions must be updated for each relevant user role whenever a column is added; this is simplified by maintaining a single "writer" role per table. Note that granting insert or update privileges on specific columns will be reflected in relation ACLs (that is, in the `pg_class` table) as the corresponding privilege on the relation overall. In other words, a role listed as having insert and/or update permissions in a relation's ACL items might not have insert and/or update permissions to all columns. ## Actions Facilitated by Root - Creating tables ## Service Credentials Direct user PostgreSQL connections are performed using secondary `LOGIN` roles created by the user's primary workspace role (where the primary workspace role is e.g. `usr_{user_id}`). The credentials for these secondary roles are referred to as "service credentials" or "PostgreSQL credentials". Service credentials are created and assigned permissions by users in the web UI, and their permissions are revoked manually in the web UI and/or by cascading `REVOKE` commands targeting the primary workspace role. Service credential role names have the format `svc_{user_id}_{8 chars (4 bytes) of random hex}`. With the user ID consuming 32 characters, this balances name length with an ample space for possible names.