Методы аутентификации. LDAP-advanced

Метод ldap-advanced auth позволяет выполнять аутентификацию с использованием существующего сервера LDAP и учетных данных user/password. Это позволяет интегрировать StarVault в среду, использующую LDAP, без дублирования конфигурации user/password в нескольких местах. Также позволяет приводить в соответствие параметры учетной записи из LDAP в Entity раздела Custom metadata, что дает возможность идентифицировать пользователя не только по ID.

Сопоставление групп и пользователей в LDAP-advanced с политиками StarVault помощью путей users/ и groups/.

1. Примечание по экранированию

Администратор должен обеспечить правильное преобразование DN. Это включает в себя DN пользователя, bind DN для поиска и т. д.

Единственный способ экранирования DN, выполняемый этим методом, - это имена пользователей, указанные во время входа в систему, когда они вставляются в окончательный DN привязки, и использует правила экранирования, определенные в RFC 4514.

Кроме того, в Active Directory есть правила экранирования, которые немного отличаются от RFC; в частности, требуется экранировать '#' независимо от позиции в DN (RFC требует, чтобы он экранировался только тогда, когда это первый символ), и '=', который, как указывает RFC, может быть экранирован с помощью обратной косой черты '\', но не содержит в своем наборе обязательных экранирующих символов. Если вы используете Active Directory и они отображаются в ваших именах пользователей, пожалуйста, убедитесь, что они экранированы, в дополнение к тому, что они должным образом экранированы в вашем настроенном DNs.

Для справки смотрите RFC 4514 и этот пост TechNet о символах для экранирования в Active Directory.

2. Аутентификация

2.1. Через CLI

$ starvault login -method=ldap-advanced username=mitchellh
Password (will be hidden):
Successfully authenticated! The policies that are associated
with this token are listed below:

admins

2.2. Через API

$ curl \
    --request POST \
    --data '{"password": "foo"}' \
    http://127.0.0.1:8200/v1/auth/ldap-advanced/login/mitchellh

Ответ будет представлен в формате JSON. Например:

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": null,
  "auth": {
    "client_token": "c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
    "policies": [
      "admins"
    ],
    "metadata": {
      "username": "mitchellh"
    },
    "lease_duration": 0,
    "renewable": false
  }
}

3. Конфигурация

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

Включите метод аутентификации LDAP-advanced:
```
$ starvault auth enable ldap-advanced
```
Настройте параметры подключения к серверу LDAP, информацию о том, как аутентифицировать пользователей, и инструкции о том, как запрашивать членство в группах. Параметры конфигурации распределены по категориям и подробно описаны ниже.

3.1. Параметры соединения

url (string, обязательно) - сервер LDAP для подключения.

Пример 1. Примеры:

ldap-advanced://ldap-advanced.myorg.com, ldaps://ldap-advanced.myorg.com:636. Это также может быть список URL через запятую, например, ldap-advanced://ldap-advanced.myorg.com,ldaps://ldap-advanced.myorg.com:636, в этом случае серверы будут опробованы в порядке очереди, если в процессе подключения возникнут ошибки.
starttls (bool, необязательно) - если true, выдает команду StartTLS после установления незашифрованного соединения.
insecure_tls - (bool, необязательно) - если true, пропускает проверку SSL-сертификата LDAP-сервера - небезопасно, используйте с осторожностью!
certificate - (string, необязательно) - сертификат CA для использования при проверке сертификата сервера LDAP, должен быть в кодировке x509 PEM.
client_tls_cert - (string, необязательно) - Сертификат клиента для предоставления серверу LDAP, должен быть закодирован x509 PEM.
client_tls_key - (string, необязательно) - ключ сертификата клиента для предоставления серверу LDAP, должен быть закодирован x509 PEM.
user additional properties - конфигурация для маппинга дополнительных параметров пользователя.
Применить конфигурацию можно двумя способами:
С помощью веб-интерфейса
Перейдите ко вкладке Доступ→ldap-advanced.

Нажмите на вкладку Конфигурация и перейдите к редактированию, нажав на кнопку Конфигурировать.

