Ctrl+K
Ctrl+K
PDF
Ctrl+K
PDF

Версии

Настройка аутентификации пользователей через LDAP

Настройка аутентификации пользователей через LDAP#

Данный раздел описывает настройку входа пользователей через внешнее LDAP-хранилище.

За работу LDAP-аутентификации отвечает сервис roox-sso. Параметры находятся в общих файлах настроек, которые могут читать разные сервисы ПУИД.

Примечание

После изменения LDAP-параметров необходимо перезапустить сервис roox-sso, чтобы новые значения были применены.

Общая схема настройки#

Для включения LDAP-аутентификации необходимо выполнить следующие действия:

  1. Включить внешний способ аутентификации через LDAP.

  2. Включить LDAP-репозиторий пользователей.

  3. Указать параметры подключения к LDAP: адрес сервера, базовый DN, сервисную учетную запись и пароль.

  4. Указать атрибут, по которому сервис roox-sso будет искать пользователя в LDAP.

  5. Указать список LDAP-атрибутов, которые нужно получать при входе пользователя.

  6. Настроить сопоставление полученных атрибутов с полями пользователя ПУИД.

  7. При необходимости настроить правила назначения ролей и организаций.

  8. Перезапустить сервис roox-sso.

Минимальный набор включающих параметров:

com.rooxteam.uidm.ldap.externalAuthentication.enabled=true
com.rooxteam.uidm.ldapv3repository.enabled=true

Типовые операции администратора#

Настройка одного LDAP-каталога#

Пример ниже показывает настройку одного LDAP-каталога. В этом случае компонент <alias> в имени ключа можно не указывать.

com.rooxteam.uidm.ldap.externalAuthentication.enabled=true
com.rooxteam.uidm.ldapv3repository.enabled=true

com.rooxteam.uidm.ldap.repository.strategy=walkthrough

com.rooxteam.uidm.ldapv3repository.ldapUrl=ldap://ldap.domain.local:389
com.rooxteam.uidm.ldapv3repository.superuserId=uidm-admin
com.rooxteam.uidm.ldapv3repository.superuserPassword=<password>
com.rooxteam.uidm.ldapv3repository.baseDN=dc=domain,dc=local
com.rooxteam.uidm.ldapv3repository.namingAttribute=uid
com.rooxteam.uidm.ldapv3repository.profileAttributesToFetch=displayName,memberOf,mail,telephoneNumber,mobile,ipaUniqueID,userPrincipalName,street,givenName,sn
com.rooxteam.uidm.ldapv3repository.userSearchFilter=

com.rooxteam.uidm.ldapv3repository.attributes.use_as_login=userPrincipalName
com.rooxteam.uidm.ldapv3repository.attributes.map=login=uid,displayName=displayName,contactEmail=mail,contactPhone=mobile,uid=ipaUniqueID,roles=memberOf,organization_id=street,givenname=givenName,sn=sn

Значение superuserPassword необходимо хранить как секрет и не публиковать в открытых документах, журналах или заявках.

Выбор LDAP-каталога#

Если настроен один LDAP-каталог, компонент <alias> в имени ключа можно опустить. Следует использовать ключи вида:

com.rooxteam.uidm.ldapv3repository.<parameter>

Например:

propepropertiesrties
com.rooxteam.uidm.ldapv3repository.ldapUrl=ldap://ldap.domain.local:389

Если LDAP-каталогов несколько, необходимо настроить отдельный блок параметров для каждого алиаса:

com.rooxteam.uidm.ldapv3repository.<alias>.<parameter>

Например:

com.rooxteam.uidm.ldapv3repository.ldap.domain.local.ldapUrl=ldap://ldap.domain.local:389

Параметр com.rooxteam.uidm.ldap.repository.strategy определяет, как сервис roox-sso выбирает LDAP-каталог при входе пользователя.

Значение

Как работает

Когда использовать

walkthrough

Сервис roox-sso последовательно проверяет настроенные LDAP-каталоги и использует первый, где пользователь найден и успешно прошел проверку пароля

