Skip to content

Commit

Permalink
Update agreed upon product spec for Permissions
Browse files Browse the repository at this point in the history
  • Loading branch information
@pavish
pavish committed Jun 21, 2024
1 parent 099f736 commit 51609e6
Showing 1 changed file with 91 additions and 140 deletions.
231 changes: 91 additions & 140 deletions docs/product/specs/permissions-revamp.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,147 +7,98 @@ This spec describes the revamped product considerations for managing Permissions
1. Our current permission handling is custom written and managed entirely within the Mathesar service layer.
1. Several users have expressed interest towards using PostgreSQL roles, a few even mentioned that it's a blocker for them to start using Mathesar.
1. Building our permission layer on top of PostgreSQL's permission system is future-proof and robust.
1. We should try to maintain feature parity with the flows we currently have.
1. Provide a rudimentary UX for ownerships and get users aquainted with the concept.

## Features we intend to remove
* We will remove the ability to share credentials across databases.
- We currently have this while creating/configuring a database.
- We will revisit this feature later down the road when we have requirements from users.
* Mathesar admins will no longer be able to create a new database on external database servers (servers that do not contain the Django DB).
1. We should maintain feature parity with the flows we currently have.

## Terminologies
* User refers to Mathesar user.
* Admin refers to Mathesar admins.
* Admin refers to Mathesar admin.
* Role refers to PostgreSQL role/user.

## What we want the user to be able to do
### Adding/configuring a database
* A database should be unique. The same database cannot be added multiple times.
- This is a change from the existing setup where a database can be added multiple times with different connection credentials.
* We'll have separate onboarding instructions/flows in the UI for pre-existing and new databases.

#### Pre-existing database
* Mathesar admins should be able to configure a pre-existing database, using the following details:
- DB server Host
- DB server Port
- Database name
- PostgreSQL role -> username and password
* Mathesar admins should be able to optionally generate pre-defined roles for Editor, and Viewer, to partially satisfy Goal (B).
- This requires the PostgreSQL role used in the previous step to contain CREATEROLE attribute on the database server.
- This step is optional and Mathesar should function normally without these roles.
- We should make it clear that these roles & their privileges would only apply for new objects created via the Mathesar UI.
- For existing objects, we'll provide an option to iteratively provide privileges to these roles.
- This will however depend on ownerships of each object and can fail.
- We will no longer have the manager role as it would be the same as having admin access.
- Future consideration: We could provide a concept of database admins as a Mathesar level access control option per database. This will help maintain feature parity with the 'DB level admins' feature we currently have.
#### New database
* Mathesar admins should be able to create a new database on the internal database server by only entering the database name.
- This will use the same role utilized by the Django database.
- The user should be able to create new roles on the internal db and use them if they wanted to.
- The role used should contain both CREATEDATABASE and CREATEROLE privileges.
- (Internal database server refers to the database server that contains the Django DB. It could be on a different host)
* Pre-defined roles should be automatically created in this setup, similar to pre-existing databases.

### Role configuration
* Admins should be able to configure existing roles in a database server, within a database page.
- Wherever possible, we should reflect roles that already exist and let the admin add them by specifying the password.
* Admins should be able to create new roles within a database page.
- This will require the role used by the admin to have CREATEROLE privilege.
- The new roles will be created on the database server that the database belongs to and have CONNECT and CREATE privileges on the database.
- The new roles will also have SELECT access to all items on the database that the role used by the admin has.
* Future considerations:
- Roles exist on the database server and not under a database.
- However, inorder to simplify the user flow, we are not introducing a UX dedicated for database servers.
- We can explore this option in the future, based on user feedback or product strategy discussions.

### Access control options
#### Configuration
* Admins should be able to provide Mathesar users access to each database configured in Mathesar.
* Each standard Mathesar user should only be associated with a single role per database.
- Admins should be able to update this user-to-role configuration.
* All Mathesar admins should be able to access all databases configured in Mathesar.
- See 'Role for admins' section on how roles are used by Admins.
* Admins cannot be removed from a database.
* Standard Mathesar users can be added/removed from a database.
* Standard Mathesar users will not be able to access a database without being provided explicit access by a Mathesar admin.

#### Permission checks for objects
* The permissions for DB objects will be determined by the priviliges of the role the user is associated with.
* For Mathesar specific objects, we will have a setting per user per database that allows the user to 'read' or 'read-write'.
- This applies for explorations and metadata such as table and column settings.
- Future consideration:
- We can allow an additional option 'Infer from DB privileges' that will automatically identify access to each Mathesar-object based on the privileges on the underlying DB objects.

