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

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

Токен в заголовке #

curl -X GET 'https://school.example.com/api/v1/courses' \
  -H 'Authorization: Bearer lms_live_a8f3c1e9d2b74a5f8e0c1d3b5a7f9e2c' \
  -H 'Accept: application/json'

Почему в заголовке, а не параметром: параметры попадают в журналы прокси, в историю браузера и в отчёты об ошибках. Заголовок — нет.

Только HTTPS. Обычный HTTP отвечает 400 без перенаправления: перенаправление с POST теряет тело и порождает баги, которые ищут днями.

Боевой и тестовый #

Префикс токена информативен:

Это не украшение. Случайно закоммиченный ключ с таким префиксом опознаётся сканером секретов — и отзывается до того, как им кто-нибудь воспользуется. Ключ вида a8f3c1e9… не опознаётся ничем.

Где взять ключ #

Школа заводит ключи сама, в настройках. Не по заявке нам: коробка стоит на вашем сервере, мы к ней не касаемся, и требовать обращения ради ключа было бы странно. Подробности — Ключи.

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

Действие от лица пользователя #

Отдельный сценарий: интеграция выполняет действие от лица конкретного человека — например, бот отправляет ответ на задание от имени ученика.

X-On-Behalf-Of: usr_01HQZX3M8K4N2P

Работает только с ключом, имеющим право на запись по пользователям, и записывается в журнал аудита как «действие выполнено интеграцией X от имени пользователя Y».

Никакой подмены личности в тени. Это важно не для нас, а для разбора: через месяц вопрос «кто отправил этот ответ» должен иметь ответ, а не догадку.

Одноразовая ссылка входа #

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

Одноразовая. Сработает у того, кто откроет её первым; второй переход получит отказ словами. Обычная ссылка входа живёт 15 минут, ссылка из письма о доступе в школу — 7 дней: такое письмо читают вечером и в выходные.

Ведёт туда, где человеку положено быть. После перехода школа сама решает куда: сотрудника — в админку, ученика — в кабинет. Та же функция, что у обычного входа.

Подтверждает почту — ту, на которую ушла ссылка. Если адрес в анкете за это время сменился, подтверждения нет: письмо читал не хозяин нового адреса.

Не заменяет код защиты. У владельца, администратора и менеджера после перехода форма просит код из приложения, а если он ещё не настроен — настроить. Ссылка, пересланная в чат, без кода в школу не пустит.

Чего в аутентификации нет #

OAuth и авторизации сторонних приложений. Ключ заводит школа и отдаёт тому, кому доверяет. Модель «пользователь разрешает приложению доступ к своим данным» в первой версии не нужна: интеграции пишет сама школа или её подрядчик.

Токена ученика. Дать ученику ключ на чтение своих данных технически возможно и модель прав это позволяет, но такой возможности сейчас нет.