# Аутентификация с помощью LDAP

В данном разделе приведены сведения об аутентификации в Picodata с
помощью протокола LDAP.

!!! tip "Picodata Enterprise"
    Данная функция доступна только в коммерческой версии Picodata.

## Общие сведения {: #intro }

[Lightweight Directory Access
Protocol](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol)
(далее LDAP) — это легковесный протокол для доступа к службе каталогов
[X.500](https://en.wikipedia.org/wiki/X.500), которая
часто используется организациями для контроля доступа к ресурсам и
управления доменными учетными записями. Существует множество серверов,
которые поддерживают данный протокол: OpenLDAP, GLAuth и прочие.

Типичный сеанс связи с LDAP-сервером выглядит примерно так: клиент
подключается к серверу, отправляет запрос, дожидается ответа сервера и
закрывает соединение. На основании ответа сервера клиент может принять
решение об аутентификации пользователя, инициировавшего подключение.

В качестве запроса в Picodata используется `BIND`, позволяющий
произвести аутентификацию пользователя с использованием заранее
известного Distinguished Name (DN) и факторов аутентификации (например,
пароля).

<!-- Запрос `SEARCH` позволит узнавать неизвестные данные, такие как `DN`.
Есть и другие типы запросов, которые позволяют осуществлять
администрирование учетных записей, то есть создание, редактирование,
удаление и т.д. -->

Для использования протокола LDAP в Picodata следует задать для
учетной записи пользователя тип аутентификации `ldap`. Примеры см.
[ниже](#user_setup).

## Особенности работы LDAP {: #ldap_concepts }

* Коммуникация с LDAP-сервером происходит один раз при установке новой
  пользовательской сессии. Если аутентификация пройдена успешно, сессия
  будет установлена, и до самого ее конца повторная аутентификация
  производиться не будет.
* **Метод отвечает только за аутентификацию.** Группы, права и владение
  объектами и т.д. не синхронизируются с удаленным сервером LDAP.
* Метод требует дополнительной настройки кластера через переменные окружения
  UNIX.
* Метод невозможно использовать в случае отказа удаленного сервера LDAP.
* Метод не кеширует результаты аутентификации.

## Настройка {: #setup }

Для использования LDAP-аутентификации под определенным пользователем в
Picodata требуется:

- наличие в сети запущенного LDAP-сервера, на котором заведен этот
  пользователь
- объявление переменных окружения с данными LDAP-сервера [при запуске узлов
  кластера Picodata](#cluster_setup)
- наличие [пользователя](#user_setup) с таким же именем и типом
  аутентификации `ldap` в Picodata

### Настройка инстанса для LDAP-аутентификации {: #cluster_setup }

Для корректной работы метода нужно установить следующие переменные окружения
UNIX:

* `TT_LDAP_URL` — URL, указывающий на удаленный сервер LDAP, например:
  `ldap://127.0.0.1:1389`.
* `TT_LDAP_DN_FMT` — произвольная формат-строка DN для запроса `BIND`.
  Пример: `cn=$USER,ou=users,dc=example,dc=org`. Вместо `$USER` будет
  подставлено фактическое имя пользователя Picodata (производится только
  для первого упоминания `$USER`).

Пример [конфигурационного файла] инстанса `i1`:

???+ example "i1.yml"
    ```yaml
    cluster:
      name: my_cluster
      shredding: False

      tier:
        default:

    instance:
      instance_dir: './i1'
      name: 'i1'
      tier: 'default'
      peer: [ 127.0.0.1:3301 ]

      iproto_listen: '0.0.0.0:3301'
      iproto_advertise: '127.0.0.1:3301'
      http_listen: '0.0.0.0:8081'
      pg:
        listen: '0.0.0.0:4327'
    ```

[конфигурационного файла]: ../reference/config.md#config_file_description

Определение переменных окружения для использования LDAP-сервера
производится отдельно в окне терминала:

```shell
export TT_LDAP_URL="ldap://127.0.0.1:1389"
export TT_LDAP_DN_FMT='cn=$USER,ou=users,dc=example,dc=org'
```

!!! note "Примечание"
    Обратите внимание, что для корректной обработки
    переменной $USER необходимо указывать значение `TT_LDAP_DN_FMT` в
    одинарных кавычках.

В текущей реализации строка форматирования DN общая для всех
пользователей. Кроме того, нет возможности установить персональный DN
для конкретного пользователя. В качестве параметра можно использовать
только имена пользователей.

Переменные окружения не кешируются — их можно менять во время эксплуатации
кластера; в этом случае для новых попыток аутентификации будут
использоваться актуальные значения параметров.

Запуск кластера, состоящего из одного инстанса `i1`, с авторизацией в LDAP:

```shell
picodata run --config i1.yml
```

### Настройка пользователей LDAP в Picodata {: #user_setup }

Как и другие методы аутентификации, `ldap` можно указать при [создании
нового пользователя][create_user] через параметр `USING`:

```sql
CREATE USER "username" USING ldap;
```

Помимо этого, можно сменить метод аутентификации уже существующего
пользователя:

```sql
ALTER USER "username" USING ldap;
```

Обратите внимание, что при использовании метода LDAP **не требуется**
указывать пароль пользователя. Это связано с тем, что Picodata не хранит
пароли: при каждой попытке аутентификации клиент будет отправлять пароль
отдельно; в свою очередь, Picodata будет использовать полученный пароль
при взаимодействии с сервером LDAP. Также, рекомендуется [включить SSL]
для передачи пароля по сети в зашифрованном виде.

[включить SSL]: ssl.md
[create_user]: access_control.md#create_user

См. также:

- [Управление доступом](access_control.md)

### Устранение неполадок {: #troubleshooting }

В отличие от других методов аутентификации, LDAP требует дополнительной
настройки, без которой аутентификация с использованием этого метода
будет невозможна. Также важно понимать, что любые проблемы с удаленным
LDAP-сервером немедленно отразятся на возможности аутентифицировать
пользователей. Для решения этой проблемы администраторам предлагается
временно изменить метод аутентификации (например, на `'md5'`) для
затронутых пользователей при помощи функции смены пароля:

```sql
ALTER USER "username" WITH PASSWORD 'new_password' USING md5;
```
