Общая информация

Модуль служит для аутентификации в системе через OIDC или взаимодействия с агентом Basis, может использоваться как:

• модуль auth:
  • аутентификация пользователя по токену со сверкой его валидности в OIDC Issuer
  • аутентификация пользователя по крипто-токену Базис
• модуль account (создание пользователя, в системе необходимо наличие утилиты /usr/sbin/useradd)
• модуль session

Установка

Для деривативов debian (Астра / Убунта)

mkdir -p /usr/lib/security
mv pam_lppro.so /usr/lib/security

Для деривативов Enterpise Linux (РедОС)

mkdir -p /usr/lib64/security
mv pam_lppro.so /usr/lib64/security

Настройка

Для использования, необходимо прописать модуль в цепочке соответствующего сервиса (например для использования с протоколом Loudplay - это файл /etc/pam.d/loudplay), например:

auth     required    pam_lppro.so <opt1> <opt2>=<some> <opt3>
account  required    pam_lppro.so
session  required    pam_lppro.so

Где opt - различные параметры настройки модуля, здесь возможные опции:

• flow=<type> - вид аутентификации, type может быть jwt (по-умолчанию) или basis (использование крипто-токена Базис WP)
• check-login - (только для режима jwt) нужно ли сверять логин переданный PAM с логином в jwt-токене (по-умолчанию выключено)
• login-claim=<name> - (только для режима jwt) name является названием поля для сверки логина (по-умолчанию preferred_username)
• insecure - (только для режима jwt) отключить проверку TLS-сертификатов при обращениях при взаимодействии с внешними системами (по-умолчанию выключено, то есть проверка сертификата осуществляется используя системные сертификаты)
• alwayssuccess - опция для тестирования, при включении модуль всегда будет возвращать успех аутентификации (другие агрументы будут проверены, но логика обработки токена не будет вызвана)
• agent-addr - (только для режима basis) адрес для подключения к агенту по tcp (по-умолчанию localhost:10061)
• socket - (только для режима basis) путь к файлу unix socket-а для подключения к агенту по сокету

Примечание: при использовании типа аутентификации flow=basis модуль устанавливает в переменную PAM_AUTHTOK полученный расшифрованный пароль для использования другими модулями PAM в цепочке аутентификации.

Тестовая утилита аутентификации JWT

Служит для проверки модуля и выполнения аутентификации через него с запросом JWT у OIDC Issuer-а. Для использования требуется создать файл сервис /etc/pam.d/lppro-test-jwt со следующим содержанием:

auth     required    pam_lppro.so insecure
account  required    pam_lppro.so
session  required    pam_lppro.so

После чего вызвать тестовую утилиту указав актуальные значения параметров, например:

./pam-test-jwt -issuer-url http://192.168.0.31:8080 -client-id='workplace' -client-secret 'OjCY72E4TipxsFf7kKDuu397SCEVE2ut' -mode keycloak -login test1 -password change

Поведение утилиты при запуске с параметрами выше:

1. Запрос у сервиса OIDC (issuer-а) JWT-токена от имени клиента client-id с секретом client-secret для пользователя test1 с паролем change
2. Выполнение аутентификации (pam conversation) через модуль pam_lppro.so передав модулю в качестве имени пользователя PAM_USER значение test1 и в качестве токена PAM_AUTHTOK токена JWT (полученного в п1)
3. В случае успеха будет выведено сообщение authenticating…authenticated successfully

Тестовая утилита аутентификации Базис

Служит для проверки модуля и выполнения аутентификации через него с валидацией крипто-токена у агента Basis WP. Быстрое smoke-тестирование можно выполнить при помощи предоставленой утилиты mock-agent, запускающей эмуляцию API агента Базис WP. Для использования требуется создать файл сервис /etc/pam.d/lppro-test-basis со следующим содержанием:

auth     required    pam_lppro.so flow=basis
account  required    pam_lppro.so
session  required    pam_lppro.so

Перед выполнением проверки необходимо, чтобы на тестовой рабочей станции был запущен агент Базис WP либо утилита mock-agent.

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

./pam-test-basis -login user1 -password top-secret