Подходит для большинства установок, особенно если LDAP-каталог один

alias-based

Сервис roox-sso выбирает LDAP-каталог по алиасу из логина пользователя

Следует использовать, если пользователи входят с указанием домена или префикса, и по нему нужно выбрать конкретный LDAP-каталог

Для alias-based логин должен содержать алиас LDAP-каталога. На практике чаще всего используют формат user@domain.local, где domain.local соответствует алиасу LDAP-каталога.

Настройка поиска и проверки пользователя#

При входе пользователя сервис roox-sso выполняет поиск записи в LDAP от имени сервисной учетной записи superuserId.

Поиск выполняется:

  • внутри дерева baseDN;

  • по атрибуту namingAttribute;

  • с учетом дополнительного фильтра userSearchFilter, если он задан.

После нахождения пользователя сервис roox-sso проверяет введенный пароль через LDAP. Если пользователь не найден, найдено несколько записей или пароль не принят LDAP-сервером, вход отклоняется.

Для корректной проверки состояния учетной записи необходимо в profileAttributesToFetch включить атрибуты, требуемые используемому сервису каталога. Например:

Каталог

Рекомендуемые атрибуты

Active Directory

userAccountControl, accountExpires, distinguishedName

FreeIPA

nsAccountLock, krbPrincipalExpiration

Общие пользовательские атрибуты

displayName, mail, mobile, memberOf, uid или другой идентификатор пользователя

Настройка сопоставления LDAP-атрибутов с пользователем ПУИД#

Сопоставление задается параметром:

com.rooxteam.uidm.ldapv3repository.attributes.map=<uidm_attr>=<ldap_attr>,<uidm_attr>=<ldap_attr>

Пример:

com.rooxteam.uidm.ldapv3repository.attributes.map=login=uid,displayName=displayName,contactEmail=mail,contactPhone=mobile,uid=ipaUniqueID,roles=memberOf,organization_id=street,givenname=givenName,sn=sn

В этом примере:

Поле ПУИД

LDAP-атрибут

Назначение

login

uid

Логин пользователя

displayName

displayName

Отображаемое имя пользователя

contactEmail

mail

Адрес электронной почты

contactPhone

mobile

Номер телефона

uid

ipaUniqueID

Уникальный идентификатор пользователя

roles

memberOf

Группы LDAP, из которых формируются роли

organization_id

street

Внешний идентификатор организации, если используется такая модель заполнения

givenname

givenName

Имя пользователя

sn

sn

Фамилия пользователя

Если для поля roles используется LDAP-атрибут memberOf, в роли попадает имя группы из DN группы. Например, из cn=WebSSO-Ops,ou=Groups,dc=domain,dc=local будет использовано имя WebSSO-Ops.

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

com.rooxteam.uidm.ldapv3repository.default_roles=guest
com.rooxteam.uidm.ldapv3repository.default_org_id=my-org-external-id

Настройка атрибута логина#

Параметр com.rooxteam.uidm.ldapv3repository.attributes.use_as_login задает LDAP-атрибут, значение которого используется как логин пользователя в ПУИД.

Пример:

com.rooxteam.uidm.ldapv3repository.attributes.use_as_login=userPrincipalName

Примечание

Необходимо удостовериться, что этот атрибут включен в список profileAttributesToFetch.

Настроить назначение ролей по группам LDAP#

Для прямого сопоставления LDAP-групп с ролями необходимо использовать параметр:

com.rooxteam.uidm.ldapv3repository.groups_to_roles_mapping=<ldap_group>=<uidm_role>,<ldap_group>=<uidm_role>

Пример:

com.rooxteam.uidm.ldapv3repository.groups_to_roles_mapping=rooxgroup1=rooxgroup1,rooxgroup_all=rooxgroup_all,arm_self_services=arm_self_services

Для назначения ролей внутри организаций следует использовать параметры вида:

com.rooxteam.uidm.ldapv3repository.groups_to_org_roles_mapping.<groupName>=<orgName>=<role1>;<role2>