Добавьте следующую конфигурацию в поле Дополнительные пользовательские параметры:

{ "email": "mail", "family_name": "sn", "given_name": "givenName", "name": "cn", "preferred_username": "uid" }

Ключ JSON объекта выше - значение в alias.custom_metadata.<name>;

Значение - поле из LDAP записи пользователя.

После добавления конфигурации в поле нажмите Сохранить. Применение конфигурации позволит наблюдать в логах дополнительную информацию о пользователе.

Для проверки, что конфигурация применилась успешно, перейдите на вкладку Доступ→Сущности. Выберите нужный псевдоним из списка. Перейдите ко вкладке Дополнительные метаданные.
С помощью CLI
Предварительно создайте файл <Название_конфигурации>.json в текущей директории со следующим содержимым:

{ "useradditionalproperties": {"name": "cn", "given_name": "givenName", "family_name": "sn", "preferred_username": "uid", "email": "mail"} }

Примените данную конфигурацию с помощью команды:

starvault write auth/ldap-advanced/config @<Название_конфигурации>.json

Применение конфигурации позволит наблюдать в логах дополнительную информацию о пользователе.

Параметры сущности включают в себя блок data.aliases.custom-metadata, который содержит параметры пользователя из LDAP-advanced. Для просмотра этих параметров выполните команду:

starvault read -format=json identity/entity/id/<id>

Пример вывода:

{ "request_id": "b564c30f-4a73-f756-3cf3-547e310ff347", "lease_id": "", "lease_duration": 0, "renewable": false, "data": { "aliases": [ { "canonical_id": "57d685b6-120f-984d-5663-79a876b1ce79", "creation_time": "2025-07-15T10:41:47.798054469Z", "custom_metadata": { (1) "family_name": "Administrator", "name": "Administrator", "preferred_username": "admin" }, "id": "1c0dc7fa-06c9-2a29-76b7-6f9d6d28a5fd", "last_update_time": "2025-07-15T10:41:47.798054469Z", "local": false, "merged_from_canonical_ids": null, "metadata": null, "mount_accessor": "auth_ldap-advanced_5d9da975", "mount_path": "auth/ldap-advanced/", "mount_type": "ldap-advanced", "name": "uid=admin,cn=users,cn=accounts,dc=starvault-dev,dc=cp,dc=infra" } ], "creation_time": "2025-07-15T10:41:47.798049999Z", "direct_group_ids": [], "disabled": false, "group_ids": [], "id": "57d685b6-120f-984d-5663-79a876b1ce79", "inherited_group_ids": [], "last_update_time": "2025-07-15T10:41:47.798049999Z", "merged_entity_ids": null, "metadata": null, "name": "entity_dd9cafcd", "namespace_id": "root", "policies": [] }, "warnings": null }

1 data.aliases.custom_metadata (тип данных: object) - параметры из LDAP-записей пользователей

3.2. Параметры привязки

Существует два альтернативных метода разрешения объекта пользователя, используемого для аутентификации конечного пользователя:

Search: при использовании Search привязка может быть анонимной или аутентифицированной.
User Principal Name: метод определения пользователей, поддерживаемый Active Directory.

3.2.1. Привязка - аутентифицированный поиск

3.2.2. Привязка - аутентифицированный поиск

binddn (string, необязательно) - отличительное имя объекта для привязки при выполнении поиска пользователей и групп.

Пример: cn=starvault,ou=Users,dc=example,dc=com
bindpass (string, необязательно) - пароль, используемый вместе с binddn при поиске пользователя.
userdn (string, необязательно) - базовый DN, по которому будет выполняться поиск пользователей.

Пример: ou=Users,dc=example,dc=com
userattr (string, необязательно) - атрибут объекта атрибута пользователя, соответствующий имени пользователя, переданному при аутентификации.

