diff --git a/docs/ru/docs/tutorial/security/oauth2-jwt.md b/docs/ru/docs/tutorial/security/oauth2-jwt.md new file mode 100644 index 000000000..1195fad21 --- /dev/null +++ b/docs/ru/docs/tutorial/security/oauth2-jwt.md @@ -0,0 +1,261 @@ +# OAuth2 с паролем (и хешированием), Bearer с JWT-токенами + +Теперь, когда у нас определен процесс обеспечения безопасности, давайте сделаем приложение действительно безопасным, используя токены JWT и безопасное хеширование паролей. + +Этот код можно реально использовать в своем приложении, сохранять хэши паролей в базе данных и т.д. + +Мы продолжим разбираться, начиная с того места, на котором остановились в предыдущей главе. + +## Про JWT + +JWT означает "JSON Web Tokens". + +Это стандарт для кодирования JSON-объекта в виде длинной строки без пробелов. Выглядит это следующим образом: + +``` +eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c +``` + +Он не зашифрован, поэтому любой человек может восстановить информацию из его содержимого. + +Но он подписан. Следовательно, когда вы получаете токен, который вы эмитировали (выдавали), вы можете убедиться, что это именно вы его эмитировали. + +Таким образом, можно создать токен со сроком действия, скажем, 1 неделя. А когда пользователь вернется на следующий день с тем же токеном, вы будете знать, что он все еще авторизирован в вашей системе. + +Через неделю срок действия токена истечет, пользователь не будет авторизован и ему придется заново входить в систему, чтобы получить новый токен. А если пользователь (или третье лицо) попытается модифицировать токен, чтобы изменить срок действия, вы сможете это обнаружить, поскольку подписи не будут совпадать. + +Если вы хотите поиграть с JWT-токенами и посмотреть, как они работают, посмотрите https://jwt.io. + +## Установка `PyJWT` + +Нам необходимо установить `pyjwt` для генерации и проверки JWT-токенов на языке Python. + +Убедитесь, что вы создали [виртуальное окружение](../../virtual-environments.md){.internal-link target=_blank}, активируйте его, а затем установите `pyjwt`: + +
+ +```console +$ pip install pyjwt + +---> 100% +``` + +
+ +/// info | Дополнительная информация +Если вы планируете использовать алгоритмы цифровой подписи, такие как RSA или ECDSA, вам следует установить зависимость библиотеки криптографии `pyjwt[crypto]`. + +Подробнее об этом можно прочитать в документации по установке PyJWT. +/// + +## Хеширование паролей + +"Хеширование" означает преобразование некоторого содержимого (в данном случае пароля) в последовательность байтов (просто строку), которая выглядит как тарабарщина. + +Каждый раз, когда вы передаете точно такое же содержимое (точно такой же пароль), вы получаете точно такую же тарабарщину. + +Но преобразовать тарабарщину обратно в пароль невозможно. + +### Для чего нужно хеширование паролей + +Если ваша база данных будет украдена, то вор не получит пароли пользователей в открытом виде, а только их хэши. + +Таким образом, вор не сможет использовать этот пароль в другой системе (поскольку многие пользователи везде используют один и тот же пароль, это было бы опасно). + +## Установка `passlib` + +PassLib - это отличный пакет Python для работы с хэшами паролей. + +Он поддерживает множество безопасных алгоритмов хеширования и утилит для работы с ними. + +Рекомендуемый алгоритм - "Bcrypt". + +Убедитесь, что вы создали и активировали виртуальное окружение, и затем установите PassLib вместе с Bcrypt: + +
+ +```console +$ pip install "passlib[bcrypt]" + +---> 100% +``` + +
+ +/// tip | Подсказка +С помощью `passlib` можно даже настроить его на чтение паролей, созданных **Django**, плагином безопасности **Flask** или многими другими библиотеками. + +Таким образом, вы сможете, например, совместно использовать одни и те же данные из приложения Django в базе данных с приложением FastAPI. Или постепенно мигрировать Django-приложение, используя ту же базу данных. + +При этом пользователи смогут одновременно входить в систему как из приложения Django, так и из приложения **FastAPI**. +/// + +## Хеширование и проверка паролей + +Импортируйте необходимые инструменты из `passlib`. + +Создайте "контекст" PassLib. Именно он будет использоваться для хэширования и проверки паролей. + +/// tip | Подсказка +Контекст PassLib также имеет функциональность для использования различных алгоритмов хеширования, в том числе и устаревших, только для возможности их проверки и т.д. + +Например, вы можете использовать его для чтения и проверки паролей, сгенерированных другой системой (например, Django), но хэшировать все новые пароли другим алгоритмом, например Bcrypt. + +И при этом быть совместимым со всеми этими системами. +/// + +Создайте служебную функцию для хэширования пароля, поступающего от пользователя. + +А затем создайте другую - для проверки соответствия полученного пароля и хранимого хэша. + +И еще одну - для аутентификации и возврата пользователя. + +{* ../../docs_src/security/tutorial004_an_py310.py hl[8,49,56:57,60:61,70:76] *} + +/// note | Технические детали +Если проверить новую (фальшивую) базу данных `fake_users_db`, то можно увидеть, как теперь выглядит хэшированный пароль: `"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`. +/// + +## Работа с JWT токенами + +Импортируйте установленные модули. + +Создайте случайный секретный ключ, который будет использоваться для подписи JWT-токенов. + +Для генерации безопасного случайного секретного ключа используйте команду: + +
+ +```console +$ openssl rand -hex 32 + +09d25e094faa6ca2556c818166b7a9563b93f7099f6f0f4caa6cf63b88e8d3e7 +``` + +
+ +И скопируйте полученный результат в переменную `SECRET_KEY` (не используйте тот, что в примере). + +Создайте переменную `ALGORITHM` с алгоритмом, используемым для подписи JWT-токена, и установите для нее значение `"HS256"`. + +Создайте переменную для срока действия токена. + +Определите Pydantic Model, которая будет использоваться для формирования ответа на запрос на получение токена. + +Создайте служебную функцию для генерации нового токена доступа. + +{* ../../docs_src/security/tutorial004_an_py310.py hl[4,7,13:15,29:31,79:87] *} + +## Обновление зависимостей + +Обновите `get_current_user` для получения того же токена, что и раньше, но на этот раз с использованием JWT-токенов. + +Декодируйте полученный токен, проверьте его и верните текущего пользователя. + +Если токен недействителен, то сразу же верните HTTP-ошибку. + +{* ../../docs_src/security/tutorial004_an_py310.py hl[90:107] *} + +## Обновление *операции пути* `/token` + +Создайте `timedelta` со временем истечения срока действия токена. + +Создайте реальный токен доступа JWT и верните его + +{* ../../docs_src/security/tutorial004_an_py310.py hl[118:133] *} + +### Технические подробности о JWT ключе `sub` + +В спецификации JWT говорится, что существует ключ `sub`, содержащий субъект токена. + +Его использование необязательно, но это именно то место, куда вы должны поместить идентификатор пользователя, и поэтому мы здесь его и используем. + +JWT может использоваться и для других целей, помимо идентификации пользователя и предоставления ему возможности выполнять операции непосредственно в вашем API. + +Например, вы могли бы определить "автомобиль" или "запись в блоге". + +Затем вы могли бы добавить права доступа к этой сущности, например "управлять" (для автомобиля) или "редактировать" (для блога). + +Затем вы могли бы передать этот JWT-токен пользователю (или боту), и они использовали бы его для выполнения определенных действий (управление автомобилем или редактирование запись в блоге), даже не имея учетной записи, просто используя JWT-токен, сгенерированный вашим API. + +Используя эти идеи, JWT можно применять для гораздо более сложных сценариев. + +В отдельных случаях несколько сущностей могут иметь один и тот же идентификатор, скажем, `foo` (пользователь `foo`, автомобиль `foo` и запись в блоге `foo`). + +Поэтому, чтобы избежать коллизий идентификаторов, при создании JWT-токена для пользователя можно добавить префикс `username` к значению ключа `sub`. Таким образом, в данном примере значение `sub` было бы `username:johndoe`. + +Важно помнить, что ключ `sub` должен иметь уникальный идентификатор для всего приложения и представлять собой строку. + +## Проверка в действии + +Запустите сервер и перейдите к документации: http://127.0.0.1:8000/docs. + +Вы увидите пользовательский интерфейс вида: + + + +Пройдите авторизацию так же, как делали раньше. + +Используя учетные данные пользователя: + +Username: `johndoe` +Password: `secret` + +/// check | Заметка +Обратите внимание, что нигде в коде не используется открытый текст пароля "`secret`", мы используем только его хэшированную версию. +/// + + + +Вызвав эндпоинт `/users/me/`, вы получите ответ в виде: + +```JSON +{ + "username": "johndoe", + "email": "johndoe@example.com", + "full_name": "John Doe", + "disabled": false +} +``` + + + +Если открыть инструменты разработчика, то можно увидеть, что передаваемые данные включают только токен, пароль передается только в первом запросе для аутентификации пользователя и получения токена доступа, но не в последующих: + + + +/// note | Техническая информация +Обратите внимание на заголовок `Authorization`, значение которого начинается с `Bearer`. +/// + +## Продвинутое использование `scopes` + +В OAuth2 существует понятие "диапазоны" ("`scopes`"). + +С их помощью можно добавить определенный набор разрешений к JWT-токену. + +Затем вы можете передать этот токен непосредственно пользователю или третьей стороне для взаимодействия с вашим API с определенным набором ограничений. + +О том, как их использовать и как они интегрированы в **FastAPI**, читайте далее в **Руководстве пользователя**. + +## Резюме + +С учетом того, что вы видели до сих пор, вы можете создать безопасное приложение **FastAPI**, используя такие стандарты, как OAuth2 и JWT. + +Практически в любом фреймворке работа с безопасностью довольно быстро превращается в сложную тему. + +Многие пакеты, сильно упрощающие эту задачу, вынуждены идти на многочисленные компромиссы с моделью данных, с базой данных и с доступным функционалом. Некоторые из этих пакетов, которые пытаются уж слишком все упростить, имеют даже "дыры" в системе безопасности. + +--- + +**FastAPI** не делает уступок ни одной базе данных, модели данных или инструментарию. + +Он предоставляет вам полную свободу действий, позволяя выбирать то, что лучше всего подходит для вашего проекта. + +Вы можете напрямую использовать многие хорошо поддерживаемые и широко распространенные пакеты, такие как `passlib` и `PyJWT`, поскольку **FastAPI** не требует сложных механизмов для интеграции внешних пакетов. + +Напротив, он предоставляет инструменты, позволяющие максимально упростить этот процесс без ущерба для гибкости, надежности и безопасности. + +При этом вы можете использовать и реализовывать безопасные стандартные протоколы, такие как OAuth2, относительно простым способом. + +В **Руководстве пользователя** вы можете узнать больше о том, как использовать "диапазоны" ("`scopes`") OAuth2 для создания более точно настроенной системы разрешений в соответствии с теми же стандартами. OAuth2 с диапазонами - это механизм, используемый многими крупными провайдерами сервиса аутентификации, такими как Facebook, Google, GitHub, Microsoft, Twitter и др., для авторизации сторонних приложений на взаимодействие с их API от имени их пользователей.