Skip to content

Commit c97c07c

Browse files
author
Metabase Docs bot
committed
[auto] adding content to SEM-349-lighter->master
1 parent 0945304 commit c97c07c

File tree

10 files changed

+54
-236
lines changed

10 files changed

+54
-236
lines changed

_docs/master/databases/connections/mongodb.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ Learn more about [configuring SSL with MongoDB](http://mongodb.github.io/mongo-j
121121

122122
## How Metabase syncs data in MongoDB
123123

124-
Because MongoDB contains unstructured data, Metabase takes a different approach to syncing your database's metadata. To get a sense of the schema, Metabase will query the first and last 500 documents (most of the calculation is done in MongoDB). This sampling helps Metabase do things like differentiate datetime fields from string fields, and provide people with pre-populated filters. Metabase also syncs 1,000 leaf fields (fields at the deepest nesting level) per MongoDB collection. The reason Metabase only scans a sample of the documents is because scanning every document in every collection on every sync would put too much strain on your database. And while the sampling does a pretty good job keeping Metabase up to date, it can also mean that new fields can sometimes fall through the cracks, leading to visualization issues, or even fields failing to appear in your results. For more info, check out our [troubleshooting guide](../../troubleshooting-guide/db-connection).
124+
Because MongoDB contains unstructured data, Metabase takes a different approach to syncing your database's metadata. To get a sense of the schema, Metabase will query the first and last 500 documents (most of the calculation is done in MongoDB). This sampling helps Metabase do things like differentiate datetime fields from string fields, and provide people with pre-populated filters. The reason Metabase only scans a sample of the documents is because scanning every document in every collection on every sync would put too much strain on your database. And while the sampling does a pretty good job keeping Metabase up to date, it can also mean that new fields can sometimes fall through the cracks, leading to visualization issues, or even fields failing to appear in your results. For more info, check out our [troubleshooting guide](../../troubleshooting-guide/db-connection).
125125

126126
## General connectivity concerns
127127

_docs/master/developers-guide/driver-changelog.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,11 @@ layout: new-docs
3131

3232
- Added a feature `:expressions/today` for drivers that support generating a date for the current day.
3333

34+
## Metabase 0.55.8
35+
36+
- Add multi-method `driver/do-with-resilient-connection` for executing functions in a context where closed connections may be automatically reopened
37+
38+
3439
## Metabase 0.55.0
3540

3641
- Add the multi-method `->date` that allows the driver to control how to cast strings and temporal types to dates.
Binary file not shown.
Binary file not shown.

_docs/master/permissions/impersonation.md

Lines changed: 18 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -21,138 +21,48 @@ This page covers the [View data](./data#view-data-permissions) permission level
2121

2222
**Impersonation access** allows admins to "outsource" View data permissions to roles in your database. Admins can associate user attributes with database-defined roles and their privileges. If someone is in a group with their View data permission set to Impersonation, the person will be able to view and query data based on the privileges granted to the role specified by their user attribute.
2323

24-
## Impersonation vs sandboxing
24+
## Setting up connection impersonation
2525

26-
### Impersonation sets permissions for questions written in both the SQL editor and the query builder
27-
28-
Impersonation operates at the database level. In a database engine, setting the role before the query runs can alter the results of the query, as the role defines the permissions that your database should use when it executes the statements.
29-
30-
### Sandboxing only sets permissions for query builder questions
31-
32-
Sandboxing operates at the Metabase level. Since Metabase can't parse SQL queries to find out what data people are allowed to view, sandboxing only applies to questions composed in the query builder (where Metabase can interpret the queries).
33-
34-
## Example use case for impersonation
35-
36-
Let's say we have a People table that includes rows of accounts from all 50 states of the United States. Let's say you want your Vermont sales team to:
37-
38-
- Be able to ask questions using both the query builder and the native SQL editor.
39-
- Only be able to view customer accounts in the People table who live in Vermont.
40-
41-
First, you'll set up permissions in your database by creating a role with a policy. Then in Metabase, you'll set data access to that database to Impersonation, so when people run queries on that database, Metabase will use that role to limit what data they can see.
42-
43-
## Set up connection impersonation
26+
> \*\*For impersonation to work for Redshift databases, the user account Metabase uses to [connect to your Redshift database](../databases/connections/redshift) must be a superuser, as Metabase will need to be able to run the [SET SESSION AUTHORIZATION](https://docs.aws.amazon.com/redshift/latest/dg/r_SET_SESSION_AUTHORIZATION) command, which can only be run by a database superuser.
4427
4528
For impersonation access to work, you'll first need to set up roles in your database for Metabase to impersonate, then configure Metabase to impersonate those roles when people view or query data.
4629

47-
### Set up Metabase database connection for impersonation
48-
49-
Impersonation uses database roles to run queries on your database, but there still needs to be a default role that that will be used to run operations like [sync, scans, and fingerprinting](../databases/sync-scan). So the user account that Metabase uses to [connect to your database](../databases/connecting) should have access to everything in that database that any Metabase group may need access to, as that database user account is what Metabase uses to sync table information.
50-
51-
You can then create roles in the database that have more restrictive access to the database (like row-level or table-level security). When the role is passed to the database using impersonation, the engine will return a subset of the data, or restrict the query altogether.
52-
53-
> For **Redshift** databases, the user account Metabase uses to [connect to your Redshift database](../databases/connections/redshift) must be a superuser, as Metabase will need to be able to run the [SET SESSION AUTHORIZATION](https://docs.aws.amazon.com/redshift/latest/dg/r_SET_SESSION_AUTHORIZATION) command, which can only be run by a database superuser.
54-
5530
### In your database, set up roles
5631

57-
In your database (not in Metabase):
58-
59-
1. Create a new database role (in Redshift, this would be a new user).
60-
2. Grant that role privileges that you'd like impersonated users to have..
32+
1. Create a new role (in Redshift, this would be a new user).
33+
2. Grant that role privileges.
6134

6235
For exactly how to create a new role in your database and grant that role privileges, you'll need to consult your database's documentation. We also have some docs on [users, roles, and privileges](../databases/users-roles-privileges) that can help you get started.
6336

64-
For example, if you're using PostgreSQL, the SQL below will create a role called `vermont_sales_team` and only allow that role to select rows in the `people` table where the value in the `state` column is `VT` (the abbreviation for Vermont):
65-
66-
```sql
67-
CREATE ROLE vermont_sales_team;
68-
69-
GRANT
70-
SELECT ON ALL TABLES IN SCHEMA PUBLIC TO vermont_sales_team;
71-
72-
73-
CREATE POLICY vermont ON people
74-
FOR
75-
SELECT TO vermont_sales_team USING (state = 'VT');
76-
77-
78-
ALTER TABLE people ENABLE ROW LEVEL SECURITY;
79-
```
80-
81-
### Set up a Metabase group
82-
83-
Permissions in Metabase, including impersonation, are managed by groups, so you'll need to:
84-
85-
1. [Create a new group](../people-and-groups/managing#groups) (or select an existing one).
86-
2. [Add people to the group](../people-and-groups/managing#adding-people-to-groups).
87-
88-
You might want to create a test user and add them to the group to verify later that impersonation is working correctly.
37+
### In your Metabase, set up impersonation and specify a user attribute
8938

90-
### Assign a user attribute to people in the group
39+
1. **Create a [new group](../people-and-groups/managing#groups)**, or select an existing group.
9140

92-
To associate people in the group with a role that you created in your database, you'll use a user attribute.
41+
2. **Assign a [user attribute](../people-and-groups/managing#adding-a-user-attribute) to people in that group.** You'll use this user attribute to associate people in that group with a role that you created in your database. For example, if you created a role named `sales` in your database with access to a subset of tables relevant to the sales team, you would add a user attribute called `db_role` (or whatever you want to call the attribute) and assign the value `sales` to the person's `db_role`. The value of the attribute (`sales` in this case) should match the name of the role in your database. Only some databases enforce case sensitivity, so you might want to make sure the attribute's value and the database's role match exactly.
9342

94-
Assign a [user attribute](../people-and-groups/managing#adding-a-user-attribute) to people in your group:
43+
3. **Apply the impersonation access to that group.**. Hit Cmd/Ctrl + K to bring up the command palette. Search for **Permissions**. Or go to **Admin settings** > **Permissions** > **Data**.
9544

96-
- The **key** of the attribute can be anything.
97-
- The **value** of the attribute must match the desired database role for every person.
45+
4. Select the database you want to set permissions on.
9846

99-
![Setting a user attribute for impersonation](./images/user-attribute-impersonation.png)
47+
5. Find the group that you want to associate with the database role you created. Under **View data** setting for that group, select **Impersonation**.
10048

101-
For example, if you created a role named `vermont_sales_team` in your database with access to a subset of data relevant to the Vermont sales team (like [in the example above](#in-your-database-set-up-roles)), you could add a user attribute called `db_role` (or whatever you want to call the attribute) and assign the value `vermont_sales_team` to the person's `db_role` attribute.
49+
6. From the dropdown, select the user attribute that you added that maps to the role you want the group to use when querying the database.
10250

103-
Some databases enforce case sensitivity, so you might want to make sure the attribute's value and the database's role match exactly.
104-
105-
People in one group can have different attribute values, but must have the same attribute key. See [People in a group with impersonation access to data do not necessarily share the same privileges](#people-in-a-group-with-impersonation-access-to-data-do-not-necessarily-share-the-same-privileges).
106-
107-
### Set up impersonation
108-
109-
1. In Metabase, hit Cmd/Ctrl + K to bring up the command palette and search for **Permissions**, or go directly to **Admin settings** > **Permissions** > **Data**.
110-
111-
2. Select the group that you want to to associate with the database role you created.
112-
113-
3. Select the database to configure access to.
114-
115-
4. Under **View data** setting for that database, select **Impersonation**. This option will only be visible if you already [created a user attribute](#assign-a-user-attribute-to-people-in-the-group).
116-
117-
![Select impersonated permissions](./images/select-impersonated.png)
118-
119-
If your All Users group has more permissive access to this database (for example, "Can view"), you will see a warning, because [Metabase gives people the most permissive access to data across all of their groups](#metabase-gives-people-the-most-permissive-access-to-data-across-all-of-their-groups). You'll need to [block database access for the All Users group](./data#revoke-access-even-though-all-users-has-greater-access) before setting up impersonation.
120-
121-
5. From the user attribute dropdown, select the user attribute that you added that maps to the role you want the group to use when querying the database.
122-
123-
6. Save your changes.
124-
125-
Remember to also set up ["Create queries"](./data#create-queries-permissions) permissions for your group and database. For example, if you'd like people to be able to write SQL while using impersonated database roles, you'll need to set "Create queries" permissions to "Query builder and native".
126-
127-
### Verify that impersonated permissions are working
128-
129-
Admins will not be able to verify that impersonation is are working from their own account, so you should create a test user, add them to the group and set up their user attributes.
130-
131-
To verify that the impersonated permissions are working:
132-
133-
- If the test user has "Create queries" permissions set to "Create queries and native", create a SQL question and verify that the test user can only see the right data.
134-
135-
For example, for the `vermont_sales_team` role from the [example above](#in-your-database-set-up-roles), you can run:
136-
137-
```
138-
SELECT * FROM people;
139-
```
140-
141-
to verify that the test user only sees data from Vermont.
142-
143-
- If the test user has "Create queries" permissions set to "Query builder only", go to **Browse data** in the left sidebar and verify that the user can only see the tables they have access to, and only the data in those tables that
51+
7. Save your changes.
14452

14553
## People in a group with impersonation access to data do not necessarily share the same privileges
14654

14755
Metabase will use whatever role you specify in the user attribute for each person. E.g., if you select the `db_role` attribute for impersonation, one person's `db_role` could be `sales`, another person's could be `engineering`, or whatever other value that maps to a valid role in your database.
14856

14957
## Use impersonation to set up row-level SQL access
15058

151-
You can use impersonation to give people access to the SQL editor, while restricting their access to data based on a specific database role. And not just table-level access, but row-level access---or however you define access for that role in your database. Effectively, you can use impersonation to set up data sandbox-like access to your data, while letting people use the SQL editor to query that data. The difference is that, _instead of setting up a data sandbox in Metabase, you need to set up that row-level security via the privileges granted to a role in your database._
59+
You can use impersonation to give people access to the native/SQL editor, while restricting their access to data based on a specific database role. And not just table-level access, but row-level access---or however you define access for that role in your database. Effectively, you can use impersonation to set up data sandbox-like access to your data, while letting people use the SQL editor to query that data. The difference is that, _instead of setting up a data sandbox in Metabase, you need to set up that row-level security via the privileges granted to a role in your database._
15260

15361
If instead you want to give a group SQL access to some, but not all, of the schemas or tables in that database, you can create an additional role in your database that only includes a subset of those tables---or even specific row-level access---and then use Metabase's impersonation feature to associate a user attribute with that role. Essentially what Metabase will do is take the user attribute and pass that attribute as a string into a `SET ROLE` or `USE ROLE` command for the database _before_ Metabase executes the query.
15462

155-
Connection impersonation doesn't apply to people in the Metabase Admins group, as their more permissive privileges take precedence.
63+
Connection impersonation doesn't apply to people in the Metabase admins group, as their more permissive privileges take precedence.
64+
65+
For more about how to set this up, check out [Use Impersonation to get row-level permissions with both GUI and SQL queries](/learn/metabase-basics/administration/permissions/impersonation).
15666

15767
## Metabase gives people the most permissive access to data across all of their groups
15868

@@ -163,10 +73,6 @@ So if a person is in two groups with different permissions for the same database
16373

16474
Blue group's more permissive access would override the impersonated access.
16575

166-
## Admins won't see the effects of impersonation
167-
168-
Admins won't ever see the effects of impersonation effects, because their privileges will override those of any other group they're a member of.
169-
170-
Metabase's default Administrators group has "Can view" access to all databases, and Metabase uses the most permissive access for any person in multple groups, so any admin will have "Can view" - not "Impersonated" - access to the database.
76+
## Further reading
17177

172-
To test impersonation, create a test user, assign them a user attribute with the database role, and add them to the impersonated group. Then, log in as the test user and verify the data access.
78+
- [Use Impersonation to get row-level permissions with both GUI and SQL queries](/learn/metabase-basics/administration/permissions/impersonation)

_site/docs/master/databases/connections/mongodb.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4466,7 +4466,7 @@ <h2 id="configuring-ssl-via-the-command-line">Configuring SSL via the command li
44664466

44674467
<h2 id="how-metabase-syncs-data-in-mongodb">How Metabase syncs data in MongoDB</h2>
44684468

4469-
<p>Because MongoDB contains unstructured data, Metabase takes a different approach to syncing your database’s metadata. To get a sense of the schema, Metabase will query the first and last 500 documents (most of the calculation is done in MongoDB). This sampling helps Metabase do things like differentiate datetime fields from string fields, and provide people with pre-populated filters. Metabase also syncs 1,000 leaf fields (fields at the deepest nesting level) per MongoDB collection. The reason Metabase only scans a sample of the documents is because scanning every document in every collection on every sync would put too much strain on your database. And while the sampling does a pretty good job keeping Metabase up to date, it can also mean that new fields can sometimes fall through the cracks, leading to visualization issues, or even fields failing to appear in your results. For more info, check out our <a href="../../troubleshooting-guide/db-connection">troubleshooting guide</a>.</p>
4469+
<p>Because MongoDB contains unstructured data, Metabase takes a different approach to syncing your database’s metadata. To get a sense of the schema, Metabase will query the first and last 500 documents (most of the calculation is done in MongoDB). This sampling helps Metabase do things like differentiate datetime fields from string fields, and provide people with pre-populated filters. The reason Metabase only scans a sample of the documents is because scanning every document in every collection on every sync would put too much strain on your database. And while the sampling does a pretty good job keeping Metabase up to date, it can also mean that new fields can sometimes fall through the cracks, leading to visualization issues, or even fields failing to appear in your results. For more info, check out our <a href="../../troubleshooting-guide/db-connection">troubleshooting guide</a>.</p>
44704470

44714471
<h2 id="general-connectivity-concerns">General connectivity concerns</h2>
44724472

_site/docs/master/developers-guide/driver-changelog.html

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4366,6 +4366,12 @@ <h2 id="metabase-0560">Metabase 0.56.0</h2>
43664366
</li>
43674367
</ul>
43684368

4369+
<h2 id="metabase-0558">Metabase 0.55.8</h2>
4370+
4371+
<ul>
4372+
<li>Add multi-method <code class="language-plaintext highlighter-rouge">driver/do-with-resilient-connection</code> for executing functions in a context where closed connections may be automatically reopened</li>
4373+
</ul>
4374+
43694375
<h2 id="metabase-0550">Metabase 0.55.0</h2>
43704376

43714377
<ul>
Binary file not shown.
Binary file not shown.

0 commit comments

Comments
 (0)