auth-api

API сервиса аутентификации и авторизации в приложение Твой ФФ!

Схема работы Auth APUI

Функционал

1. Аутентификация и авторизация пользователей
2. Управление доступами к ресурсам Твой ФФ
3. Отправка пользовательских данных в Userdata API

Запуск

1. Перейдите в папку проекта

2. Создайте виртуальное окружение командой и активируйте его:

foo@bar:~$ python3 -m venv venv
foo@bar:~$ source ./venv/bin/activate  # На MacOS и Linux
foo@bar:~$ venv\Scripts\activate  # На Windows

3. Установите библиотеки

foo@bar:~$ pip install -r requirements.txt

• Бэкенд может запуститься без кластера Kafka. Просто не указывайте KAFKA_DSN в .env. Если вам нужна его логика, то тут находится инструкция по поднятию: https://github.com/profcomff/db-kafka

4. Запускайте приложение!

foo@bar:~$ python -m auth_backend start

---

ENV-file description

• DB_DSN – Адрес базы данных в фаормате postgresql://admin:admin@localhost:5432/dev
• EMAIL – Адрес электронной почты (логин для входа) для отправки уведомлений по Email
• EMAIL_PASS – Пароль от электронной почты
• HOST – Хост для использования в шаблонах сообщений электронной почты
• KAFKA_DSN - Адрес Kafka Cluster
• KAFKA_USER_LOGIN_TOPIC_NAME - имя топика, куда Auth API пишет пользовательские данные при успешной авторизации
• KAFKA_TIMEOUT - время, в течение которого kafka worker ждет пока новое сообщение отправится(не используется)
• KAFKA_LOGIN - Логин в брокер сообщений Kafka
• KAFKA_PASSWORD - Пароль в брокер сообщений Kafka
• ENABLED_AUTH_METHODS - включенные методы авторизации
• TOKEN_LENGTH - длина отдаваемого токена при авторизации
• SESSION_TIME_IN_DAYS - время, через которое протухнет токен
• MAX_RETRIES - максимальное кол-во ретраев при отправке письма
• STOP_MAX_DELAY - максимальная задержка между попытками отправить письмо
• WAIT_MIN, WAIT_MAX - минимальное и максимальное время ожидания успешной отправки письма
• EMAIL_DELAY_TIME_IN_MINUTES - окно учёта писем
• EMAIL_DELAY_COUNT - сколько писем можно отправить максимум в промежутке времени EMAIL_DELAY_TIME_IN_MINUTES

Остальные параметры указаны тут

Google

• GOOGLE_REDIRECT_URL: str – URL адрес страницы для получения данных авторизации на нашем фронтэнде
• GOOGLE_SCOPES: list[str] – Запрашиваемые у гугла права на управление аккаунтом, по умолчанию запрашивает данные пользователя
• GOOGLE_CREDENTIALS: Json – Данные приложения Google, получить можно в Google Cloud Console

Physics

• PHYSICS_REDIRECT_URL: str – см. секцию Google
• PHYSICS_SCOPES: list[str] – см. секцию Google
• PHYSICS_CREDENTIALS: Json – см. секцию Google

LK MSU

• LKMSU_REDIRECT_URL – URL адрес страницы для получения данных авторизации на нашем фронтэнде

Yandex

• YANDEX_REDIRECT_URL – URL адрес страницы для получения данных авторизации на нашем фронтэнде
• YANDEX_CLIENT_ID - ID приложения, созданного в Яндексе
• YANDEX_CLIENT_SECRET - Ключ для получения токена пользователя в Яндексе

MYMSU

• MYMSU_REDIRECT_URL – см. секцию Yandex
• MYMSU_CLIENT_ID - см. секцию Yandex
• MYMSU_CLIENT_SECRET - см. секцию Yandex

Telegram

• TELEGRAM_REDIRECT_URL – URL адрес страницы для получения данных авторизации на нашем фронтэнде
• TELEGRAM_BOT_TOKEN - Токен бота приложения

---

Основные абстракции

1. Пользователь - запись в таблице user, может иметь много методов входа, например, VK, email, LKMSU
2. Скоуп - право на определенное действие над определенным ресурсом. Например timetable.event.update - право на изменение расписания в Timetable API
3. Группа - запись в таблице Group. Может иметь родителя, в итоге группы образуют дерево(деревья). Группа имеет свои скоупы. Группы также косвенно имеет все скоупы своего родителя, которая в свою очередь имеет скоупы своего родителя и т.д.
4. Сессия - сущность опредляющая доступ к аккаунту. Имеет токен, свои скоупы. Пользователь авторизуется и тем самым создает сессию. В нее можно поместить те права, которые есть у пользователя. Сессия заканчивается через какое то время и доступ становится невозможен, надо создать новую сессию.