Пример:

com.rooxteam.uidm.ldapv3repository.groups_to_org_roles_mapping.GROUP_EMPLOYEE=b2b=adminAllOperations

Настройка проверки состояния учетной записи#

Сервис roox-sso может проверять состояние учетной записи по LDAP-атрибутам. Для Active Directory доступны настройки флагов userAccountControl:

com.rooxteam.uidm.ldap.externalAuthentication.userAccountControl.attributesOn=NORMAL_ACCOUNT
com.rooxteam.uidm.ldap.externalAuthentication.userAccountControl.attributesOff=ACCOUNTDISABLE,LOCKOUT,PASSWORD_EXPIRED

Параметр

Значение по умолчанию

Пример

Описание

com.rooxteam.uidm.ldap.externalAuthentication.userAccountControl.attributesOn

NORMAL_ACCOUNT

NORMAL_ACCOUNT

Флаги, которые должны быть включены у пользователя

com.rooxteam.uidm.ldap.externalAuthentication.userAccountControl.attributesOff

ACCOUNTDISABLE,LOCKOUT,PASSWORD_EXPIRED

ACCOUNTDISABLE,LOCKOUT,PASSWORD_EXPIRED

Флаги, которые должны быть выключены у пользователя

Если атрибут userAccountControl отсутствует в записи пользователя, проверка флагов Active Directory пропускается.

Настройка пула LDAP-соединений#

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

  1. Определить, для какого LDAP-каталога нужно изменить поведение пула: единственный каталог без алиаса или каталог с конкретным <alias>.

  2. Открыть файл /usr/share/tomcat/ldap.properties.

  3. Изменить параметры пула из подраздела Пул LDAP-соединений.

  4. Для повышения устойчивости после длительного простоя включить проверку простаивающих соединений:

com.rooxteam.uidm.ldapv3repository.pool2.test-while-idle=true
com.rooxteam.uidm.ldapv3repository.pool2.eviction-run-interval-millis=300000

  1. Перезапустить сервис roox-sso.

  2. Проверить вход пользователя из LDAP и отсутствие ошибок подключения к LDAP-серверу в журнале /var/log/roox-sso/roox-sso.log.

Настройка смены пароля пользователя во внешнем LDAP#

Если сценарий смены или сброса пароля пользователя предполагает необходимость изменять пароль во внешнем LDAP-каталоге, необходимо настроить отдельный блок параметров:

com.rooxteam.sso.credentials.external-ldap-change.providedUrl=ldaps://dc.domain.local:636
com.rooxteam.sso.credentials.external-ldap-change.superuserId=CN=svc-sso,DC=domain,DC=local
com.rooxteam.sso.credentials.external-ldap-change.superuserPassword=<password>
com.rooxteam.sso.credentials.external-ldap-change.baseDn=DC=domain,DC=local
com.rooxteam.sso.credentials.external-ldap-change.uidmNamingAttribute=uid
com.rooxteam.sso.credentials.external-ldap-change.namingAttribute=sAMAccountName
com.rooxteam.sso.credentials.external-ldap-change.userSearchFilter=(objectClass=person)
com.rooxteam.sso.credentials.external-ldap-change.passwordAttribute=userPassword
com.rooxteam.sso.credentials.external-ldap-change.isUnicodePasswordAttribute=false
com.rooxteam.sso.credentials.external-ldap-change.ignoreErrors=true
com.rooxteam.sso.credentials.external-ldap-change.additionalProperties=

Для Active Directory обычно требуется использовать атрибут unicodePwd; в этом случае следует задать:

com.rooxteam.sso.credentials.external-ldap-change.passwordAttribute=unicodePwd
com.rooxteam.sso.credentials.external-ldap-change.isUnicodePasswordAttribute=true

Справочник путей к конфигурационным файлам#

Параметры работы с LDAP задаются в общем файле настроек:

Файл настройки на VM

Назначение

Ответственный сервис

Действие после изменения