Примечание: - при отсутствии параметров командной строки в качестве имени пользователя используется root, а пароля changeit - mock-agent осуществляет эмуляцию API, возвращая успешный ответ и пароль, в случае, если крипто-токен содержит пароль являющийся реверсом от логина (то есть toor от root) - при запуске mock-agent по-умолчанию сервер поднимается на адресе localhost:10064, используя ключ -s будет прослушиваться сокет по пути /var/run/mock-agent.sock

Поведение утилиты при запуске с параметрами выше:

1. Создание крипто-токена из пароля top-secret по описанной структуре данных, используя алгоритм шифрования AES-256-GCM и HKDF-генерацию ключа шифрования с временной меткой
2. Выполнение аутентификации (pam conversation) через модуль pam_lppro.so передав модулю в качестве имени пользователя PAM_USER значение user1 и в качестве токена PAM_AUTHTOK крипто-токена Базис (полученного в п1)
3. В случае успеха будет выведено сообщение authenticating…authenticated successfully

Примеры настроек

Варианты опций в /etc/pam.d/

Базовый

Настройки по-умолчанию: проверка сертификатов включена, сверка логина переданного в PAM и логина в токене отключена.

auth     required    pam_lppro.so

Отключение проверки TLS

Выключить проверку сертификатов при обращении к внешним системам.

auth     required    pam_lppro.so     insecure

Включить сверку логина 1

Проверка совпадения переданного в PAM логина и логина в токене (по умолчанию используется поле preferred_username), отключение проверки TLS.

auth     required    pam_lppro.so     insecure check-login

Включить сверку логина 2

Проверка совпадения переданного в PAM логина и логина в токене, в токене как поле логина используется email.

auth     required    pam_lppro.so     check-login login-claim=email

Для проверки утилитой pam-test-jwt вызывать с указанием параметра scope.

./pam-test-jwt -issuer-url https://oidc.am.loudplay.local -client-id='my-client' -client-secret 'yX0hdqek0a' -login='amalashin@loudplay.local' -password='top-secret' -insecure -scopes=openid,profile,email

Интеграция с Базис WP (TCP)

Использование модуля pam_lppro с последующей передачей полученного токена аутентификации (пароля) из крипто-токена через агент Базис WP, работающий по TCP.

auth      required   pam_lppro.so flow=basis
auth      required   pam_sss.so
account   required   pam_sss.so
password  required   pam_sss.so
session   required   pam_env.so readenv=1 user_readenv=0
session   required   pam_oddjob_mkhomedir.so skel=/etc/skel umask=0077
session   required   pam_sss.so

С такой конфигурацией поведение цепочки аутентификации следующее:

1. Клиентский сервис запрашивает аутентификацию
2. Модуль pam_lppro взаимодействует с агентом Базис WP для получения пароля из крипто-токена
3. Модуль pam_lppro устанавливает переменные PAM_USER и PAM_AUTHTOK
4. Следующие в цепочке модули (в данном случае, pam_sss) выполняют аутентификацию (например, через Kerberos) используя переданные логин и токен (пароль) пользователя

Интеграция с Базис WP (Socket)

Использование модуля pam_lppro с последующей передачей полученного токена аутентификации (пароля) из крипто-токена через агент Базис WP, работающий по unix socket.

auth      required   pam_lppro.so flow=basis socket=/run/wp.agent.sock
auth      required   pam_sss.so
account   required   pam_sss.so
password  required   pam_sss.so
session   required   pam_env.so readenv=1 user_readenv=0
session   required   pam_oddjob_mkhomedir.so skel=/etc/skel umask=0077
session   required   pam_sss.so

С такой конфигурацией поведение цепочки аутентификации следующее:

1. Клиентский сервис запрашивает аутентификацию
2. Модуль pam_lppro взаимодействует с агентом Базис WP для получения пароля из крипто-токена
3. Модуль pam_lppro устанавливает переменные PAM_USER и PAM_AUTHTOK
4. Следующие в цепочке модули (в данном случае, pam_sss) выполняют аутентификацию (например, через Kerberos) используя переданные логин и токен (пароль) пользователя