> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultas comuns de gerenciamento de acesso

> Este artigo apresenta os conceitos básicos para definir usuários e funções SQL e aplicar esses privilégios e permissões a bancos de dados, tabelas, linhas e colunas.

<Tip>
  **Autogerenciado**

  Se você estiver trabalhando com ClickHouse autogerenciado, consulte [usuários e funções SQL](/docs/pt-BR/concepts/features/security/access-rights).
</Tip>

Este artigo apresenta os conceitos básicos para definir usuários e funções SQL e aplicar esses privilégios e permissões a bancos de dados, tabelas, linhas e colunas.

<div id="admin-user">
  ## Usuário admin
</div>

Os serviços do ClickHouse Cloud têm um usuário admin, `default`, criado quando o serviço é criado. A senha é fornecida na criação do serviço e pode ser redefinida por usuários do ClickHouse Cloud que tenham a função **Admin**.

Quando você adiciona usuários SQL ao seu serviço do ClickHouse Cloud, eles precisarão de um nome de usuário SQL e uma senha. Se quiser que eles tenham privilégios de nível administrativo, atribua aos novos usuários a função `default_role`. Por exemplo, adicionando o usuário `clickhouse_admin`:

```sql theme={null}
CREATE USER IF NOT EXISTS clickhouse_admin
IDENTIFIED WITH sha256_password BY 'P!@ssword42!';
```

```sql theme={null}
GRANT default_role TO clickhouse_admin;
```

<Note>
  Ao usar o SQL Console, suas instruções SQL não serão executadas como o usuário `default`. Em vez disso, elas serão executadas como um usuário chamado `sql-console:${cloud_login_email}`, em que `cloud_login_email` é o e-mail do usuário que está executando a consulta naquele momento.

  Esses usuários do SQL Console gerados automaticamente têm a função `default`.
</Note>

<div id="passwordless-authentication">
  ## Autenticação sem senha
</div>

Há duas funções disponíveis para o Console SQL: `sql_console_admin`, com permissões idênticas às de `default_role`, e `sql_console_read_only`, com permissões somente leitura.

Os usuários Admin recebem a função `sql_console_admin` por padrão, então nada muda para eles. No entanto, a função `sql_console_read_only` permite conceder a usuários não Admin acesso somente leitura ou acesso total a qualquer instância. Um Admin precisa configurar esse acesso. As funções podem ser ajustadas com os comandos `GRANT` ou `REVOKE` para atender melhor aos requisitos específicos de cada instância, e todas as modificações feitas nessas funções serão mantidas.

<div id="granular-access-control">
  ### Controle de acesso granular
</div>

Essa funcionalidade de controle de acesso também pode ser configurada manualmente com granularidade por usuário. Antes de atribuir as novas funções `sql_console_*` aos usuários, devem ser criadas funções de banco de dados específicos por usuário do console SQL que sigam o namespace `sql-console-role:<email>`. Por exemplo:

```sql theme={null}
CREATE ROLE OR REPLACE sql-console-role:<email>;
GRANT <some grants> TO sql-console-role:<email>;
```

Quando uma função correspondente for detectada, ela será atribuída ao usuário em vez das funções padrão. Isso permite configurações de controle de acesso mais complexas, como criar funções como `sql_console_sa_role` e `sql_console_pm_role` e concedê-las a usuários específicos. Por exemplo:

```sql theme={null}
CREATE ROLE OR REPLACE sql_console_sa_role;
GRANT <whatever level of access> TO sql_console_sa_role;
CREATE ROLE OR REPLACE sql_console_pm_role;
GRANT <whatever level of access> TO sql_console_pm_role;
CREATE ROLE OR REPLACE `sql-console-role:christoph@clickhouse.com`;
CREATE ROLE OR REPLACE `sql-console-role:jake@clickhouse.com`;
CREATE ROLE OR REPLACE `sql-console-role:zach@clickhouse.com`;
GRANT sql_console_sa_role to `sql-console-role:christoph@clickhouse.com`;
GRANT sql_console_sa_role to `sql-console-role:jake@clickhouse.com`;
GRANT sql_console_pm_role to `sql-console-role:zach@clickhouse.com`;
```