Сценарий использования

Email: регистрация нового аккаунта

1. Дернуть ручку POST /email/registrate . Вы передаете

{
 "email": "string", // Почта
 "password": "string" // Пароль
}

3. На почту приходит письмо с линком на GET /email/approve?token='...', если по ней перейти то почта будет подтверждена и регистрацию можно считать завершенной.

Email: вход в аккаунт

1. Дернуть ручку POST /email/login. там всего один вариант логина, никуда не денетесь
2. В теле запроса есть scopes, это обязательный параметр. scopes - это лист айдишников, существующих в группах в которых вы состоите прямо или в группах, которые являются родителями ваших групп. Он может быть равен [], если вам не нужны права для этого токена.
3. Вам придет токен, сохраняйте его куда нибудь, срок действия ограничен.

Email: Восстановление забытого пароля

1. Дернуть ручку POST /email/reset/password/restore. Вы передаете

{"email": "string" // Почта}

3. Вам придет письмо, где будет ссылка НА ФРОНТ(надо сделать это), в ссылке будет reset_token
4. Токен надо передать в ручку POST /email/reset/password в заголовках, вместе с

{"new_password": ""}

и пароль будет изменен

Email: Изменение пароля

1. Если пароль не забыт, а просто надо его поменять. Тогда в POST /email/reset/password/request передается токен авторизации, в теле вы передаете

{
"password": "string", // старый пароль
"new_password": "string" // новый пароль
}

3. Отправляете запрос и всё, пароль изменен, вам придет письмо с уведомлением о смене пароляю

Email: Изменение адреса электронной почты

1. Дернуть ручку POST /email/reset/email/request. Всего один вариант, передаете новое мыло в теле

{"email": "string" //Почта}

и токен атворизации в заголовках 2. На почту придет письмо с подтверждением почты, там будет токен подтверждения в query параметрах. Ссылка ведет на ручку GET пока что, но надо переделать, чтобы тоже вела на фронт.

Google/Physics: вход пользователя с аккаунтом Google

Все примеры написаны для Google аккаунта, для аккаунта physics.msu.ru средует делать запросы к /physics-msu вместо /google

1. Получаем адрес для запроса на сервер Google: GET /google/auth_url
2. Редиректим пользователя на этот url, пользователь входит в аккаунт и возвращается на страницу, которую можно узнать запросом GET /google/redirect_url
3. Если Google не передал в ответе GET параметр error, передаем GET параметры страницы на сервер авториации в теле POST запроса в формате JSON: POST /google/login. Иначе возвращаем ошибку авторизации
4. При успешном входе получаем token сессии. В теле запроса есть scopes, это обязательный параметр. scopes - это лист айдишников, существующих в группах в которых вы состоите прямо или в группах, которые являются родителями ваших групп. Он может быть равен [], если вам не нужны права для этого токена. Если сервер авторизации ответил ошибкой 401:
   1. запоминаем значение id_token из ответа.
   2. Предлагаем пользователю завести новый аккаунт нашего приложения, связанный с гуглом
5. Если пользователь соглашается, делаем запрос с {"id_token": "<id-token>"} в теле на адрес POST /google/register. При успешном входе получаем token сессии, иначе показываем экран ошибки авторизации. В теле запроса есть scopes, это обязательный параметр. scopes - это лист айдишников, существующих в группах в которых вы состоите прямо или в группах, которые являются родителями ваших групп. Он может быть равен [], если вам не нужны права для этого токена.

Google/Physics: добавление аккаунта Google как второго метода входа

Все примеры написаны для Google аккаунта, для аккаунта physics.msu.ru средует делать запросы к /physics-msu вместо /google

1. Получаем адрес для запроса на сервер Google: GET /google/auth_url
2. Редиректим пользователя на этот url, пользователь входит в аккаунт и возвращается на страницу, которую можно узнать запросом GET /google/redirect_url
3. Если Google не передал в ответе GET параметр error, передаем данные на сервер авториации: POST /google/register, указываем заголовок Authorization: <auth-token>. Иначе возвращаем ошибку авторизации
4. При успешном входе получаем token сессии, иначе показываем экран ошибки авторизации

Telegram: добавление аккаунта Telegram как второго метода входа

1. Получаем адрес обычным способом, перенаправляем туда пользователя
2. После выдачи доступа пользователь попадает на redirect url с параметром #tgAuthResult=...
   1. На этой странице должен быть встроен виджет авторизации телеграмма, который преобразует #tgAuthResult=... в ?first_name=...&user_name=...
3. Отослать данные из GET параметров в виде словаря на ручку GET /telegram/login
4. При успешном входе получаем token сессии, иначе показываем экран ошибки авторизации

Созданиие группы

1. Дернуть ручку POST /group, передать

{
"name": "string", // имя группы
"parent_id": "string", // айди предка группы(из него подтянутся скоупы)
"scopes": "string" // скуопы группы
}

Итоговые права участников группы будут равны сумме прав участников рожительской группы и прав текущей группы

Создание скоупсов

0. У вас должен быть аккаунт с правом на создание скоупсов :)
1. Получаете токен со скоупом auth.scope.create
2. Идете с токеном на ручку POST /scope, отправляете его туда в заголовке и в теле отправляете

{
"name": "string", // имя скоупа(там должно быть две точки и три слова без пробелов)
"comment": "string" // комментарий
}

4. Профит

Добавление скоупсов в группу

1. Дернуть PATCH /group/{id}, передать

{"scopes": ["<scopes>"] // список, содержащий старые скоупы + новые. Ручка полностью заменит скоупы на переданные}

Узнать информацию о себе

1. Дернуть ручку GET /me, передать в заголовках токен авторизации Ответ содержит поля

• auth_methods - список доступных методов авторизации пользователя
• session_scopes - скоупы текущей сессии
• user_scopes - список доступных пользователю скоупов
• indirect_groups - список групп в которых пользователь состоит косвенно(то есть родители групп, в которых он состоит непосредственно)
• groups - список групп в которых пользователь состоит непосредственно
• email - электронная почта пользователя
• id - айди в Auth API

---

Добавление метода аутентификации

1. Продумайте, какой путь должен совершить пользователь, чтобы войти в сервис с использованием вашего метода аутентификации

   • Все методы должны поддерживать минимум 2 варианта взаимодействия: регистрация нового пользователя (она же, добавление метода аутентификации существующему пользователю) и повторный вход.
   • Большинство внешних приложений (Google/Yandex/Telegram и др.) уже придумали все за вас и используют стандарт OAuth2 для авторизации внешних приложений, поэтому они очень похожи друг на друга и можно посомтреть примеры. Google авторизация уже реализована и можно почитать пути пользователя выше.

2. Определитесь, какие методы нужны для работы с вашим методом авторизации.

   • По умолчанию есть 2 API ручки: /login – вход (повторный), и /register – первичная регистрация/добавление нового метода авторизации
   • Для OAuth2 авторизации и аутентификации также обязательно определены ручки /auth_url и /redirect_url – возвращают URL, куда пользователя должен перенаправить наш фронтенд для ввода логина и пароля на внешнем ресурсе, и URL, куда внешнее приложение перенаправит результат входа, соответственно
   • Вы можете определить и свои методы, но помните, что их нужно также поддержать и на фронтенде приложения. Обязательно опишите пошагово (а лучше нарисуйте схему в Miro или draw.io), как будут рабоать ваши методы со стороны пользователя/фронтенда

3. Создайте новый файл в папке auth_backend/auth_plugins, создайте класс и отнаследуйте его

   • для legacy аутентификации от

     auth-api/auth_backend/auth_plugins/auth_method.py

     Line 37 in 1ce51bd

     class AuthMethodMeta(metaclass=ABCMeta):

   • для OAuth аутентификации от

     auth-api/auth_backend/auth_plugins/auth_method.py

     Line 112 in 1ce51bd

     class OauthMeta(AuthMethodMeta):

4. Задайте классу описание, prefix и tags

   auth-api/auth_backend/auth_plugins/google.py

   Lines 31 to 34 in 1ce51bd

   	"""Вход в приложение по аккаунту гугл"""
   	prefix = '/google'
   	tags = ['Google']

   • prefix используется как отправная точка для ваших методов. Ручка логина для метода авторизации с премиксом /myauth будет /myauth/login
   • Описание и теги используются для документирования кода. Зачастую без них непонятно, что вообще происходит. Не пропускайте их.

5. Создайте основные методы

   • Помните, что все методы являются @staticmethod или @classmethod. То есть не принимают аргумент self (текущий объект), а принимают ничего или cls (текущий класс) соответственно
   • Ручки /login и /register имеют сигнатуры async def _login(...) и async def _register(...) соответственно
   • Ручка /login обязательно возвращает объект

     auth-api/auth_backend/models/db.py

     Line 117 in 1ce51bd

     class UserSession(BaseDbModel):

   • Ручки /auth_url и /redirect_url методов OAuth2 обязательно возвращают оъект

     auth-api/auth_backend/auth_plugins/auth_method.py

     Lines 115 to 116 in 1ce51bd

     	class UrlSchema(Base):
     	url: str

Contributing

• Основная информация по разработке наших приложений

• Основная информация по разработке Auth API тут и тут