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

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

foo@bar:~$ python -m auth_backend

• DB_DSN – Адрес базы данных в фаормате postgresql://admin:admin@localhost:5432/dev
• EMAIL – Адрес электронной почты (логин для входа) для отправки уведомлений по Email
• EMAIL_PASS – Пароль от электронной почты
• HOST – Хост для использования в шаблонах сообщений электронной почты

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

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

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

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

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

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

1. Дернуть ручку POST /email/registrate . Вы передаете {email: "", password: ""}
2. На почту приходит письмо с линком на GET /email/approve?token='...', если по ней перейти то почта будет подтверждена и регистрацию можно считать завершенной.

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

1. Дернуть ручку POST /email/reset/password/request. Вы передаете {email: ""}в нагрузке
2. Вам придет письмо, где будет ссылка НА ФРОНТ(надо сделать это), в ссылке будет reset_token
3. Токен надо передать в ручку POST /email/reset/password в заголовках, вместе с {email: "", new_password: ""} и пароль будет изменен. email не понадобится после решения #36

1. Если пароль не забыт, а просто надо его поменять. Тогда в POST /email/reset/password/request передается токен авторизации, в теле вы передаете {email: "", password: "", new_password: ""}
2. Отправляете запрос и всё, пароль изменен, вам придет письмо с уведомлением о смене пароляю

1. Дернуть ручку POST /email/reset/email/request. Всего один вариант, передаете новое мыло в теле {email: ""} и токен атворизации в заголовках
2. На почту придет письмо с подтверждением почты, там будет токен подтверждения в query параметрах. Ссылка ведет на ручку GET пока что, но надо переделать, чтобы тоже вела на фронт.

Все примеры написаны для 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.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 сессии, иначе показываем экран ошибки авторизации

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

0. У вас должен быть аккаунт с правом на создание скоупсов :)
1. Получаете токен со скоупом auth.scope.create
2. Идете с токеном на ручку POST /scope, отправляете его туда в заголовке и в теле отправляете `{name: str - имя скоупа(там должно быть две точки и три слова без пробелов), comment - комментарий}
3. Профит

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