<div id="test-admin-privileges">
  ## Teste os privilégios de administrador
</div>

Saia da sessão com o usuário `default` e entre novamente como o usuário `clickhouse_admin`.

Todos estes devem funcionar:

```sql theme={null}
SHOW GRANTS FOR clickhouse_admin;
```

```sql theme={null}
CREATE DATABASE db1
```

```sql theme={null}
CREATE TABLE db1.table1 (id UInt64, column1 String) ENGINE = MergeTree() ORDER BY id;
```

```sql theme={null}
INSERT INTO db1.table1 (id, column1) VALUES (1, 'abc');
```

```sql theme={null}
SELECT * FROM db1.table1;
```

```sql theme={null}
DROP TABLE db1.table1;
```

```sql theme={null}
DROP DATABASE db1;
```

<div id="non-admin-users">
  ## Usuários não administradores
</div>

Os usuários devem ter os privilégios necessários, e nem todos devem ser administradores. O restante deste documento apresenta cenários de exemplo e as funções necessárias.

<div id="preparation">
  ### Preparação
</div>

Crie estas tabelas e usuários para uso nos exemplos.

<div id="creating-a-sample-database-table-and-rows">
  #### Criando um banco de dados, uma tabela e linhas de exemplo
</div>

<Steps>
  <Step title="Criar um banco de dados de teste" id="create-a-test-database">
    ```sql theme={null}
    CREATE DATABASE db1;
    ```
  </Step>

  <Step title="Criar uma tabela" id="create-a-table">
    ```sql theme={null}
    CREATE TABLE db1.table1 (
       id UInt64,
       column1 String,
       column2 String
    )
    ENGINE MergeTree
    ORDER BY id;
    ```
  </Step>

  <Step title="Popular a tabela com linhas de exemplo" id="populate">
    ```sql theme={null}
    INSERT INTO db1.table1
       (id, column1, column2)
    VALUES
       (1, 'A', 'abc'),
       (2, 'A', 'def'),
       (3, 'B', 'abc'),
       (4, 'B', 'def');
    ```
  </Step>

  <Step title="Verificar a tabela" id="verify">
    ```sql title="Consulta" theme={null}
    SELECT *
    FROM db1.table1
    ```

    ```response title="Resposta" theme={null}
    Query id: 475015cc-6f51-4b20-bda2-3c9c41404e49

    ┌─id─┬─column1─┬─column2─┐
    │  1 │ A       │ abc     │
    │  2 │ A       │ def     │
    │  3 │ B       │ abc     │
    │  4 │ B       │ def     │
    └────┴─────────┴─────────┘
    ```
  </Step>

  <Step title={<>Criar <code>column_user</code></>} id="create-a-user-with-restricted-access-to-columns">
    Crie um usuário comum que será usado para demonstrar a restrição de acesso a determinadas colunas:

    ```sql theme={null}
    CREATE USER column_user IDENTIFIED BY 'password';
    ```
  </Step>

  <Step title={<>Criar <code>row_user</code></>} id="create-a-user-with-restricted-access-to-rows-with-certain-values">
    Crie um usuário comum que será usado para demonstrar a restrição de acesso a linhas com determinados valores:

    ```sql theme={null}
    CREATE USER row_user IDENTIFIED BY 'password';
    ```
  </Step>
</Steps>

<div id="creating-roles">
  #### Criando funções
</div>

Com este conjunto de exemplos:

* serão criadas funções para diferentes privilégios, como colunas e linhas
* os privilégios serão concedidos às funções
* usuários serão atribuídos a cada função

As funções são usadas para definir grupos de usuários para determinados privilégios, em vez de gerenciar cada usuário separadamente.