Примеры: sAMAccountName, cn, uid
userfilter (string, необязательно) - шаблон Go, используемый для построения фильтра поиска пользователей LDAP-advanced. Шаблон может обращаться к следующим контекстным переменным: [UserAttr, Username]. По умолчанию используется фильтр ({{.UserAttr}}={{.Username}}) или (userPrincipalName={{.Username}}@UPNDomain), если задан параметр upndomain. Фильтр поиска пользователей можно использовать для ограничения числа пользователей, которые могут попытаться войти в систему.

Например, чтобы ограничить вход для пользователей, которые не являются подрядчиками, можно написать (&(objectClass=user)({{.UserAttr}}={{.Username}})(!(employeeType=Contractor))).

При указании userfilter в фильтре должно присутствовать либо шаблонное значение {{.UserAttr}}, либо буквальное значение, соответствующее userattr, чтобы гарантировать, что поиск возвращает уникальный результат, учитывающий userattr для целей сопоставления псевдонимов сущностей, и избежать возможных коллизий при входе в систему.

3.2.3. Привязка - анонимный поиск

discoverdn (bool, необязательно) - если true, используйте анонимную привязку для обнаружения DN привязки пользователя.
userdn (string, необязательно) - базовый DN, по которому будет выполняться поиск пользователей.

Пример: ou=Users,dc=example,dc=com
userattr (string, необязательно) - атрибут объекта атрибута пользователя, соответствующий имени пользователя, переданному при аутентификации.

Примеры: sAMAccountName, cn, uid
userfilter (string, необязательно) - шаблон Go, используемый для построения фильтра поиска пользователей LDAP-advanced. Шаблон может обращаться к следующим контекстным переменным: [UserAttr, Username]. По умолчанию используется фильтр ({{.UserAttr}}={{.Username}}) или (userPrincipalName={{.Username}}@UPNDomain), если задан параметр upndomain. Фильтр поиска пользователей можно использовать для ограничения числа пользователей, которые могут попытаться войти в систему.

Например, чтобы ограничить вход для пользователей, которые не являются подрядчиками, можно написать (&(objectClass=user)({{.UserAttr}}={{.Username}})(!(employeeType=Contractor))).
deny_null_bind (bool, необязательно) - эта опция предотвращает обход аутентификации пользователями при предоставлении пустого пароля. По умолчанию используется значение true.
anonymous_group_search (bool, необязательно) - использует анонимные привязки при выполнении поиска групп LDAP-advanced. По умолчанию имеет значение false.

3.2.4. Разыменование псевдонимов

dereference_aliases (string, необязательно) - управление тем, как будут разыменовываться псевдонимы при выполнении поиска. Возможные значения: never, finding, searching, и always. При использовании finding` псевдонимы будут разыменовываться только во время разрешения имен базы. при использовании searching` псевдонимы будут разыменовываться после разрешения имен.

3.2.5. Привязка - основное имя пользователя (AD)

upndomain (string, необязательно) - userPrincipalDomain, используемый для построения строки UPN для аутентифицируемого пользователя. Сконструированный UPN будет выглядеть как [username]@UPNDomain.

Пример: example.com, что приведет к привязке StarVault как username@example.com.

3.3. Разрешение членства в группе

После аутентификации пользователя метод LDAP-advanced auth должен знать, как определить, к каким группам принадлежит пользователь. Конфигурация для этого может отличаться в зависимости от вашего сервера LDAP и схемы каталогов. При определении принадлежности к группе используются две основные стратегии: первая - поиск объекта authenticated user и следование атрибуту групп, членом которых он является. Вторая - поиск объектов group, членом которых является аутентифицированный пользователь. Поддерживаются оба метода.

groupfilter (string, необязательно) - шаблон Go, используемый при построении запроса на членство в группе. Шаблон может обращаться к следующим контекстным переменным: [UserDN, Username]. По умолчанию используется (|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}})), который совместим с несколькими распространенными схемами каталогов. Для поддержки разрешения вложенных групп в Active Directory вместо этого используйте следующий запрос: (&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}})).
groupdn (string, обязательно) - база поиска LDAP, используемая для поиска членства в группе. Это может быть корень, содержащий либо группы, либо пользователей.

