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

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

!!! 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 и прочие.

LDAPS (Lightweight Directory Access Protocol Secure) — это защищенная
версия протокола LDAP, использующая SSL/TLS для шифрования трафика между
клиентом и сервером каталогов. Это обеспечивает конфиденциальность и
безопасность данных при доступе к службам каталогам.

Для использования LDAPS при аутентификации в Picodata применяется TLS
(Transport Layer Security) — протокол, обеспечивающий безопасную
передачу данных в сети, шифруя информацию между клиентом и
сервером. TLS включается с помощью переменной `TT_LDAP_ENABLE_TLS` (см.
[ниже](#cluster_setup)) на стороне Picodata и работает при условии, что
на LDAP-сервере настроено использование StartTLS. После выполнения
[настроек](#cluster_setup) зашифрованное подключение будет работать
автоматически если на стороне LDAP-сервера находится доверенный ключ,
подписанный корневым сертификатом (CA), которому доверяет клиент.

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

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

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

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

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

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

[Argus]: ../plugins/argus.md

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

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

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

### Настройка инстанса для аутентификации LDAP/LDAPS {: #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`).
* `TT_LDAP_ENABLE_TLS` — параметр, включающий использование TLS (через
StartTLS); возможные значения: `true`, `false`. По умолчанию, TLS выключено.
Перед включением параметра необходимо убедиться, что LDAP-сервер
сконфигурирован использовать StartTLS.

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

???+ example "i1.yml"
    ```yaml
    cluster:
      name: my_cluster
      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'
        advertise: '127.0.0.1:4327'
    ```

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

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

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

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

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

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

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

```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/LDAPS немедленно отразятся на возможности аутентифицировать
пользователей. Для решения этой проблемы администраторам предлагается
временно изменить метод аутентификации (например, на `'md5'`) для
затронутых пользователей при помощи функции смены пароля:

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