Sharing a connection

Connections can be shared across the organization so that other users can also use and access the data in CARTO. In this guide we will cover the different sharing modes and the recommended use cases for each one.

Sharing a connection

In the "Connections" section in CARTO Workspace, you will notice a three-dot menu in the connections you have created. This menu lets you edit, share or delete your connection. Let's click on "Permissions and sharing".

Sharing modes

Once inside the permissions and sharing menu, we can check the different sharing modes. These options are also available when creating or editing a connection.

  • Private: the connection can only be viewed, used, or edited by you. When you create a connection, it’s always private by default.

  • Shared: other users in your organization can view or use the connection, but only you can edit it. You can further restrict this shared mode using one of the following options

    • Organization: all users in your organization can view or use the connection.

    • Groups: select manually which groups of users can view or use this connection. Learn more about synchronizing user groups.

    • Require viewer credentials: this option is similar to "Organization" but requires all users, regardless of their role, to provide their own credentials before using the connection. This flow to provide credentials will kick off at any point, whether they're trying to open a map or a workflow. This mode is used to leverage policies such as row-level security or collaborate in maps while using personal credentials.

Not all sharing modes are available for all connections. For example, you need to use Single Sign-On and Groups to select the Groups mode, and Require viewer credentials is only available for BigQuery (OAuth) and Databricks connections. On the other hand, BigQuery OAuth connections can't be shared with the entire organization or groups because they're tied to personal credentials.

Require viewer credentials

This option is only available for:

If you need this sharing mode with a different provider or authentication method, please share it as feedback through your CARTO point of contact.

When you set up a connection and share it using the "Require viewer credentials" mode, all the other authenticated users will need to provide their credentials to use the connection. This will be done in a modal like this when they open a table, a map, or a workflow using this connection:

After they provide their own credentials, they will be able to use that connection as usual. Credentials are stored for each user so they won't need to input them every time. If for some reasons the credentials need to be modified or removed, there are options in different parts of the CARTO Workspace and Builder, such as the connection card.

Maps shared in public (everyone on the internet or protected with password) won't require unauthenticated users to provide credentials

Row-level security and other policies

When using "Require viewer credentials" the connection will dynamically enforce each CARTO user to their own credential to query the data warehouse (ie: BigQuery), including cache management. This makes it possible to leverage security policies set in the database, such as row-level security policies.

This will also enforce general role-based permission policies set by the organization, so if a table is used in a map and the user does not have access to that table, the map will not render any data at all.

Our recommended best practice is to set the security policies at the database level, so we'll compile here some interesting readings for the different available providers:

Last updated