Seguridad - Primeros Pasos¶

Imaginemos que tienes tu API de backend en algún dominio.

Y tienes un frontend en otro dominio o en una ruta diferente del mismo dominio (o en una aplicación móvil).

Y quieres tener una forma de que el frontend se autentique con el backend, usando un usuario y contraseña.

Podemos usar OAuth2 para construir eso con FastAPI.

Pero ahorrémonos el tiempo de leer la especificación completa solo para encontrar esos pequeños fragmentos de información que necesitas.

Usemos las herramientas proporcionadas por FastAPI para manejar la seguridad.

Cómo se ve¶

Primero usemos el código y veamos cómo funciona, y luego volveremos para entender qué está pasando.

Crear main.py¶

Copia el ejemplo en un archivo 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}

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}

Ejecútalo¶

$ pip install python-multipart

Ejecuta el ejemplo con:

fastapi dev
fast →fastapi dev
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

restart ↻

Revísalo¶

Ve a la documentación interactiva en: http://127.0.0.1:8000/docs.

Verás algo como esto:

Y si haces clic, tienes un pequeño formulario de autorización para escribir un usuario y contraseña (y otros campos opcionales):

Esto por supuesto no es el frontend para los usuarios finales, pero es una gran herramienta automática para documentar interactivamente toda tu API.

Puede ser usado por el equipo frontend (que también puedes ser tú).

Puede ser usado por aplicaciones y sistemas de terceros.

Y también puedes usarlo tú mismo, para depurar, verificar y probar la misma aplicación.

El flujo password¶

Ahora volvamos un poco atrás y entendamos qué es todo eso.

El "flujo" password es una de las formas ("flujos") definidas en OAuth2, para manejar la seguridad y la autenticación.

OAuth2 fue diseñado para que el backend o la API pudieran ser independientes del servidor que autentica al usuario.

Pero en este caso, la misma aplicación FastAPI manejará la API y la autenticación.

Así que, revisémoslo desde ese punto de vista simplificado:

• El usuario escribe el usuario y la contraseña en el frontend, y presiona Enter.
• El frontend (ejecutándose en el navegador del usuario) envía ese usuario y contraseña a una URL específica en nuestra API (declarada con tokenUrl="token").
• The API checks that username and password, and responds with a "token" (we haven't implemented any of this yet).
  • Un "token" es simplemente un string con algún contenido que podemos usar después para verificar a este usuario.
  • Normally, a token is set to expire after some time.
    • Así que, el usuario tendrá que iniciar sesión de nuevo en algún momento después.
    • Y si el token es robado, el riesgo es menor. No es como una llave permanente que funcionará para siempre (en la mayoría de los casos).
• El frontend almacena ese token temporalmente en algún lugar.
• El usuario hace clic en el frontend para ir a otra sección de la aplicación web frontend.
• The frontend needs to fetch some more data from the API.
  • Pero necesita autenticación para ese endpoint específico.
  • Así que, para autenticarse con nuestra API, envía un header Authorization con un valor de Bearer más el token.
  • Si el token contiene foobar, el contenido del header Authorization sería: Bearer foobar.

OAuth2PasswordBearer de FastAPI¶

FastAPI proporciona varias herramientas, a diferentes niveles de abstracción, para implementar estas características de seguridad.

En este ejemplo vamos a usar OAuth2, con el flujo Password, usando un token Bearer. Hacemos eso usando la clase OAuth2PasswordBearer.

Cuando creamos una instancia de la clase OAuth2PasswordBearer pasamos el parámetro tokenUrl. Este parámetro contiene la URL que el cliente (el frontend ejecutándose en el navegador del usuario) usará para enviar el usuario y la contraseña para obtener un token.

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}

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}

Este parámetro no crea ese endpoint / path operation, sino que declara que la URL /token será la que el cliente debería usar para obtener el token. Esa información se usa en OpenAPI, y luego en los sistemas de documentación interactiva de la API.

Pronto también crearemos la path operation real.

La variable oauth2_scheme es una instancia de OAuth2PasswordBearer, pero también es un "callable".

Se podría llamar como:

oauth2_scheme(some, parameters)

Así que, puede ser usada con Depends.

Usarlo¶

Ahora puedes pasar ese oauth2_scheme en una dependencia con 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}

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}

Esta dependencia proporcionará un str que se asigna al parámetro token de la función de path operation.

FastAPI sabrá que puede usar esta dependencia para definir un "esquema de seguridad" en el esquema OpenAPI (y la documentación automática de la API).

Qué hace¶

Irá y buscará en la petición ese header Authorization, verificará si el valor es Bearer más algún token, y devolverá el token como un str.

Si no ve un header Authorization, o el valor no tiene un token Bearer, responderá con un error de código de estado 401 (UNAUTHORIZED) directamente.

Ni siquiera tienes que verificar si el token existe para devolver un error. Puedes estar seguro de que si tu función se ejecuta, tendrá un str en ese token.

Ya puedes probarlo en la documentación interactiva:

No estamos verificando la validez del token todavía, pero eso ya es un comienzo.

Resumen¶

Así, con solo 3 o 4 líneas extra, ya tienes alguna forma primitiva de seguridad.