Перейти к содержимому
M
Все статьи
Разработка 8 мин чтения

Auth-плагин Moodle: свой способ входа для внешней системы

Как написать auth-плагин Moodle: класс auth_plugin_base, методы user_login и loginpage_hook, вход из внешней системы без второго пароля и ошибки безопасности.

Как написать auth-плагин Moodle: класс auth_plugin_base, методы user_login и loginpage_hook, вход из внешней системы без второго пароля и ошибки безопасности.

Задача из жизни: у колледжа есть сайт с личным кабинетом абитуриента или студента, и нужно, чтобы человек нажимал кнопку «Перейти к обучению» и попадал в 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

Что проверить перед выкладкой

  1. Администратор с обычным паролем по-прежнему входит. Не отключайте ручной вход для аварийного доступа, иначе при сбое внешней системы вы потеряете и админку.
  2. Токен нельзя использовать дважды и после истечения срока.
  3. Выход из Moodle не оставляет живой сессии во внешней системе, если так задумано.
  4. Плагин подключён в списке «Управление аутентификацией» и включён только там, где нужно.
  5. Провайдер конфиденциальности описывает, что вы храните о пользователе.

Выход из системы и обновление профиля

Вход — половина работы. Если человек вышел из кабинета на сайте, а в Moodle остался с живой сессией, это неприятно на общем компьютере в аудитории. Для этого есть logoutpage_hook и postlogout_hook: в первом можно закрыть сессию во внешней системе, во втором перенаправить на страницу сайта. Решите заранее, чего вы хотите: единого выхода или выхода только из Moodle. Единый выход требует, чтобы внешняя система тоже умела принимать запрос о закрытии сессии, и это отдельная работа на её стороне.

Профиль обновляют в user_authenticated_hook или через get_userinfo. Решите, какие поля внешняя система считает основными. Если ФИО пришло из кабинета, а пользователь поменял его в Moodle, то при следующем входе его правка затрется. Это нормально, но об этом нужно предупредить сотрудников: иначе поток обращений «у меня сбрасывается фамилия» обеспечен. Чтобы управлять этим, у плагинов аутентификации есть настройка блокировки полей профиля: заблокированное поле пользователь в Moodle изменить не может.

Случай из практики: вход из кабинета слушателя

В учебном центре ДПО слушатель попадал в Moodle из собственного кабинета, и вход приходилось связывать с учётной записью, созданной задолго до этого. Наибольшей проблемой оказались не токены, а дубли: один человек занесён дважды, с разными адресами почты. Если бы плагин создавал пользователя при каждом незнакомом идентификаторе, дублей стало бы больше. Поэтому для найденных по ключу записей вход шёл сразу, а при неоднозначности пользователь видел сообщение с просьбой обратиться к администратору, а сам случай попадал в журнал. Лишняя минута работы администратора обходится дешевле, чем объединение двух профилей с историей оценок.

Если вам нужно сначала навести порядок в списках, посмотрите, как я загружаю пользователей из учётной системы колледжа: массовая загрузка пользователей. Чистые данные упрощают любой вход.

Журнал и разбор жалоб

Когда вход не сработал, пользователь пишет «не пускает» и больше ничего. Чтобы разобрать такой случай, плагин должен записывать причину отказа: токен не найден, токен просрочен, внешняя система не ответила, найдено несколько учётных записей. Секреты и сами токены в журнал не попадают, достаточно идентификатора пользователя и кода причины. Тогда обращение занимает минуты: смотрите код и понимаете, ломается ли дело на стороне Moodle, внешнего кабинета или в данных человека. Без такого журнала приходится воспроизводить ошибку под чужой учётной записью, а это и долго, и неэтично.

Если у вас уже есть личный кабинет на сайте и вы хотите соединить его с СДО, опишите, откуда приходит пользователь и какой у него идентификатор. По этим двум фактам видно, хватит ли штатного плагина. Напишите мне через доработку Moodle, а про готовые варианты читайте в статье про вход через Госуслуги.

Нужна помощь с Moodle?

Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.