<Steps>
  <Step title={<>Crie uma função para restringir os usuários dessa função a ver apenas <code>column1</code> no banco de dados <code>db1</code> e na tabela <code>table1</code>:</>} id="create-column-role">
    ```sql theme={null}
    CREATE ROLE column1_users;
    ```
  </Step>

  <Step title={<>Defina privilégios para permitir a visualização de <code>column1</code></>} id="set-column-privileges">
    ```sql theme={null}
    GRANT SELECT(id, column1) ON db1.table1 TO column1_users;
    ```
  </Step>

  <Step title={<>Adicione o usuário <code>column_user</code> à função <code>column1_users</code></>} id="add-column-user-to-role">
    ```sql theme={null}
    GRANT column1_users TO column_user;
    ```
  </Step>

  <Step title={<>Crie uma função para restringir os usuários dessa função a ver apenas linhas selecionadas; neste caso, apenas linhas que contenham <code>A</code> em <code>column1</code></>} id="create-row-role">
    ```sql theme={null}
    CREATE ROLE A_rows_users;
    ```
  </Step>

  <Step title={<>Adicione <code>row_user</code> à função <code>A_rows_users</code></>} id="add-row-user-to-role">
    ```sql theme={null}
    GRANT A_rows_users TO row_user;
    ```
  </Step>

  <Step title={<>Crie uma política para permitir a visualização apenas das linhas em que <code>column1</code> tenha o valor <code>A</code></>} id="create-row-policy">
    ```sql theme={null}
    CREATE ROW POLICY A_row_filter ON db1.table1 FOR SELECT USING column1 = 'A' TO A_rows_users;
    ```
  </Step>

  <Step title="Defina privilégios para o banco de dados e a tabela" id="set-db-table-privileges">
    ```sql theme={null}
    GRANT SELECT(id, column1, column2) ON db1.table1 TO A_rows_users;
    ```
  </Step>

  <Step title="Conceda permissões explícitas para que outras funções ainda tenham acesso a todas as linhas" id="grant-other-roles-access">
    ```sql theme={null}
    CREATE ROW POLICY allow_other_users_filter 
    ON db1.table1 FOR SELECT USING 1 TO clickhouse_admin, column1_users;
    ```

    <Note>
      Ao associar uma política a uma tabela, o sistema aplicará essa política, e somente os usuários e funções definidos poderão realizar operações na tabela; todos os demais terão qualquer operação negada. Para evitar que a política restritiva de linhas seja aplicada a outros usuários, outra política deve ser definida para permitir que outros usuários e funções tenham acesso normal ou outros tipos de acesso.
    </Note>
  </Step>
</Steps>

<div id="verification">
  ## Verificação
</div>

<div id="testing-role-privileges-with-column-restricted-user">
  ### Testando privilégios da função com usuário com restrição de colunas
</div>

<Steps>
  <Step title={<>Faça login no cliente do ClickHouse usando o usuário <code>clickhouse_admin</code></>} id="login-admin-user">
    ```bash theme={null}
    clickhouse-client --user clickhouse_admin --password password
    ```
  </Step>

  <Step title="Verifique o acesso ao banco de dados, à tabela e a todas as linhas com o usuário admin." id="verify-admin-access">
    ```sql theme={null}
    SELECT *
    FROM db1.table1
    ```

    ```response theme={null}
    Query id: f5e906ea-10c6-45b0-b649-36334902d31d

    ┌─id─┬─column1─┬─column2─┐
    │  1 │ A       │ abc     │
    │  2 │ A       │ def     │
    │  3 │ B       │ abc     │
    │  4 │ B       │ def     │
    └────┴─────────┴─────────┘
    ```
  </Step>

  <Step title={<>Faça login no cliente do ClickHouse usando o usuário <code>column_user</code></>} id="login-column-user">
    ```bash theme={null}
    clickhouse-client --user column_user --password password
    ```
  </Step>

  <Step title={<>Teste o <code>SELECT</code> usando todas as colunas</>} id="test-select-all-columns">
    ```sql theme={null}
    SELECT *
    FROM db1.table1
    ```

    ```response theme={null}
    Query id: 5576f4eb-7450-435c-a2d6-d6b49b7c4a23

    0 rows in set. Elapsed: 0.006 sec.

    Received exception from server (version 22.3.2):
    Code: 497. DB::Exception: Received from localhost:9000. 
    DB::Exception: column_user: Not enough privileges. 
    To execute this query it's necessary to have grant 
    SELECT(id, column1, column2) ON db1.table1. (ACCESS_DENIED)
    ```

    <Note>
      O acesso foi negado porque todas as colunas foram especificadas, e o usuário tem acesso apenas a `id` e `column1`
    </Note>
  </Step>

  <Step title={<>Verifique a consulta <code>SELECT</code> apenas com as colunas especificadas e permitidas:</>} id="verify-allowed-columns">
    ```sql theme={null}
    SELECT
        id,
        column1
    FROM db1.table1
    ```

    ```response theme={null}
    Query id: cef9a083-d5ce-42ff-9678-f08dc60d4bb9

    ┌─id─┬─column1─┐
    │  1 │ A       │
    │  2 │ A       │
    │  3 │ B       │
    │  4 │ B       │
    └────┴─────────┘
    ```
  </Step>
