From b2a53290c599cc68186d4dd80faa190206d2d396 Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Wed, 22 May 2024 15:08:24 -0400 Subject: [PATCH] Refactor the Database Object Permissions guide Closes #41917 Merge the Database Object Permissions guide into the Database Access RBAC guide for greater discoverability and a clearer division of labor between the two guides. This change also includes the following edits to make the refactor cleaner, since we can include each troubleshooting step as a separate H3 in the dateabase object permissions H2: - Remove an unnecessary troubleshooting step: One step indicates that import rules are validated, which is unnecessary to document, since validation errors are self explanatory. - Instead of mentioning the admin user as a troubleshooting step, add a separate H3 for the admin user and describe the `admin_user` field, which was not mentioned in the original database object permissions guide. --- docs/config.json | 4 - .../database-access-controls.mdx | 213 ----------------- docs/pages/database-access/rbac.mdx | 216 +++++++++++++++++- 3 files changed, 213 insertions(+), 220 deletions(-) delete mode 100644 docs/pages/database-access/auto-user-provisioning/database-access-controls.mdx diff --git a/docs/config.json b/docs/config.json index 69c686d9db214..44c07dbbea185 100644 --- a/docs/config.json +++ b/docs/config.json @@ -1268,10 +1268,6 @@ { "title": "PostgreSQL", "slug": "/database-access/auto-user-provisioning/postgres/" - }, - { - "title": "Database Access Controls", - "slug": "/database-access/auto-user-provisioning/database-access-controls/" } ] }, diff --git a/docs/pages/database-access/auto-user-provisioning/database-access-controls.mdx b/docs/pages/database-access/auto-user-provisioning/database-access-controls.mdx deleted file mode 100644 index 4229967ad055c..0000000000000 --- a/docs/pages/database-access/auto-user-provisioning/database-access-controls.mdx +++ /dev/null @@ -1,213 +0,0 @@ ---- -title: Database Access Controls -description: Understand the concepts behind Database Access Controls managed by Teleport. ---- - -{/*lint ignore messaging*/} -**Database Access Controls** is a Teleport feature that lets you configure -role-based access controls for database objects. A **database -object** can be a table, view, or stored procedure. With Database Access Controls, you can ensure that users only have permissions to manage the data -they need. - -You can define **import rules** that instruct the Teleport Database Service to -apply labels to database objects imported from databases that match labels configured within the import rule. When a user connects to a database, the Database Service selectively grants permissions by checking database object labels against the user's Teleport roles. - -The Database Service grants object-level permissions for the duration of a -connection and revokes them automatically when the connection ends. - -## Database object import rules - -A database object import rule in Teleport is a resource that defines the labels to be applied to database objects imported into Teleport. If a specific object does not match any of the rules, it will not be imported. - -By default, if no import rules are present (e.g. you create a fresh cluster or delete all your rules), Teleport will automatically create the `import_all_objects` rule on startup: - -```yaml -kind: db_object_import_rule -metadata: - name: import_all_objects -spec: - # Priority determines how important the rule is, with lower number indicating lower priority. - # In case of conflicts, when the same label is applied by two rules, - # the label applied by rule with higher priority wins. - priority: 0 - # database_labels is a filter specifying which database resources are in scope of this rule. - database_labels: - - name: '*' - values: - - '*' - # Each mapping, if matched, introduces a set of labels applied to database object. - # Database objects without labels are not imported. - mappings: - - add_labels: - database: '{{obj.database}}' - object_kind: '{{obj.object_kind}}' - name: '{{obj.name}}' - protocol: '{{obj.protocol}}' - schema: '{{obj.schema}}' - database_service_name: '{{obj.database_service_name}}' - # match adds objects to be imported; it cannot be empty. - match: - # list of all table names - table_names: - - '*' - # Additional mappings can be added here. - # - add_labels: ... -version: v1 -``` - -This rule will import all objects and label them by their inherent properties using the template syntax. - -Feel free to modify this rule with `tctl edit` to meet your specific requirements or add more rules. For instance, consider the following rule designed to designate particular tables as accessible to developers, either in a read-only or read-write capacity. - -```yaml -kind: db_object_import_rule -metadata: - name: ownership_nonprod -spec: - priority: 100 - database_labels: - # Affect `dev` and `staging` environments. - # Prod environment may have a different rule. - - name: 'env' - values: - - 'staging' - - 'dev' - - 'prod' - mappings: - # Apply project label - - add_labels: - project: horizon - # match section is mandatory and must contain at least one non-empty subsection - match: - table_names: - - '*' - # scope is the optional section which enables further filtering of objects by database and schema names. When omitted, this filtering is disabled. - scope: - database_names: - - 'horizon' - - 'horizon_v2' - schema_names: - - 'application' - - 'data_import' - # Add `dept: hr` label for respective tables. - - add_labels: - dept: hr - match: - table_names: - - '*' - scope: - schema_names: - - 'recruitment' - - 'salaries' - - 'pto' - - 'hr_scratchpad' -version: v1 -``` - -Save the rule to a file and execute `tctl create -f ownership_nonprod.yaml` to create it in Teleport. - -## Database permissions in roles - -To grant user permissions during a database connection, the user must be associated with a role that meets specific criteria: -- `spec.allow.db_labels` must match the database labels of particular database. -- Database user auto-provisioning should be enabled (`spec.options.create_db_user_mode` not set to `off` or `spec.options.create_db_user: true`). -- The label key/value pairs in `spec.allow.db_permissions.match` should correspond to the labels on the specific database object. - -The labels on the table must be matched with an appropriate role. Here's an example of a role that utilizes the `dept` label, applied by the `ownership_nonprod` rule, granting read-only access to HR records in the database. The `hr_scratchpad` table is further made editable. On the other hand, any objects labeled `dept: sales` are made unavailable by removing all permissions a user may have received for them. The wildcard permissions are only allowed in the `deny` part of the spec (`spec.deny.db_permissions`). - -```yaml -kind: role -metadata: - name: dept_hr_permissions -spec: - allow: - db_labels: - '*': '*' - db_names: - - '*' - db_permissions: - # default permission: read-only - - match: - object_kind: table - dept: hr - permissions: - - SELECT - # extra permissions for select tables - - match: - object_kind: table - dept: hr - name: hr_scratchpad - permissions: - - SELECT - - UPDATE - - DELETE - - INSERT - deny: - db_permissions: - # explicitly disallow any interaction with `dept: sales` tables. - - match: - dept: sales - permissions: - - '*' - options: - create_db_user_mode: keep -version: v7 -``` - -## Permissions lifecycle and consistency - -A user can maintain multiple simultaneous connections to the same database. All connections must possess identical permissions; otherwise, a new connection will be rejected. Upon the termination of the last active connection, all user permissions are automatically revoked. - -## Troubleshooting - - -### Checking the logs - -To diagnose the import process, refer to the Database Service logs to find details such as the number of objects fetched from the database, the number of imported objects (the difference comprising objects not matched by any import rule), and finally, the number of objects for which the user has been granted permissions. - -{/* spell-checker: disable */} -```code -INFO [DB:SERVIC] Database objects fetched from the database (table:75). db:my-postgres id:b4a33740-1d82-4a8d-b2be-2aa90ae9d2eb total:75 postgres/users.go:212 -INFO [DB:SERVIC] Database objects imported (table:75). db:my-postgres err_count:0 id:b4a33740-1d82-4a8d-b2be-2aa90ae9d2eb total:75 postgres/users.go:216 -INFO [DB:SERVIC] Calculated database permissions: "INSERT": 75 objects (table:75), "SELECT": 75 objects (table:75), "UPDATE": 75 objects (table:75). db:my-postgres id:b4a33740-1d82-4a8d-b2be-2aa90ae9d2eb user:teleport-user postgres/users.go:223 -``` -{/* spell-checker: enable */} - -### Invalid database admin user permissions - -The database admin user, referred to as `teleport-admin` in this documentation, is responsible for granting permissions to end users. Ensure that the admin user possesses the necessary permissions; otherwise, this action might fail. - -```bash -tsh db connect postgres-db --db-name postgres --db-user teleport-user -psql: error: connection to server at "localhost" (::1), port 50800 failed: Connection refused - Is the server running on that host and accepting TCP/IP connections? -connection to server at "localhost" (127.0.0.1), port 50800 failed: your Teleport role requires automatic database user provisioning but an attempt to activate database user "teleport-user" failed due to the following error: ERROR: permission denied for table pg_subscription (SQLSTATE 42501) -ERROR: exit status 2 -``` - -### Invalid import rules - -Import rules undergo validation upon creation. An invalid rule will trigger an error during tctl create. For instance: - -```yaml -... - mappings: - - add_labels: - invalid_label: '{{' -... -``` - -Will cause error: - -```shell -> tctl create -f import_all_objects_invalid.yaml -ERROR: validating rule - mapping value failed to parse as template - "{{" is using template brackets '{{' or '}}', however expression does not parse, make sure the format is {{expression}} -``` - -## Next steps - -- Read automatic user provisioning [RFD](https://github.com/gravitational/teleport/blob/master/rfd/0113-automatic-database-users.md). -- Read database permission management [RFD](https://github.com/gravitational/teleport/blob/master/rfd/0151-database-permission-management.md) - diff --git a/docs/pages/database-access/rbac.mdx b/docs/pages/database-access/rbac.mdx index b4dfbb86bc1b6..df536e67e5215 100644 --- a/docs/pages/database-access/rbac.mdx +++ b/docs/pages/database-access/rbac.mdx @@ -16,7 +16,7 @@ this section focuses on configuring RBAC for database access. ## Role configuration -Teleport's "role" resource provides the following instruments for restricting +Teleport's role resource provides the following instruments for restricting database access: ```yaml @@ -77,7 +77,7 @@ spec: or database account) will be rejected. -## Database names +### Database names There's a distinction in how different database servers handle logical databases which leads to a difference in how `db_names` role field is applied to a connection @@ -94,7 +94,7 @@ the scope of permissions a user has once connected is determined by the permissi grants set on the account within the database. As such, `db_names` role field is not currently enforced on MySQL connection attempts. -## Template variables +### Template variables Similar to other role fields, `db_*` fields support templating variables. @@ -138,3 +138,213 @@ spec: db_users: ["{{internal.db_users}}"] db_names: ["{{internal.db_names}}"] ``` + +## Database object import rules + +A database object import rule in Teleport is a resource that defines the labels +to be applied to database objects imported into Teleport. If a specific object +does not match any of the rules, it will not be imported. + +### Default import rule + +By default, if no import rules are present (e.g. you create a fresh cluster or +delete all your rules), Teleport will automatically create the +`import_all_objects` rule on startup: + +```yaml +kind: db_object_import_rule +metadata: + name: import_all_objects +spec: + # Priority determines how important the rule is, with lower number indicating lower priority. + # In case of conflicts, when the same label is applied by two rules, + # the label applied by rule with higher priority wins. + priority: 0 + # database_labels is a filter specifying which database resources are in scope of this rule. + database_labels: + - name: '*' + values: + - '*' + # Each mapping, if matched, introduces a set of labels applied to database object. + # Database objects without labels are not imported. + mappings: + - add_labels: + database: '{{obj.database}}' + object_kind: '{{obj.object_kind}}' + name: '{{obj.name}}' + protocol: '{{obj.protocol}}' + schema: '{{obj.schema}}' + database_service_name: '{{obj.database_service_name}}' + # match adds objects to be imported; it cannot be empty. + match: + # list of all table names + table_names: + - '*' + # Additional mappings can be added here. + # - add_labels: ... +version: v1 +``` + +This rule will import all objects and label them by their inherent properties using the template syntax. + +### Customizing the default import rule + +You can modify the default `db_object_import_rule` as you would any other +Teleport resource. + +For instance, consider the following rule designed to designate particular +tables as accessible to developers, either in a read-only or read-write +capacity: + +```yaml +kind: db_object_import_rule +metadata: + name: ownership_nonprod +spec: + priority: 100 + database_labels: + # Affect `dev` and `staging` environments. + # Prod environment may have a different rule. + - name: 'env' + values: + - 'staging' + - 'dev' + - 'prod' + mappings: + # Apply project label + - add_labels: + project: horizon + # match section is mandatory and must contain at least one non-empty subsection + match: + table_names: + - '*' + # scope is the optional section which enables further filtering of objects by database and schema names. When omitted, this filtering is disabled. + scope: + database_names: + - 'horizon' + - 'horizon_v2' + schema_names: + - 'application' + - 'data_import' + # Add `dept: hr` label for respective tables. + - add_labels: + dept: hr + match: + table_names: + - '*' + scope: + schema_names: + - 'recruitment' + - 'salaries' + - 'pto' + - 'hr_scratchpad' +version: v1 +``` + +### Database admin user + +A database admin user is responsible for granting permissions to end users. You +must specify a database admin user before using database object import rules. To +specify a database admin user, add the following to a role that restricts +database object permissions: + +```yaml +spec: + # ... + admin_user: "teleport-admin" + # ... +``` + +In this case, the Teleport Database Service expects to activate a user called +`teleport-admin` in order to execute object import rules. Ensure that the admin +user possesses the necessary permissions to manage users in your database, +otherwise object import rules might fail, depending on how you have configured +the database: + +```code +$ tsh db connect postgres-db --db-name postgres --db-user teleport-user +psql: error: connection to server at "localhost" (::1), port 50800 failed: Connection refused + Is the server running on that host and accepting TCP/IP connections? +connection to server at "localhost" (127.0.0.1), port 50800 failed: your Teleport role requires automatic database user provisioning but an attempt to activate database user "teleport-user" failed due to the following error: ERROR: permission denied for table pg_subscription (SQLSTATE 42501) +ERROR: exit status 2 +``` + +### Executing database object permission rules + +The Teleport Database Service checks the roles associated with a user before +allowing that user to connect to a database. + +To grant database object permissions during a database connection, the user must +be associated with a role that meets specific criteria: +- `spec.allow.db_labels` must match the database labels of particular database. +- Database user auto-provisioning must be enabled + (`spec.options.create_db_user_mode` not set to `off` or + `spec.options.create_db_user: true`). +- The label key/value pairs in `spec.allow.db_permissions.match` must correspond + to the labels on the specific database object. + +A user can maintain multiple simultaneous connections to the same database. All +connections must possess identical permissions; otherwise, a new connection will +be rejected. Upon the termination of the last active connection, all user +permissions are automatically revoked. + +The labels on the table must be matched with an appropriate role. Here's an +example of a role that utilizes the `dept` label, applied by the +`ownership_nonprod` rule, granting read-only access to HR records in the +database. The `hr_scratchpad` table is further made editable. On the other hand, +any objects labeled `dept: sales` are made unavailable by removing all +permissions a user may have received for them. The wildcard permissions are only +allowed in the `deny` part of the spec (`spec.deny.db_permissions`): + +```yaml +version: v7 +kind: role +metadata: + name: dept_hr_permissions +spec: + allow: + db_labels: + '*': '*' + db_names: + - '*' + db_permissions: + # default permission: read-only + - match: + object_kind: table + dept: hr + permissions: + - SELECT + # extra permissions for select tables + - match: + object_kind: table + dept: hr + name: hr_scratchpad + permissions: + - SELECT + - UPDATE + - DELETE + - INSERT + deny: + db_permissions: + # explicitly disallow any interaction with `dept: sales` tables. + - match: + dept: sales + permissions: + - '*' + options: + create_db_user_mode: keep +``` + +### Troubleshooting object import rules + +To diagnose issues with importing database objects, refer to the Teleport +Database Service logs. These indicate the number of objects fetched from the +database, the number of imported objects (the difference comprising objects not +matched by any import rule), and the number of objects for which the user has +been granted permissions: + +```text +INFO [DB:SERVIC] Database objects fetched from the database (table:75). db:my-postgres id:b4a33740-1d82-4a8d-b2be-2aa90ae9d2eb total:75 postgres/users.go:212 +INFO [DB:SERVIC] Database objects imported (table:75). db:my-postgres err_count:0 id:b4a33740-1d82-4a8d-b2be-2aa90ae9d2eb total:75 postgres/users.go:216 +INFO [DB:SERVIC] Calculated database permissions: "INSERT": 75 objects (table:75), "SELECT": 75 objects (table:75), "UPDATE": 75 objects (table:75). db:my-postgres id:b4a33740-1d82-4a8d-b2be-2aa90ae9d2eb user:teleport-user postgres/users.go:223 +```