RFC: RBAC Support for PD

text/2020-12-16-pd-rbac.md

@@ -0,0 +1,150 @@
+# RBAC Support for PD
+
+## Summary
+
+Here we propose adding RBAC to PD so that all requests to PD must be authenticated,
+and clients may only do actions they are explicitly authorized to perform.
+
+This RFC is a partial implementation of [tikv/8621](https://github.com/tikv/tikv/issues/8621)
+that describes a way to support RBAC-based data access control for TiKV and PD.
+
+## Motivation
+
+PD server exposes its APIs to the network via HTTP or gRPC endpoints.
+
+Currently, clients knowing the PD address have full access to PD APIs.
+This poses a threat to the PD and TiKV cluster.
+
+If a PD server is exposed or a client is compromised, an attacker may freely
+read the status of the PD cluster and perform destructive actions.
+
+And in some cases, we may want to authorize a client (most likely some utility)
+access to a subset of PD APIs, which can’t be realized without an auth system.
+
+Once RBAC support is added into PD, we may assign specific permissions to a client,
+and make sure no client may perform actions beyond its need, minimizing the potential
+outcome of a security breach.
+
+Utilities requiring direct access to PD may gain limited access to it with a user
+created earlier by an administrator.
+
+## Detailed design
+
+### Authentication
+
+- PD stores `User`s in a KV database (etcd).
+  - Username: string
+  - Hash: string (sha256)
+  - Roles: a set of strings (role names)
+- A client (TiDB/TiKV/pd-ctl/…) must provide a pair of username and password to
+  gain access to PD APIs (including HTTP and gRPC endpoints).
+  - Clients using HTTP APIs should send requests with a basic authentication header.
+  - Clients using gRPC should set its username and password in the meta field.
+- What resources the client may have access to and what actions it may perform
+  depends on the roles that are authorized to this user, which is covered in the
+  following section.
+- Users can be created, modified or deleted by an existing user with admin access
+  (also covered in the next section). An initial admin user can be pre-defined
+  in the config file.
+- The whole authentication and authorization mechanism can be enabled by setting
+  the `authentication` option to `true` in the config file or command-line arguments.
+  Once activated, requests without a valid pair of username and password will be
+  rejected.
+
+### Authorization
+
+- First, we define `Permission` to represent a specific operation.
+  - Resource (eg. Stores, Regions, …)
+  - Action (one of GET, CREATE, UPDATE, DELETE)
+- Then we map every API handler to a `Permission`.For example, `GET` `/api/v1/operators`
+  maps to `Permission{resource: "Operators", action: GET}`.
+- `Role` is stored in a KV database (etcd).
+  - Name: string
+  - Permissions: a set of `Permission`s
+- Whether a user has access to an API is determined by its roles, and permissions
+  included in each role. When validating a request, we generate a `Permission` by
+  the requested API, and check if any role of this user has it.
+- There’s a special role called `Admin` that grants access to administrative APIs
+  of RBAC control. The initial admin user defined in the config file is assigned
+  with this role automatically.
+
+### Modifications
+
+- Implement `RBACManager` to handle user & role related CRUD operations.
+  - Query users & roles in memory cache.
+  - Load them from KV.
+  - Persist them into KV.
+  - Validate user hash & permission.
+- Add administrative APIs
+  - GET /user
+    - Query user info of current request.
+    - `{"user": "blabla", "roles": ["reader", …]}`
+  - GET /users
+    - List all usernames and their roles.
+  - POST /users
+    - Create a new user.
+    - `{"username": "blabla", "roles": []}`
+  - GET /users/`<user>`
+    - Query user info
+    - `{"username": "blabla", "roles": ["reader", …]}`
+  - POST /users/`<user>`/password
+    - Edit user password.
+    - `{"password": "blabla"}`
+  - POST /users/`<user>`/roles
+    - Set user roles.
+    - `{"roles": ["reader", "writer", …]}`
+  - POST /users/`<user>`/roles/add
+    - Add a role to user.
+    - `{"role": "admin"}`
+  - DELETE /users/`<user>`/roles
+    - Delete a role from user.
+    - `{"role": "admin"}`
+  - GET /roles
+    - List all usernames and their roles.
+    - `[{"name": "reader", "permissions": [{"resource": "Operators", "action": "GET"},…]},…]`
+  - POST /roles
+    - Create a new role.
+    - `{"name": "writer", "permissions": [{"resource": "Operators", "action": "UPDATE"},…]}`
+  - GET /roles/`<role>`
+    - Query role info
+    - `{"name": "reader", "permissions": [{"resource": "Operators", "action": "GET"},…]}`
+  - POST /roles/`<role>`
+    - Set role permissions.
+    - `{"permissions": […]}`
+  - POST /roles/`<role>`/add
+    - Add a permission to role.
+    - `{"permission": {...}}`
+  - DELETE /roles/`<role>`
+    - Delete a permission from role.
+    - `{"permission": {...}}`
+- Add middlewares to HTTP router and gRPC handlers
+  - Rejects any request without a valid pair of username & password.
+  - Maps requested handler to a `Permission`.
+  - Rejects the request if the current user doesn’t have the required permission.
+- Modify pd-ctl, TiKV and TiDB to send requests with user credentials.
+
+### How Clients Interact with PD
+
+- The administrator deploys PD cluster and creates initial users with TiDB/TiKV
+  specific permissions (there are pre-defined roles for TiDB and TiKV).
+- TiDB/TiKV may access PD with these users.
+- pd-ctl and other utils may access PD with the admin user or any existing user.
+  Logging with an unprivileged user may restrict actions these tools may perform.
+
+## Alternatives
+
+### Certificate & Token-based PD Auth
+
+This method is mentioned in [rfcs/46](https://github.com/tikv/rfcs/pull/46).
+This implementation is great generally, but it lacks the ability to have fine-grained
+control on PD APIs.
+
+The idea of authenticating with certificates and its design of tokens is great though.
+We may combine it with the design proposed with this RFC in the future by making
+minor modifications to the administrative APIs and data models, and implementing
+a token issuing and refreshing mechanism.
+
+## Future Additions
+
+- Token-based authentication.
+- Compatible with [rfcs/46](https://github.com/tikv/rfcs/pull/46).