Перейти к содержанию

Безопасность - первые шаги

Представим, что у вас есть свой бэкенд API на некотором домене.

И у вас есть фронтенд на другом домене или на другом пути того же домена (или в мобильном приложении).

И вы хотите иметь возможность аутентификации фронтенда с бэкендом, используя имя пользователя и пароль.

Мы можем использовать OAuth2 для создания такой системы с помощью FastAPI.

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

Для работы с безопасностью воспользуемся средствами, предоставленными FastAPI.

Как это выглядит

Давайте сначала просто воспользуемся кодом и посмотрим, как он работает, а затем детально разберём, что происходит.

Создание main.py

Скопируйте пример в файл main.py:

from typing import Annotated

from fastapi import Depends, FastAPI
from fastapi.security import OAuth2PasswordBearer

app = FastAPI()

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


@app.get("/items/")
async def read_items(token: Annotated[str, Depends(oauth2_scheme)]):
    return {"token": token}
🤓 Other versions and variants 
from fastapi import Depends, FastAPI
from fastapi.security import OAuth2PasswordBearer
from typing_extensions import Annotated

app = FastAPI()

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


@app.get("/items/")
async def read_items(token: Annotated[str, Depends(oauth2_scheme)]):
    return {"token": token}

Tip

Prefer to use the Annotated version if possible.

from fastapi import Depends, FastAPI
from fastapi.security import OAuth2PasswordBearer

app = FastAPI()

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


@app.get("/items/")
async def read_items(token: str = Depends(oauth2_scheme)):
    return {"token": token}

Запуск

Дополнительная информация

Вначале, установите библиотеку python-multipart.

А именно: pip install python-multipart.

Это связано с тем, что OAuth2 использует "данные формы" для передачи имени пользователя и пароля.

Запустите ваш сервер:

$ uvicorn main:app --reload

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Проверка

Перейдите к интерактивной документации по адресу: http://127.0.0.1:8000/docs.

Вы увидите примерно следующее:

Кнопка авторизации!

У вас уже появилась новая кнопка "Authorize".

А у операции пути теперь появился маленький замочек в правом верхнем углу, на который можно нажать.

При нажатии на нее появляется небольшая форма авторизации, в которую нужно ввести имя пользователя и пароль (и другие необязательные поля):

Технические детали

Неважно, что вы введете в форму, она пока не будет работать. Но мы к этому еще придем.

Конечно, это не фронтенд для конечных пользователей, но это отличный автоматический инструмент для интерактивного документирования всех ваших API.

Он может использоваться командой фронтенда (которой можете быть и вы сами).

Он может быть использован сторонними приложениями и системами.

Кроме того, его можно использовать самостоятельно для отладки, проверки и тестирования одного и того же приложения.

Аутентификация по паролю

Теперь давайте вернемся немного назад и разберемся, что же это такое.

Аутентификация по паролю является одним из способов, определенных в OAuth2, для обеспечения безопасности и аутентификации.

OAuth2 был разработан для того, чтобы бэкэнд или API были независимы от сервера, который аутентифицирует пользователя.

Но в нашем случае одно и то же приложение FastAPI будет работать с API и аутентификацией.

Итак, рассмотрим его с этой упрощенной точки зрения:

  • Пользователь вводит на фронтенде имя пользователя и пароль и нажимает Enter.
  • Фронтенд (работающий в браузере пользователя) отправляет эти имя пользователя и пароль на определенный URL в нашем API (объявленный с помощью параметра tokenUrl="token").
  • API проверяет эти имя пользователя и пароль и выдает в ответ "токен" (мы еще не реализовали ничего из этого).
    • "Токен" - это просто строка с некоторым содержимым, которое мы можем использовать позже для верификации пользователя.
    • Обычно срок действия токена истекает через некоторое время.
      • Таким образом, пользователю придется снова войти в систему в какой-то момент времени.
      • И если токен будет украден, то риск будет меньше, так как он не похож на постоянный ключ, который будет работать вечно (в большинстве случаев).
  • Фронтенд временно хранит этот токен в каком-то месте.
  • Пользователь щелкает мышью на фронтенде, чтобы перейти в другой раздел на фронтенде.
  • Фронтенду необходимо получить дополнительные данные из API.
    • Но для этого необходима аутентификация для конкретной конечной точки.
    • Поэтому для аутентификации в нашем API он посылает заголовок Authorization со значением Bearer плюс сам токен.
    • Если токен содержит foobar, то содержание заголовка Authorization будет таким: Bearer foobar.

Класс OAuth2PasswordBearer в FastAPI

FastAPI предоставляет несколько средств на разных уровнях абстракции для реализации этих функций безопасности.

В данном примере мы будем использовать OAuth2, с аутентификацией по паролю, используя токен Bearer. Для этого мы используем класс OAuth2PasswordBearer.

Дополнительная информация

Токен "bearer" - не единственный вариант, но для нашего случая он является наилучшим.

