Задача из жизни: у колледжа есть сайт с личным кабинетом абитуриента или студента, и нужно, чтобы человек нажимал кнопку «Перейти к обучению» и попадал в Moodle уже авторизованным, без второго пароля. Штатные способы входа это не всегда умеют. Тогда пишется auth-плагин. Это один из самых коротких типов плагинов по объёму кода и один из самых опасных по цене ошибки: через него входят в систему. Общую картину по единому входу я описывала на странице про SSO в Moodle, здесь только разработка.
Когда свой плагин не нужен
Сначала проверьте, нельзя ли обойтись готовым. Штатный плагин OAuth 2 работает с провайдерами, которые используют стандартный протокол, и принимает настроенные сервисы. Для входа через корпоративный каталог есть LDAP, а для сценариев SAML есть отдельные сторонние плагины. Свой плагин оправдан в трёх случаях:
- внешняя система использует собственный протокол или собственный формат токена;
- нужна особая логика сопоставления: по номеру студенческого, по документу, по договору;
- вход должен происходить автоматически из кабинета на вашем сайте, а не со страницы входа Moodle.
Каркас плагина
Плагин лежит в auth/имя, класс называется auth_plugin_имя и наследует auth_plugin_base из lib/authlib.php. В конструкторе задают тип входа и загружают настройки.
defined('MOODLE_INTERNAL') || die();
require_once($CFG->libdir . '/authlib.php');
class auth_plugin_portal extends auth_plugin_base {
public function __construct() {
$this->authtype = 'portal';
$this->config = get_config('auth_portal');
}
public function user_login($username, $password) {
return false; // вход по паролю не используется
}
public function is_internal() {
return false;
}
public function can_change_password() {
return false;
}
}
Здесь пароль в Moodle не проверяется вообще: метод user_login всегда отказывает, а настоящий вход происходит другим путём. Если же вы хотите проверять логин и пароль во внешней системе, user_login становится главным методом: он получает имя и пароль и возвращает истину, если внешний сервер подтвердил вход.
Методы, которые обычно переопределяют
| Метод | Когда вызывается | Зачем переопределять |
|---|---|---|
user_login($username, $password) | Вход через форму логина | Проверка пароля во внешней системе |
is_internal() | При решении, хранит ли Moodle пароль | Ложь для внешней проверки |
can_change_password(), can_reset_password() | Показ ссылок смены и сброса пароля | Отключить, если пароль живёт снаружи |
change_password_url() | Куда вести пользователя для смены пароля | Адрес страницы во внешней системе |
loginpage_hook() | При открытии страницы входа | Принять токен или перенаправить на внешнюю систему |
pre_loginpage_hook() | Раньше, чем отрисована страница входа | Автоматический вход без страницы |
user_authenticated_hook() | После успешного входа | Дополнить профиль, записать в журнал |
logoutpage_hook() и postlogout_hook() | Выход | Закрыть сессию во внешней системе |
get_userinfo($username) | Обновление данных профиля | Вернуть поля пользователя из внешней системы |
config_form(), process_config() | Страница настроек плагина | Адрес сервиса, ключ, правила сопоставления |
Состав методов и их сигнатуры проверяйте по описанию auth_plugin_base для вашей версии Moodle на moodledev.io: часть методов добавлялась позже, а часть хуков изменила поведение.
Вход по токену из внешней системы
Схема, которую я считаю разумной, состоит из трёх шагов. Кабинет на сайте при нажатии кнопки создаёт одноразовый токен и сохраняет его вместе с идентификатором пользователя и временем. Пользователь попадает на страницу Moodle с этим токеном. Плагин в loginpage_hook видит параметр, спрашивает внешний сервис, действителен ли токен, находит или создаёт учётную запись и завершает вход.
public function loginpage_hook() {
$token = optional_param('portaltoken', '', PARAM_ALPHANUMEXT);
if ($token === '') {
return;
}
$external = $this->check_token($token); // запрос к вашему сервису
if (!$external) {
throw new moodle_exception('invalidtoken', 'auth_portal');
}
$user = $this->find_or_create_user($external);
complete_user_login($user);
redirect(new moodle_url('/my/'));
}
Функция complete_user_login принимает объект пользователя, поднимает сессию и посылает событие входа. Её вызывают после того, как вы сами убедились, что человек тот, за кого себя выдаёт. Сам токен не принимайте через PARAM_RAW и не пишите в журнал.
Сопоставление пользователей
Самая трудная часть не в коде входа, а в вопросе «кто это». Адрес почты менять можно, ФИО тоже, у однофамильцев совпадают и имена. Поэтому ключом должен быть неизменяемый идентификатор из внешней системы. Я храню его в поле idnumber или в дополнительном поле профиля и ищу пользователя по нему. Правила такие.
- Нашли по ключу: обновляем профиль данными из внешней системы, если это разрешено настройками.
- Не нашли, но есть учётная запись с тем же адресом почты и другим способом входа: останавливаемся и показываем сообщение. Автоматически переключать нельзя, это путь к захвату чужого профиля.
- Не нашли совсем: создаём пользователя с нужным способом входа и случайным паролем, который не используется.
Создание пользователя делают штатной функцией ядра, а не прямой вставкой в таблицу. Тогда срабатывают события, и другие плагины, например зачётная книжка, узнают о новом человеке.
Ошибки безопасности
| Ошибка | Чем грозит | Как исправить |
|---|---|---|
| Токен многоразовый или живёт сутками | Перехваченный адрес даёт вход | Одноразовый токен со сроком в минуты, проверка на сервере |
| Токен остался в адресной строке | Попадает в журналы и историю | Редирект сразу после обмена |
| Слияние по адресу почты | Захват чужой учётной записи | Ключ из внешней системы, отказ при конфликте |
| Нет проверки подписи ответа внешнего сервиса | Подделка ответа | Подпись или обращение к сервису по защищённому каналу с проверкой сертификата |
| Сведения о входе не пишутся в журнал | Невозможно разобрать инцидент | События ядра плюс собственный журнал отказов без секретов |
| Параметр перенаправления принимается как есть | Открытое перенаправление на чужой сайт | Разрешать только адреса своего Moodle |
Что проверить перед выкладкой
- Администратор с обычным паролем по-прежнему входит. Не отключайте ручной вход для аварийного доступа, иначе при сбое внешней системы вы потеряете и админку.
- Токен нельзя использовать дважды и после истечения срока.
- Выход из Moodle не оставляет живой сессии во внешней системе, если так задумано.
- Плагин подключён в списке «Управление аутентификацией» и включён только там, где нужно.
- Провайдер конфиденциальности описывает, что вы храните о пользователе.
Выход из системы и обновление профиля
Вход — половина работы. Если человек вышел из кабинета на сайте, а в Moodle остался с живой сессией, это неприятно на общем компьютере в аудитории. Для этого есть logoutpage_hook и postlogout_hook: в первом можно закрыть сессию во внешней системе, во втором перенаправить на страницу сайта. Решите заранее, чего вы хотите: единого выхода или выхода только из Moodle. Единый выход требует, чтобы внешняя система тоже умела принимать запрос о закрытии сессии, и это отдельная работа на её стороне.
Профиль обновляют в user_authenticated_hook или через get_userinfo. Решите, какие поля внешняя система считает основными. Если ФИО пришло из кабинета, а пользователь поменял его в Moodle, то при следующем входе его правка затрется. Это нормально, но об этом нужно предупредить сотрудников: иначе поток обращений «у меня сбрасывается фамилия» обеспечен. Чтобы управлять этим, у плагинов аутентификации есть настройка блокировки полей профиля: заблокированное поле пользователь в Moodle изменить не может.
Случай из практики: вход из кабинета слушателя
В учебном центре ДПО слушатель попадал в Moodle из собственного кабинета, и вход приходилось связывать с учётной записью, созданной задолго до этого. Наибольшей проблемой оказались не токены, а дубли: один человек занесён дважды, с разными адресами почты. Если бы плагин создавал пользователя при каждом незнакомом идентификаторе, дублей стало бы больше. Поэтому для найденных по ключу записей вход шёл сразу, а при неоднозначности пользователь видел сообщение с просьбой обратиться к администратору, а сам случай попадал в журнал. Лишняя минута работы администратора обходится дешевле, чем объединение двух профилей с историей оценок.
Если вам нужно сначала навести порядок в списках, посмотрите, как я загружаю пользователей из учётной системы колледжа: массовая загрузка пользователей. Чистые данные упрощают любой вход.
Журнал и разбор жалоб
Когда вход не сработал, пользователь пишет «не пускает» и больше ничего. Чтобы разобрать такой случай, плагин должен записывать причину отказа: токен не найден, токен просрочен, внешняя система не ответила, найдено несколько учётных записей. Секреты и сами токены в журнал не попадают, достаточно идентификатора пользователя и кода причины. Тогда обращение занимает минуты: смотрите код и понимаете, ломается ли дело на стороне Moodle, внешнего кабинета или в данных человека. Без такого журнала приходится воспроизводить ошибку под чужой учётной записью, а это и долго, и неэтично.
Если у вас уже есть личный кабинет на сайте и вы хотите соединить его с СДО, опишите, откуда приходит пользователь и какой у него идентификатор. По этим двум фактам видно, хватит ли штатного плагина. Напишите мне через доработку Moodle, а про готовые варианты читайте в статье про вход через Госуслуги.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.