</Steps>

<div id="testing-role-privileges-with-row-restricted-user">
  ### Testando privilégios de função com usuário com restrição por linha
</div>

<Steps>
  <Step title={<>Faça login no cliente do ClickHouse usando <code>row_user</code></>} id="login-row-user">
    ```bash theme={null}
    clickhouse-client --user row_user --password password
    ```
  </Step>

  <Step title="Veja as linhas disponíveis" id="view-available-rows">
    ```sql theme={null}
    SELECT *
    FROM db1.table1
    ```

    ```response theme={null}
    Query id: a79a113c-1eca-4c3f-be6e-d034f9a220fb

    ┌─id─┬─column1─┬─column2─┐
    │  1 │ A       │ abc     │
    │  2 │ A       │ def     │
    └────┴─────────┴─────────┘
    ```

    <Note>
      Verifique se apenas as duas linhas acima são retornadas; as linhas com o valor `B` em `column1` não devem ser incluídas.
    </Note>
  </Step>
</Steps>

<div id="modifying-users-and-roles">
  ## Modificando usuários e funções
</div>

Os usuários podem receber várias funções para combinar os privilégios necessários. Ao usar várias funções, o sistema combinará essas funções para determinar os privilégios; o efeito final é que as permissões das funções serão cumulativas.

Por exemplo, se `role1` permitir apenas SELECT em `column1` e `role2` permitir SELECT em `column1` e `column2`, o usuário terá acesso a ambas as colunas.

<Steps>
  <Step title="Usando a conta de administrador, crie um novo usuário para restringir por linha e coluna com funções padrão" id="create-restricted-user">
    ```sql theme={null}
    CREATE USER row_and_column_user IDENTIFIED BY 'password' DEFAULT ROLE A_rows_users;
    ```
  </Step>

  <Step title={<>Remova os privilégios anteriores da função <code>A_rows_users</code></>} id="remove-prior-privileges">
    ```sql theme={null}
    REVOKE SELECT(id, column1, column2) ON db1.table1 FROM A_rows_users;
    ```
  </Step>

  <Step title={<>Permita que a função <code>A_row_users</code> faça SELECT apenas de <code>column1</code></>} id="allow-column1-select">
    ```sql theme={null}
    GRANT SELECT(id, column1) ON db1.table1 TO A_rows_users;
    ```
  </Step>

  <Step title={<>Faça login no cliente do ClickHouse usando <code>row_and_column_user</code></>} id="login-restricted-user">
    ```bash theme={null}
    clickhouse-client --user row_and_column_user --password password;
    ```
  </Step>

  <Step title="Teste com todas as colunas:" id="test-all-columns-restricted">
    ```sql theme={null}
    SELECT *
    FROM db1.table1
    ```

    ```response theme={null}
    Query id: 8cdf0ff5-e711-4cbe-bd28-3c02e52e8bc4

    0 rows in set. Elapsed: 0.005 sec.

    Received exception from server (version 22.3.2):
    Code: 497. DB::Exception: Received from localhost:9000. 
    DB::Exception: row_and_column_user: Not enough privileges. 
    To execute this query it's necessary to have grant 
    SELECT(id, column1, column2) ON db1.table1. (ACCESS_DENIED)
    ```
  </Step>

  <Step title="Teste com as colunas permitidas:" id="test-limited-columns">
    ```sql theme={null}
    SELECT
        id,
        column1
    FROM db1.table1
    ```

    ```response theme={null}
    Query id: 5e30b490-507a-49e9-9778-8159799a6ed0

    ┌─id─┬─column1─┐
    │  1 │ A       │
    │  2 │ A       │
    └────┴─────────┘
    ```
  </Step>