И это может быть лучшим вариантом для большинства случаев использования, если только вы не являетесь экспертом в области OAuth2 и точно знаете, почему вам лучше подходит какой-то другой вариант.

В этом случае FastAPI также предоставляет инструменты для его реализации.

При создании экземпляра класса OAuth2PasswordBearer мы передаем в него параметр tokenUrl. Этот параметр содержит URL, который клиент (фронтенд, работающий в браузере пользователя) будет использовать для отправки имени пользователя и пароля с целью получения токена.

from typing import Annotated

from fastapi import Depends, FastAPI
from fastapi.security import OAuth2PasswordBearer

app = FastAPI()

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


@app.get("/items/")
async def read_items(token: Annotated[str, Depends(oauth2_scheme)]):
    return {"token": token}
🤓 Other versions and variants 
from fastapi import Depends, FastAPI
from fastapi.security import OAuth2PasswordBearer
from typing_extensions import Annotated

app = FastAPI()

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


@app.get("/items/")
async def read_items(token: Annotated[str, Depends(oauth2_scheme)]):
    return {"token": token}

Tip

Prefer to use the Annotated version if possible.

from fastapi import Depends, FastAPI
from fastapi.security import OAuth2PasswordBearer

app = FastAPI()

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


@app.get("/items/")
async def read_items(token: str = Depends(oauth2_scheme)):
    return {"token": token}

Подсказка

Здесь tokenUrl="token" ссылается на относительный URL token, который мы еще не создали. Поскольку это относительный URL, он эквивалентен ./token.

Поскольку мы используем относительный URL, если ваш API расположен по адресу https://example.com/, то он будет ссылаться на https://example.com/token. Если же ваш API расположен по адресу https://example.com/api/v1/, то он будет ссылаться на https://example.com/api/v1/token.

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

Этот параметр не создает конечную точку / операцию пути, а объявляет, что URL /token будет таким, который клиент должен использовать для получения токена. Эта информация используется в OpenAPI, а затем в интерактивных системах документации API.

Вскоре мы создадим и саму операцию пути.

Дополнительная информация

Если вы очень строгий "питонист", то вам может не понравиться стиль названия параметра tokenUrl вместо token_url.

Это связано с тем, что тут используется то же имя, что и в спецификации OpenAPI. Таким образом, если вам необходимо более подробно изучить какую-либо из этих схем безопасности, вы можете просто использовать копирование/вставку, чтобы найти дополнительную информацию о ней.

Переменная oauth2_scheme является экземпляром OAuth2PasswordBearer, но она также является "вызываемой".

Ее можно вызвать следующим образом:

oauth2_scheme(some, parameters)

Поэтому ее можно использовать вместе с Depends.

Использование

Теперь вы можете передать ваш oauth2_scheme в зависимость с помощью Depends.

from typing import Annotated

from fastapi import Depends, FastAPI
from fastapi.security import OAuth2PasswordBearer

app = FastAPI()

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


@app.get("/items/")
async def read_items(token: Annotated[str, Depends(oauth2_scheme)]):
    return {"token": token}
🤓 Other versions and variants 
from fastapi import Depends, FastAPI
from fastapi.security import OAuth2PasswordBearer
from typing_extensions import Annotated

app = FastAPI()

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


@app.get("/items/")
async def read_items(token: Annotated[str, Depends(oauth2_scheme)]):
    return {"token": token}

Tip

Prefer to use the Annotated version if possible.

from fastapi import Depends, FastAPI
from fastapi.security import OAuth2PasswordBearer

app = FastAPI()

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


@app.get("/items/")
async def read_items(token: str = Depends(oauth2_scheme)):
    return {"token": token}

Эта зависимость будет предоставлять строку, которая присваивается параметру token в функции операции пути.

FastAPI будет знать, что он может использовать эту зависимость для определения "схемы безопасности" в схеме OpenAPI (и автоматической документации по API).

Технические детали

FastAPI будет знать, что он может использовать класс OAuth2PasswordBearer (объявленный в зависимости) для определения схемы безопасности в OpenAPI, поскольку он наследуется от fastapi.security.oauth2.OAuth2, который, в свою очередь, наследуется от fastapi.security.base.SecurityBase.

Все утилиты безопасности, интегрируемые в OpenAPI (и автоматическая документация по API), наследуются от SecurityBase, поэтому FastAPI может знать, как интегрировать их в OpenAPI.

Что он делает

Он будет искать в запросе заголовок Authorization и проверять, содержит ли он значение Bearer с некоторым токеном, и возвращать токен в виде строки.

Если он не видит заголовка Authorization или значение не имеет токена Bearer, то в ответ будет выдана ошибка с кодом состояния 401 (UNAUTHORIZED).

Для возврата ошибки даже не нужно проверять, существует ли токен. Вы можете быть уверены, что если ваша функция будет выполнилась, то в этом токене есть строка.

Проверить это можно уже сейчас в интерактивной документации:

Мы пока не проверяем валидность токена, но для начала неплохо.

Резюме

Таким образом, всего за 3-4 дополнительные строки вы получаете некую примитивную форму защиты.