> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Guia para configurar a autenticação LDAP no ClickHouse
# LDAP
Esta página não se aplica ao [ClickHouse Cloud](https://clickhouse.com/cloud). O recurso documentado aqui não está disponível nos serviços do ClickHouse Cloud.
Consulte o guia [Compatibilidade com Cloud](/pt-BR/products/cloud/guides/cloud-compatibility) do ClickHouse para mais informações.
O servidor LDAP pode ser usado para autenticar usuários do ClickHouse. Há duas abordagens diferentes para isso:
* Usar o LDAP como autenticador externo para usuários existentes, definidos em `users.xml` ou nos caminhos locais de controle de acesso.
* Usar o LDAP como diretório externo de usuários e permitir a autenticação de usuários não definidos localmente, caso eles existam no servidor LDAP.
Em ambas as abordagens, um servidor LDAP nomeado internamente deve ser definido na configuração do ClickHouse para que outras partes da configuração possam fazer referência a ele.
## Definição do servidor LDAP
Para definir o servidor LDAP, adicione a seção `ldap_servers` ao `config.xml`.
**Exemplo**
```xml theme={null}
localhost
636
uid={user_name},ou=users,dc=example,dc=com
300
false
yes
tls1.2
demand
/path/to/tls_cert_file
/path/to/tls_key_file
/path/to/tls_ca_cert_file
/path/to/tls_ca_cert_dir
ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:AES256-GCM-SHA384
localhost
389
EXAMPLE\{user_name}
CN=Users,DC=example,DC=com
(&(objectClass=user)(sAMAccountName={user_name}))
no
```
Observe que é possível definir vários servidores LDAP na seção `ldap_servers` usando nomes distintos.
**Parâmetros**
| Parâmetro | Padrão | Descrição |
| ------------------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `host` | — | Hostname ou IP do servidor LDAP. Este parâmetro é obrigatório e não pode ficar vazio. |
| `port` | `636` / `389` | Porta do servidor LDAP. O padrão é `636` se `enable_tls` estiver definido como `yes`; caso contrário, `389`. |
| `bind_dn` | — | Modelo usado para construir o DN para bind. O DN resultante será construído substituindo todas as substrings `{user_name}` do modelo pelo nome de usuário real durante cada tentativa de autenticação. |
| `auth_dn_prefix` | — | **Obsoleto.** Uma alternativa a `bind_dn`. Não pode ser usado junto com `bind_dn`. Quando especificado, o bind DN é construído como `auth_dn_prefix + {user_name} + auth_dn_suffix`. Por exemplo, definir `auth_dn_prefix` como `uid=` e `auth_dn_suffix` como `,ou=users,dc=example,dc=com` equivale a definir `bind_dn` como `uid={user_name},ou=users,dc=example,dc=com`. |
| `auth_dn_suffix` | — | **Obsoleto.** Consulte `auth_dn_prefix`. |
| `verification_cooldown` | `0` | Um período de tempo, em segundos, após uma tentativa de bind bem-sucedida, durante o qual o usuário será considerado autenticado com sucesso em todas as solicitações subsequentes sem contatar o servidor LDAP. Especifique `0` para desativar o cache e forçar o contato com o servidor LDAP em cada solicitação de autenticação. |
| `follow_referrals` | `false` | Uma flag para permitir que a biblioteca cliente LDAP siga automaticamente os referrals LDAP retornados pelo servidor. Isso é mais relevante em ambientes Microsoft Active Directory, nos quais pesquisas em subárvore em um base DN de nível alto (por exemplo, `DC=example,DC=com`) podem retornar referrals/referências de pesquisa (por exemplo, `DC=DomainDnsZones,...`). Defina como `true` somente quando você precisar explicitamente de pesquisas entre partições. |
| `enable_tls` | `yes` | Uma flag para acionar o uso de conexão segura com o servidor LDAP. Especifique `no` para o protocolo `ldap://` em texto simples (não recomendado), `yes` para LDAP sobre SSL/TLS com o protocolo `ldaps://` (recomendado) ou `starttls` para o protocolo StartTLS legado (protocolo `ldap://` em texto simples, atualizado para TLS). |
| `tls_minimum_protocol_version` | `tls1.2` | A versão mínima do protocolo SSL/TLS. Valores aceitos: `ssl2`, `ssl3`, `tls1.0`, `tls1.1`, `tls1.2`. |
| `tls_require_cert` | `demand` | Comportamento da verificação do certificado do peer SSL/TLS. Valores aceitos: `never`, `allow`, `try`, `demand`. |
| `tls_cert_file` | — | Caminho para o arquivo de certificado. |
| `tls_key_file` | — | Caminho para o arquivo de chave do certificado. |
| `tls_ca_cert_file` | — | Caminho para o arquivo de certificado da CA. |
| `tls_ca_cert_dir` | — | Caminho para o diretório que contém os certificados da CA. |
| `tls_cipher_suite` | — | Conjunto de cifras permitido (na notação OpenSSL). |
| `search_limit` | `256` | Número máximo de entradas que podem ser retornadas por consultas de pesquisa LDAP executadas por esta definição de servidor (para detecção de DN de usuário e mapeamento de função). |
**Subparâmetros de `user_dn_detection`**
Seção com parâmetros de pesquisa LDAP para detectar o DN real do usuário autenticado via bind. Isso é usado principalmente em filtros de pesquisa para mapeamento adicional de função quando o servidor é Active Directory. O DN de usuário resultante será usado ao substituir substrings `{user_dn}` onde elas forem permitidas. Por padrão, o DN de usuário é definido como igual ao bind DN, mas, assim que a pesquisa for executada, ele será atualizado com o valor real do DN de usuário detectado.
| Parâmetro | Padrão | Descrição |
| --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `base_dn` | — | Modelo usado para construir o base DN para a pesquisa LDAP. O DN resultante será construído substituindo todas as substrings `{user_name}` e `{bind_dn}` do modelo pelo nome de usuário real e pelo bind DN durante a pesquisa LDAP. |
| `scope` | `subtree` | Escopo da pesquisa LDAP. Valores aceitos: `base`, `one_level`, `children`, `subtree`. |
| `search_filter` | — | Modelo usado para construir o filtro de pesquisa da pesquisa LDAP. O filtro resultante será construído substituindo todas as substrings `{user_name}`, `{bind_dn}` e `{base_dn}` do modelo pelo nome de usuário real, bind DN e base DN durante a pesquisa LDAP. Observe que caracteres especiais devem ser escapados corretamente em XML. |
## Autenticador LDAP externo
Um servidor LDAP remoto pode ser usado como método para verificar senhas de usuários definidos localmente (usuários definidos em `users.xml` ou em caminhos locais de controle de acesso). Para isso, especifique o nome de um servidor LDAP previamente definido em vez de `password` ou seções semelhantes na definição do usuário.
A cada tentativa de login, o ClickHouse tenta fazer "bind" no DN especificado pelo parâmetro `bind_dn` na [definição do servidor LDAP](#ldap-server-definition) usando as credenciais fornecidas e, se a operação for bem-sucedida, o usuário será considerado autenticado. Isso costuma ser chamado de método de "simple bind".
**Exemplo**
```xml theme={null}
my_ldap_server
```
Observe que o usuário `my_user` está associado a `my_ldap_server`. Esse servidor LDAP deve ser configurado no arquivo principal `config.xml`, conforme descrito anteriormente.
Quando o [Controle de acesso e gerenciamento de contas](/pt-BR/concepts/features/security/access-rights#access-control-usage) baseado em SQL está habilitado, usuários autenticados por servidores LDAP também podem ser criados usando a instrução [CREATE USER](/pt-BR/reference/statements/create/user).
```sql title="Query" theme={null}
CREATE USER my_user IDENTIFIED WITH ldap SERVER 'my_ldap_server';
```
## Diretório externo de usuários LDAP
Além dos usuários definidos localmente, um servidor LDAP remoto pode ser usado como fonte de definições de usuários. Para isso, especifique o nome de um servidor LDAP previamente definido (consulte [Definição do servidor LDAP](#ldap-server-definition)) na seção `ldap`, dentro da seção `users_directories` do arquivo `config.xml`.
A cada tentativa de login, o ClickHouse tenta localizar a definição do usuário localmente e autenticá-lo como de costume. Se o usuário não estiver definido, o ClickHouse assumirá que a definição existe no diretório LDAP externo e tentará fazer "bind" no DN especificado no servidor LDAP usando as credenciais fornecidas. Se isso for bem-sucedido, o usuário será considerado existente e autenticado. O usuário receberá as funções da lista especificada na seção `roles`. Além disso, uma operação LDAP de "search" pode ser executada, e os resultados podem ser transformados e tratados como nomes de funções, sendo então atribuídos ao usuário se a seção `role_mapping` também estiver configurada. Tudo isso implica que o [Controle de acesso e gerenciamento de contas](/pt-BR/concepts/features/security/access-rights#access-control-usage) baseado em SQL esteja habilitado e que as funções sejam criadas usando a instrução [CREATE ROLE](/pt-BR/reference/statements/create/role).
**Exemplo**
Adicionar ao `config.xml`.
```xml theme={null}
my_ldap_server
ou=groups,dc=example,dc=com
subtree
(&(objectClass=groupOfNames)(member={bind_dn}))
cn
clickhouse_
my_ad_server
CN=Users,DC=example,DC=com
CN
subtree
(&(objectClass=group)(member={user_dn}))
clickhouse_
```
Observe que `my_ldap_server`, referenciado na seção `ldap` dentro da seção `user_directories`, deve ser um servidor LDAP previamente definido e configurado no `config.xml` (consulte [Definição do servidor LDAP](#ldap-server-definition)).
**Parâmetros**
| Parameter | Default | Description |
| --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server` | — | Um dos nomes de servidor LDAP definidos na seção de configuração `ldap_servers` acima. Esse parâmetro é obrigatório e não pode estar vazio. |
| `roles` | — | Seção com uma lista de funções definidos localmente que serão atribuídos a cada usuário recuperado do servidor LDAP. Se nenhuma função for especificada aqui nem atribuída durante o mapeamento de função (abaixo), o usuário não poderá executar nenhuma ação após a autenticação. |
**Subparâmetros de `role_mapping`**
Seção com parâmetros de busca LDAP e regras de mapeamento. Quando um usuário se autentica, com a vinculação ao LDAP ainda ativa, é executada uma busca LDAP usando `search_filter` e o nome do usuário autenticado. Para cada entrada encontrada durante essa busca, o valor do atributo especificado é extraído. Para cada valor de atributo que tenha o prefixo especificado, o prefixo é removido, e o restante do valor passa a ser o nome de uma função local definida no ClickHouse, que deve ter sido criado previamente pela instrução [CREATE ROLE](/pt-BR/reference/statements/create/role). Pode haver várias seções `role_mapping` definidas dentro da mesma seção `ldap`. Todas elas serão aplicadas.
| Parâmetro | Padrão | Descrição |
| --------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `base_dn` | — | Modelo usado para construir a base DN da pesquisa LDAP. O DN resultante será construído substituindo todas as substrings `{user_name}`, `{bind_dn}` e `{user_dn}` do modelo pelo nome de usuário real, bind DN e DN de usuário durante cada pesquisa LDAP. |
| `scope` | `subtree` | Escopo da pesquisa LDAP. Valores aceitos: `base`, `one_level`, `children`, `subtree`. |
| `search_filter` | — | Modelo usado para construir o filtro de pesquisa da pesquisa LDAP. O filtro resultante será construído substituindo todas as substrings `{user_name}`, `{bind_dn}`, `{user_dn}` e `{base_dn}` do modelo pelo nome de usuário real, bind DN, DN de usuário e base DN durante cada pesquisa LDAP. Observe que os caracteres especiais devem ser escapados corretamente em XML. |
| `attribute` | `cn` | Nome do atributo cujos valores serão retornados pela pesquisa LDAP. |
| `prefix` | vazio | Prefixo esperado no início de cada string na lista original de strings retornadas pela pesquisa LDAP. O prefixo será removido das strings originais, e as strings resultantes serão tratadas como nomes de funções locais. |