/usr/share/tomcat/ldap.properties

Настройки LDAP-аутентификации, LDAP-репозитория пользователей, выбора LDAP-каталога, сопоставления атрибутов и проверки состояния учетной записи

roox-sso

Перезапуск roox-sso

В этом же файле обычно размещаются:

  • включение LDAP-аутентификации;

  • параметры подключения к одному или нескольким LDAP-каталогам;

  • правила выбора LDAP-каталога;

  • список LDAP-атрибутов, которые нужно читать;

  • сопоставление LDAP-атрибутов с атрибутами пользователя ПУИД;

  • дополнительные проверки состояния учетной записи;

  • параметры пула LDAP-соединений.

Справочник параметров#

В колонке Значение по умолчанию указано значение, которое используется, если параметр не задан в конфигурации. Значение нет означает, что встроенного значения по умолчанию нет.

Включение LDAP-аутентификации#

Параметр

Значение по умолчанию

Пример

Описание

com.rooxteam.uidm.ldap.externalAuthentication.enabled

false

true

Включает LDAP как внешний способ аутентификации пользователей

com.rooxteam.uidm.ldapv3repository.enabled

false

true

Включает LDAP-репозиторий пользователей

com.rooxteam.uidm.ldap.repository.strategy

walkthrough

walkthrough

Способ выбора LDAP-каталога: walkthrough или alias-based

Подключение к LDAP-каталогу#

Для единственного LDAP-каталога следует использовать ключи без алиаса:

com.rooxteam.uidm.ldapv3repository.<parameter>

Для нескольких LDAP-каталогов требуются ключи с алиасом:

com.rooxteam.uidm.ldapv3repository.<alias>.<parameter>

В таблице ниже показана форма с <alias>. Для одного LDAP-каталога необходимо удалить фрагмент <alias>. из имени ключа.

Параметр

Значение по умолчанию

Пример

Описание

com.rooxteam.uidm.ldapv3repository.<alias>.ldapUrl

нет

ldap://ldap.domain.local:389

URL LDAP-сервера. Для защищенного соединения следует использовать ldaps://...:636

com.rooxteam.uidm.ldapv3repository.<alias>.superuserId

нет

uidm-admin

Сервисная учетная запись для поиска пользователей

com.rooxteam.uidm.ldapv3repository.<alias>.superuserPassword

нет

<password>

Пароль сервисной учетной записи

com.rooxteam.uidm.ldapv3repository.<alias>.baseDN

нет

dc=domain,dc=local

Базовый DN, внутри которого выполняется поиск пользователей

com.rooxteam.uidm.ldapv3repository.<alias>.namingAttribute

нет

uid

LDAP-атрибут, по которому ищется пользователь при входе

com.rooxteam.uidm.ldapv3repository.<alias>.profileAttributesToFetch

пустой список

displayName,memberOf,mail,uid

LDAP-атрибуты, которые сервис roox-sso получает для проверки и заполнения профиля. Служебные атрибуты для проверки состояния пользователя добавляются автоматически

com.rooxteam.uidm.ldapv3repository.<alias>.userSearchFilter

нет

(objectClass=person)

Дополнительный LDAP-фильтр поиска. Может быть пустым

com.rooxteam.uidm.ldapv3repository.<alias>.referral

нет

follow

Режим обработки LDAP referral-ссылок

com.rooxteam.uidm.ldapv3repository.<alias>.connectTimeout

10000

5000

Таймаут подключения к LDAP-серверу в миллисекундах

com.rooxteam.uidm.ldapv3repository.<alias>.readTimeout

10000

5000

Таймаут чтения ответа LDAP-сервера в миллисекундах

com.rooxteam.uidm.ldapv3repository.<alias>.env

нет

java.naming.ldap.attributes.binary=objectGUID

Дополнительные свойства LDAP-подключения в формате key=value,key=value

Пул LDAP-соединений#

Сервис roox-sso использует пул LDAP-соединений для операций поиска пользователя и чтения LDAP-атрибутов от имени сервисной учетной записи superuserId. Проверка пароля пользователя выполняется отдельным LDAP bind-соединением и не берется из этого пула.