</Steps>

<div id="troubleshooting">
  ## Solução de problemas
</div>

Em alguns casos, os privilégios podem se sobrepor ou se combinar de forma a produzir resultados inesperados. Os comandos a seguir podem ser usados para ajudar a identificar o problema usando uma conta de administrador

<div id="listing-the-grants-and-roles-for-a-user">
  ### Listar grants e funções de um usuário
</div>

```sql theme={null}
SHOW GRANTS FOR row_and_column_user
```

```response theme={null}
Query id: 6a73a3fe-2659-4aca-95c5-d012c138097b

┌─GRANTS FOR row_and_column_user───────────────────────────┐
│ GRANT A_rows_users, column1_users TO row_and_column_user │
└──────────────────────────────────────────────────────────┘
```

<div id="list-roles-in-clickhouse">
  ### Listar funções no ClickHouse
</div>

```sql theme={null}
SHOW ROLES
```

```response theme={null}
Query id: 1e21440a-18d9-4e75-8f0e-66ec9b36470a

┌─name────────────┐
│ A_rows_users    │
│ column1_users   │
└─────────────────┘
```

<div id="display-the-policies">
  ### Exibir as políticas
</div>

```sql theme={null}
SHOW ROW POLICIES
```

```response theme={null}
Query id: f2c636e9-f955-4d79-8e80-af40ea227ebc

┌─name───────────────────────────────────┐
│ A_row_filter ON db1.table1             │
│ allow_other_users_filter ON db1.table1 │
└────────────────────────────────────────┘
```

<div id="view-how-a-policy-was-defined-and-current-privileges">
  ### Veja como uma política foi definida e quais são os privilégios atuais
</div>

```sql theme={null}
SHOW CREATE ROW POLICY A_row_filter ON db1.table1
```

```response theme={null}
Query id: 0d3b5846-95c7-4e62-9cdd-91d82b14b80b

┌─CREATE ROW POLICY A_row_filter ON db1.table1────────────────────────────────────────────────┐
│ CREATE ROW POLICY A_row_filter ON db1.table1 FOR SELECT USING column1 = 'A' TO A_rows_users │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="example-commands-to-manage-roles-policies-and-users">
  ## Comandos de exemplo para gerenciar funções, políticas e usuários
</div>

Os comandos a seguir podem ser usados para:

* excluir privilégios
* excluir políticas
* desvincular usuários de funções
* excluir usuários e funções
  <br />

<Tip>
  Execute estes comandos como um usuário Admin ou o usuário `default`
</Tip>

<div id="remove-privilege-from-a-role">
  ### Remover um privilégio de uma função
</div>

```sql theme={null}
REVOKE SELECT(column1, id) ON db1.table1 FROM A_rows_users;
```

<div id="delete-a-policy">
  ### Excluir uma política
</div>

```sql theme={null}
DROP ROW POLICY A_row_filter ON db1.table1;
```

<div id="unassign-a-user-from-a-role">
  ### Remover um usuário de uma função
</div>

```sql theme={null}
REVOKE A_rows_users FROM row_user;
```

<div id="delete-a-role">
  ### Excluir uma função
</div>

```sql theme={null}
DROP ROLE A_rows_users;
```

<div id="delete-a-user">
  ### Excluir um usuário
</div>

```sql theme={null}
DROP USER row_user;
```

<div id="summary">
  ## Resumo
</div>

Este artigo apresentou os conceitos básicos para criar usuários e funções SQL e mostrou as etapas para definir e modificar privilégios de usuários e funções. Para informações mais detalhadas sobre cada um, consulte nossos guias do usuário e a documentação de referência.