Пример: ou=Groups,dc=example,dc=com
groupdn (string, обязательно) - база поиска LDAP, используемая для поиска членства в группе. Это может быть корень, содержащий либо группы, либо пользователей.

Пример: ou=Groups,dc=example,dc=com

При использовании аутентифицированного поиска для параметров привязки (см. выше) для поиска группы используется отличительное имя, определенное для binddn. В противном случае для поиска группы используется аутентифицированный пользователь.

Для получения большей информации используйте starvault path-help.

3.4. Другие

username_as_alias (bool, необязательно) - если установлено значение true, это заставляет метод auth использовать имя пользователя, переданное пользователем, в качестве имени псевдонима.
max_page_size (int, необязательно) - если установлено значение больше 0, бэкэнд LDAP будет использовать управление постраничным поиском сервера LDAP для запроса страниц до указанного размера. Это можно использовать, чтобы избежать столкновения с ограничением максимального размера результатов сервера LDAP. В противном случае бэкэнд LDAP не будет использовать управление постраничным поиском.

4. Примеры

4.1. Сценарий 1

Сервер LDAP, работает на ldap.example.com, порт 389.
Сервер поддерживает команду STARTTLS для запуска шифрования на стандартном порту.
Сертификат CA хранится в файле с именем ldap_ca_cert.pem
Сервер Active Directory поддерживает атрибут userPrincipalName. Пользователи идентифицируются как username@example.com.
Группы являются вложенными, мы будем использовать LDAP_MATCHING_RULE_IN_CHAIN для просмотра списка.
Поиск группы начнется в разделе ou=Groups,dc=example,dc=com. Для всех объектов группы, расположенных по этому пути, атрибут member будет проверен на соответствие аутентифицированному пользователю.
Имена групп идентифицируются с помощью их атрибута cn.

$ starvault write auth/ldap-advanced/config \
    url="ldap-advanced://ldap-advanced.example.com" \
    userdn="ou=Users,dc=example,dc=com" \
    groupdn="ou=Groups,dc=example,dc=com" \
    groupfilter="(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))" \
    groupattr="cn" \
    upndomain="example.com" \
    certificate=@ldap_meta_ca_cert.pem \
    insecure_tls=false \
    starttls=true
...

4.2. Сценарий 2

Сервер LDAP, работает на ldap.example.com, порт 389.
Сервер поддерживает команду STARTTLS для запуска шифрования на стандартном порту.
Сертификат CA хранится в файле с именем ldap_ca_cert.pem
Сервер не разрешает анонимные привязки для выполнения поиска пользователей.
Для поиска используется учетная запись привязки cn=starvault,ou=users,dc=example,dc=com с паролем My$ecrt3tP4ss.
Объекты пользователя находятся в разделе ou=Users,dc=example,dc=com.
Имя пользователя, передаваемое в хранилище при аутентификации, сопоставляется с атрибутом sAMAccountName.
Принадлежность к группе будет определяться с помощью атрибута memberOf объектов user. Поиск начнется в разделе ou=Users,dc=example,dc=com.

$ starvault write auth/ldap-advanced/config \
    url="ldap://ldap.example.com" \
    userattr=sAMAccountName \
    userdn="ou=Users,dc=example,dc=com" \
    groupdn="ou=Users,dc=example,dc=com" \
    groupfilter="(&(objectClass=person)(uid={{.Username}}))" \
    groupattr="memberOf" \
    binddn="cn=starvault,ou=users,dc=example,dc=com" \
    bindpass='My$ecrt3tP4ss' \
    certificate=@ldap_ca_cert.pem \
    insecure_tls=false \
    starttls=true
...

4.3. Сценарий 3

Сервер LDAP работает на ldap.example.com, порт 636 (LDAPS)
Сертификат CA хранится в файле с именем ldap_ca_cert.pem
Пользовательские объекты находятся в разделе ou=Users,dc=example,dc=com.
Имя пользователя, передаваемое в хранилище при аутентификации, сопоставляется с атрибутом uid.
Имя пользователя для привязки будет автоматически определено с помощью анонимной привязки.
Принадлежность к группе будет определяться с помощью любого из атрибутов memberUid, member member или uniqueMember. Этот поиск начнется в разделе ou=Groups,dc=example,dc=com.
Названия групп определяются с помощью атрибута cn.