Пул создается автоматически при старте roox-sso для каждого настроенного LDAP-каталога. Если LDAP-каталог один и алиас не указан, создается один пул для настроек без алиаса. Если настроено несколько LDAP-каталогов с алиасами, для каждого алиаса создается отдельный пул.

Параметры пула задаются общим префиксом:

com.rooxteam.uidm.ldapv3repository.pool2.

pool2 в этом префиксе — не имя пула и не алиас LDAP-каталога, а фиксированная часть имени параметров пула. Отдельное имя пула в настройках не задается. Принадлежность пула к LDAP-каталогу определяется настройкой самого LDAP-каталога: без алиаса для единственного каталога или по алиасу каталога при множественной настройке.

Для большинства установок достаточно включить test-while-idle и задать eviction-run-interval-millis, если LDAP-сервер или сетевое оборудование закрывает простаивающие соединения. В этом случае сервис roox-sso периодически проверяет простаивающие соединения в пуле и удаляет невалидные соединения.

Параметр

Значение по умолчанию

Пример

Описание

com.rooxteam.uidm.ldapv3repository.pool2.max-total
значение com.rooxteam.uidm.ldapv3repository.pool.maxSize,

если оно задано; иначе -1

32

Максимальное количество соединений в пуле. Значение -1 означает отсутствие ограничения со стороны пула

com.rooxteam.uidm.ldapv3repository.pool2.max-total-per-key

8

8

Максимальное количество соединений для одного типа LDAP-контекста

com.rooxteam.uidm.ldapv3repository.pool2.max-idle-per-key

8

8

Максимальное количество простаивающих соединений, которые пул сохраняет

com.rooxteam.uidm.ldapv3repository.pool2.min-idle-per-key

0

1

Минимальное количество простаивающих соединений, которые пул старается поддерживать

com.rooxteam.uidm.ldapv3repository.pool2.max-wait

значение com.rooxteam.uidm.ldapv3repository.pool.timeout, если оно задано; иначе -1

5000

Время ожидания (в миллисекундах) свободного соединения, если пул исчерпан

com.rooxteam.uidm.ldapv3repository.pool2.block-when-exhausted

true

true

Если true, запрос ждет свободное соединение при исчерпании пула

com.rooxteam.uidm.ldapv3repository.pool2.test-on-create

false

false

Включение проверки соединения при создании

com.rooxteam.uidm.ldapv3repository.pool2.test-on-borrow

false

true

Включение проверки соединения перед выдачей из пула

com.rooxteam.uidm.ldapv3repository.pool2.test-on-return

false

false

Включение проверки соединения при возврате в пул

com.rooxteam.uidm.ldapv3repository.pool2.test-while-idle

false

true
Включение проверки простаивающего соединения во время периодической

проверки

com.rooxteam.uidm.ldapv3repository.pool2.eviction-run-interval-millis

-1

300000

Интервал периодической проверки простаивающих соединений в миллисекундах. Значение -1 отключает периодическую проверку

com.rooxteam.uidm.ldapv3repository.pool2.tests-per-eviction-run

3

3

Количество простаивающих соединений, проверяемых за один запуск проверки

com.rooxteam.uidm.ldapv3repository.pool2.min-evictable-time-millis

1800000

1800000

Время (в миллисекундах), через которое простаивающее соединение может быть удалено из пула

com.rooxteam.uidm.ldapv3repository.pool2.soft-min-evictable-time-millis

-1

-1

Мягкий порог удаления простаивающих соединений в миллисекундах

com.rooxteam.uidm.ldapv3repository.pool2.eviction-policy-class

org.apache.commons.pool2.impl.DefaultEvictionPolicy

org.apache.commons.pool2.impl.DefaultEvictionPolicy

Политика удаления простаивающих соединений из пула

com.rooxteam.uidm.ldapv3repository.pool2.fairness

false

false