#### Role for admins
* An admin is not associated with a single role.
* Admins should be able to utilize any role that's configured for a database.
* When an admin opens a DB object, lets say a table,
- If the owning role of that table is configured, then any operation performed by the admin will utilize that role.
- If the owing role isn't configured, we'll try to figure out the best role for the admin to use. In cases where it's not possible, we will use the `default` role.
* More information is provided in the 'Default role' and 'Dealing with Ownership and Collaboration issues' sections of this document.

### Default role
* There should be one default role per database.
* When a database is first configured, the role used to connect to the database will be set as the default role.
- This role is used for installing/upgrading the functions on the DB.
* The default role cannot be removed.
- This will ensure that the admins have atleast one role to connect to the database.
* The default role cannot be changed.
- We can provide this option in the future.
- This restriction is to reduce scope since changing the default role has more considerations such as changing ownerships for the installed functions, which might affect upgrades.

### Dealing with Ownership and granting access
#### Considerations
* PostgreSQL has ownership for all DB objects.
* Tables/schemas created by one role cannot be viewed/accessed by another role, unless the access is granted explicitly.
* When tables/schemas are created via Mathesar UI, it may cause collaboration issues among Mathesar users if they utilize different roles.

#### Approach for tables
* When a table is created via the UI, the ownership will belong to the role of the Mathesar user that created that object.
* Admins will have access to all roles on the DB and hence will be able to use the role that created the table and obtain full ownership.
* Standard users associated with that role will be able to perform all operations.
* Ownerships should be conveyed on the UI for each table.
- This should show the owning role and the users associated with that role.
* Owners can GRANT access to the object to other roles via the UI, at the following levels:
- edit: SELECT, INSERT, UPDATE, DELETE
- view: SELECT
* They should also be able to do this in a granular manner if they choose to.
* Owners can also allow users to GRANT these privileges to other users.
* If a user has GRANT access for any of the privileges, they should be able to provide the same privilege with GRANT to others via the UI.
* We will utilize the same approach for other similar DB objects such as views, when we implement them.

#### Approach for schemas
* Schemas should display the owning role and all Mathesar users with access to that role.
* When creating a schema via the UI,
* Users should be able to set default privileges for the objects in the schema for other roles to use, while creating the schema.
* We should allow granting access at the following levels:
- edit: USAGE (for schema), SELECT, INSERT, UPDATE, DELETE
- view: USAGE (for schema), SELECT
* For existing schemas,
* Owners should be able to set default privileges for the objects in the schema, for other roles to use.
- This will be at the same levels as mentioned above.
* We should allow the user to iteratively update permissions for all existing objects present in the schema.
* There is a chance that the schema owner does not have access to an underlying table, in which case, we will not do anything.
- The owner of the table can still see that the schema owner does not have access and choose to provide access via Mathesar UI.
* Public schema:
- Public schema access changed in PG 15 where the database owner is now the owner for it and access to other roles needs to be explicitly granted.
- We'll detect PG version and have separate flows for PG version <15 and >=15.

#### Notes
* We will still face collaboration issues when objects are created outside of Mathesar, however, we could handle that by mentioning in our docs and on the UI to grant access to the 'default role' for any objects users create outside of Mathesar.
- This way Mathesar admins will have access to those objects and can grant privileges within Mathesar accordingly.

## Encapsulation
W.r.t. the UX, configuration of roles and connection details should be performed within the context of a database page.
* Within a database page, Mathesar should only present Postgres roles which have been explicitly configured for that specific database.
- If the admin would like to use the same role for multiple databases that exist on the same database server, they would have to configure it separately for each database in their respective pages.
* Operations like updating the connection details, such as host, port etc., and roles, should also exist within the context of a database page.
- Changing the password for a role should only affect the role configured for one database. If the user wants to change the password for the same role for another database, they would have to update it in it's respective database page, even if that database exists on the same PostgreSQL server.
- Similarly, changing the port number configured for one Mathesar user database should not affect the port number configured for other Mathesar user databases.