$ starvault write auth/ldap-advanced/config \
    url="ldaps://ldap.example.com" \
    userattr="uid" \
    userdn="ou=Users,dc=example,dc=com" \
    discoverdn=true \
    groupdn="ou=Groups,dc=example,dc=com" \
    certificate=@ldap_ca_cert.pem \
    insecure_tls=false \
    starttls=true
...

5. Группа LDAP-advanced → разработка политики

Далее мы хотим создать сопоставление группы LDAP-advanced с политикой StarVault:

$ starvault write auth/ldap-advanced/groups/scientists policies=foo,bar

Это сопоставляет LDAP-группу "scientists" с политиками StarVault "foo" и "bar". Мы также можем добавить определенных пользователей LDAP-advanced в дополнительные (потенциально не-LDAP) группы. Обратите внимание, что политики могут быть указаны и для пользователей LDAP.

$ starvault write auth/ldap-advanced/groups/engineers policies=foobar
$ starvault write auth/ldap-advanced/users/tesla groups=engineers policies=zoobar

Это добавляет пользователя LDAP "tesla" в группу "engineers", которая сопоставлена с политикой "foobar" StarVault. Сам пользователь "tesla" связан с политикой "zoobar".

Наконец, мы можем проверить это, пройдя аутентификацию:

$ starvault login -method=ldap-advanced username=tesla
Password (will be hidden):
Successfully authenticated! The policies that are associated
with this token are listed below:

default, foobar, zoobar

6. Примечание по сопоставлению политик

Следует отметить, что сопоставление пользователь → политика происходит во время создания токена. И изменения в членстве группы на LDAP-сервере не повлияют на токены, которые уже были предоставлены. Чтобы увидеть эти изменения, необходимо отозвать старые токены и попросить пользователя пройти повторную аутентификацию.

7. Блокировка пользователя

Если пользователь несколько раз подряд предоставит неверные учетные данные, StarVault на некоторое время прекратит попытки проверить его учетные данные, а вместо этого сразу же выдаст ошибку об отказе в разрешении. Мы называем такое поведение "блокировкой пользователя". Время, на которое пользователь будет заблокирован, называется "длительностью блокировки". Пользователь сможет войти в систему после истечения срока блокировки. Количество неудачных попыток входа, после которых пользователь будет заблокирован, называется "порог блокировки". Счетчик порога блокировки обнуляется через несколько минут без попыток входа или при успешной попытке входа. Время, в течение которого счетчик будет обнулен после отсутствия попыток входа, называется "сброс счетчика блокировки". Это позволяет предотвратить как автоматические, так и целевые запросы, то есть атаки на угадывание пароля пользователем, а также автоматические атаки.

Функция блокировки пользователя включена по умолчанию. Значения по умолчанию для "порога блокировки" - 5 попыток, "продолжительности блокировки" - 15 минут, "сброса счетчика блокировки" - 15 минут.

Функцию блокировки пользователя можно отключить следующим образом:

его можно отключить глобально с помощью переменной окружения VAULT_DISABLE_USER_LOCKOUT.
его можно отключить для всех поддерживаемых методов аутентификации (ldap-advanced, userpass и approle) или для определенного поддерживаемого метода аутентификации с помощью параметра disable_lockout в строке user_lockout в конфигурационном файле. Более подробная информация приведена в разделе Конфигурация блокировки пользователей.
его можно отключить для конкретного монтирования с помощью команды "auth tune". Более подробную информацию можно найти в команде auth tune или auth tune api.

Эта функция поддерживается только методами userpass, ldap-advanced и approle auth.

8. API

Метод LDAP-advanced auth имеет полноценный HTTP API. Более подробная информация приведена в разделе API метода LDAP-advanced auth.