Включение справедливого порядка ожидания свободного соединения

com.rooxteam.uidm.ldapv3repository.pool2.validation-query-base

пустая строка

пустая строка

Базовый DN для проверки соединения

com.rooxteam.uidm.ldapv3repository.pool2.validation-query-filter

objectclass=*

objectclass=*

LDAP-фильтр для проверки соединения

Атрибуты и роли#

Параметр

Значение по умолчанию

Пример

Описание

com.rooxteam.uidm.ldapv3repository.attributes.use_as_login

нет

userPrincipalName

LDAP-атрибут, который используется как логин пользователя в ПУИД

com.rooxteam.uidm.ldapv3repository.attributes.map

нет

login=uid,displayName=displayName

Сопоставление полей ПУИД и LDAP-атрибутов

com.rooxteam.uidm.ldapv3repository.default_roles

пустой список

guest

Роли, назначаемые всем пользователям из LDAP

com.rooxteam.uidm.ldapv3repository.default_org_id

нет

my-org-external-id

Организация, назначаемая всем пользователям из LDAP

com.rooxteam.uidm.ldapv3repository.groups_to_roles_mapping

пустой список

ldap_group=uidm_role

Сопоставление групп LDAP с ролями ПУИД

com.rooxteam.uidm.ldapv3repository.groups_to_org_roles_mapping.<groupName>

пустой список

b2b=adminAllOperations

Назначение ролей в рамках организации по LDAP-группе

Смена пароля в LDAP#

Параметр

Значение по умолчанию

Пример

Описание

com.rooxteam.sso.credentials.external-ldap-change.providedUrl

нет

ldaps://dc.domain.local:636

URL LDAP-сервера для операции смены пароля

com.rooxteam.sso.credentials.external-ldap-change.superuserId

нет

CN=svc-sso,DC=domain,DC=local

Сервисная учетная запись с правом изменения пароля

com.rooxteam.sso.credentials.external-ldap-change.superuserPassword

нет

<password>

Пароль сервисной учетной записи

com.rooxteam.sso.credentials.external-ldap-change.baseDn

нет

DC=domain,DC=local

Базовый DN для поиска пользователя при смене пароля

com.rooxteam.sso.credentials.external-ldap-change.uidmNamingAttribute

uid

uid

Атрибут пользователя ПУИД, значение которого используется для поиска в LDAP

com.rooxteam.sso.credentials.external-ldap-change.namingAttribute

sAMAccountName

sAMAccountName

LDAP-атрибут, по которому ищется пользователь при смене пароля

com.rooxteam.sso.credentials.external-ldap-change.userSearchFilter

нет

(objectClass=person)

Дополнительный LDAP-фильтр поиска пользователя

com.rooxteam.sso.credentials.external-ldap-change.passwordAttribute

userPassword

userPassword

LDAP-атрибут пароля. Для Active Directory обычно unicodePwd

com.rooxteam.sso.credentials.external-ldap-change.isUnicodePasswordAttribute

false

false

Включает формат записи пароля для unicodePwd

com.rooxteam.sso.credentials.external-ldap-change.ignoreErrors

true

true

Если true, ошибки LDAP при смене пароля не прерывают основной сценарий

com.rooxteam.sso.credentials.external-ldap-change.additionalProperties

пустой список

java.naming.security.protocol=ssl

Дополнительные свойства LDAP-подключения в формате key=value,key=value

Проверка после изменения#

Для проверки внесенных изменений в файл /usr/share/tomcat/ldap.properties необходимо:

  1. Перезапустить сервис roox-sso.

  2. Выполнить вход от имени тестового пользователя из LDAP.

  3. Удостовериться, что пользователь найден по ожидаемому атрибуту namingAttribute.

  4. Удостовериться, что роли и организация назначены согласно attributes.map, default_roles и настройкам групп.

  5. Если вход отклонен, проверить пароль пользователя, доступность LDAP-сервера, корректность baseDN, namingAttribute, userSearchFilter и права сервисной учетной записи.

Содержание