## Related
- [Brent's architecture notes](https://github.com/mathesar-foundation/mathesar-wiki/pull/108)
- [Permissions for Beta - approaches & comparison](https://hackmd.io/@mathesar/Hkads67nT)
- [Rough figma design to explain permissions approach for Beta](https://www.figma.com/file/S97Mma0hAy5Syh1w85RWoB/Permissions-UX?type=design&node-id=109-98&mode=design)
- [DB object ownership meeting](https://tldv.io/app/meetings/660d6f5b8b0707001237cf0e)
* Group refers to any PostgreSQL role that is inherited by another role.

## Adding a database
- Only Mathesar admins can add new databases.
- When adding a database:
- Mathesar admin will provide:
- database server host
- database server port
- database name
- a db login role username
- a db login role password

## Granting Mathesar users collaboration access to a database
- Only Mathesar admins can grant Mathesar users collaboration access to databases.
- Inorder to do add a Mathesar user as a collaborator to a database:
- Mathesar admins would have to specify a *Login DB role* for the Mathesar user to connect to the database.
- The *Login DB roles* will be automatically reflected. The admin can choose one of them.
- (Refer Role management section for more details).
- Admins can change their own login role.
- Only admins can change the login roles of other Mathesar users.
- Only admins can remove Mathesar users from a database.
- Initially, only the admin who connected to the database will have access to it.
- They will automatically be assigned the login role that was used to connect to the database.
- Any Mathesar admin can add themselves as a collaborator to any database configured in Mathesar.

## Role management
- Mathesar will reflect all roles in a database server.
- Inorder to configure a Login DB role in Mathesar:
- For a pre-existing login role,
- the admin would have to enter the password for the Login DB role and configure it in Mathesar.
- To create a new login role,
- the role used by the admin will need to have CREATEROLE privilege.
- the admin would have to specify a username and a password.
- this role will automatically get a CONNECT and CREATE privilege on the database.
- Admins can remove the configured login roles.
- This will simply remove the stored password in the internal database.
- The role will still be displayed but Mathesar cannot connect using the role since it would not have the password.
- Admins can drop login roles configured in Mathesar.
- If the admin's role has CREATEROLE privilege and ADMIN OPTION over a role ([Refer PG docs](https://www.postgresql.org/docs/current/sql-droprole.html#:~:text=To%20drop%20a%20superuser%20role,will%20be%20raised%20if%20so)), the admin will have an UI option to drop the role in the underlying DB.
- Before deleting a role, the objects owned by the role need to be transferred to another role/group.

## Group roles
- Any Mathesar user having a role that has CREATEROLE privilege can create new non-login roles (i.e. a group roles) via the Mathesar UI. ([Refer PG docs](https://www.postgresql.org/docs/current/role-membership.html)).
- The user's role that created a group role will be able to grant membership to it for other users' roles.
- This role would have ADMIN OPTION on the group role. We'll refer to it as admin access on the UI.
- When granting membership, the user that created the group can choose if other roles should have admin access or normal membership on the group role.
- If a role has admin access over a group, the users with that role can:
- grant/revoke memberships for other roles
- delete the group
- Before deleting a group, the objects owned by the group need to be transferred to another role/group.
- rename the group
- Normal members will only be able to use the group role for sharing ownerships. They will not be able to manipulate the group itself.
- For pre-existing roles on the database:
- Admin access can be determined for existing group roles on the database by checking if the user's role has ADMIN OPTION on it ([Refer PG docs](https://www.postgresql.org/docs/current/sql-grant.html#:~:text=The%20ADMIN%20option%20allows%20the,WITH%20ADMIN%20OPTION%20on%20itself)).
- Membership can be determined by checking if the user's role has SET ROLE, or INHERIT privileges.

## Ownership of DB objects
* When creating a new DB object, the user will have an option to choose the owner. They will not be able to create new roles here. They can set the owner to:
* their own login role (this is the default selection)
* one of the group roles they are a member of
* The owner of an object can transfer the ownership to any login or group role configured in Mathesar.

### Ownership of container objects
* Owning a container object such as a schema does not guarantee owning objects within it. We will make this behaviour clear to the user using appropriate documenation in the UI and our docs.
* We will support recursive reassignment of ownership of contained objects for which the user's role has ownership of. This will be an optional checkbox.
* For eg., while transfering ownership,
* for schemas, we will display a list of tables within it whose ownership belong to the user's role (or any of their group roles).
* the user can choose to transfer ownership for the schema along with this subset of tables within it.

## Providing access to DB objects
* The owner can provide access to DB objects to other roles in the following ways. We will present a dropdown in the case of schemas & tables.
* Database
* Connect to database (CONNECT)
* Create schemas in database (CREATE)
* No access
* Schema
* Use schema (USAGE)
* Create tables within schema (USAGE & CREATE)
* No access
* Table
* View table (SELECT)
* Edit table rows (SELECT, INSERT, UPDATE, DELETE)
* Custom (the user can select granular privileges)
* No access
* We will not allow any user other than the owner to manage permissions, for the beta release.
* This includes users who have WITH GRANT over some of the privileges.

## Explorations & Table Metadata
All Mathesar users will have full control over explorations & table metadata in the databases they have access to.

0 comments on commit 51609e6

Please sign in to comment.