Estos scopes representan "permisos".

En OpenAPI (por ejemplo, en la documentación de la API), puedes definir "esquemas de seguridad".

Cuando uno de estos esquemas de seguridad usa OAuth2, también puedes declarar y usar scopes.

Cada "scope" es solo un string (sin espacios).

Normalmente se utilizan para declarar permisos de seguridad específicos, por ejemplo:

* `users:read` o `users:write` son ejemplos comunes.

# Seguridad Avanzada

## Funcionalidades Adicionales

Hay algunas funcionalidades extra para manejar la seguridad aparte de las cubiertas en el [Tutorial - Guía del Usuario: Seguridad](../../tutorial/security/index.md){.internal-link target=_blank}.

/// tip | Consejo

Las siguientes secciones **no son necesariamente "avanzadas"**.

Y es posible que para tu caso de uso, la solución esté en una de ellas.

///

## Lee primero el Tutorial

# Seguridad

Hay muchas formas de manejar la seguridad, autenticación y autorización.

Y normalmente es un tema complejo y "difícil".

En muchos frameworks y sistemas, solo manejar la seguridad y autenticación requiere una gran cantidad de esfuerzo y código (en muchos casos puede ser el 50% o más de todo el código escrito).

## Sobre seguridad, APIs y documentación

Ocultar las interfaces de usuario de la documentación en producción *no debería* ser la forma de proteger tu API.

Eso no añade ninguna seguridad extra a tu API, las *path operations* seguirán estando disponibles donde están.

Si hay una falla de seguridad en tu código, seguirá existiendo.

///

## Otros modelos

Ahora puedes obtener el usuario actual directamente en las *path operation functions* y manejar los mecanismos de seguridad a nivel de **Dependency Injection**, usando `Depends`.

Y puedes usar cualquier modelo o datos para los requisitos de seguridad (en este caso, un modelo de Pydantic `User`).

Pero no estás limitado a usar algún modelo de datos, clase o tipo específico.

# Simple OAuth2 con Password y Bearer

Ahora vamos a construir a partir del capítulo anterior y agregar las partes faltantes para tener un flujo de seguridad completo.

## Obtener el `username` y `password`

Vamos a usar las utilidades de seguridad de **FastAPI** para obtener el `username` y `password`.

OAuth2 especifica que cuando se utiliza el "password flow" (que estamos usando), el cliente/usuario debe enviar campos `username` y `password` como form data.

/// info | Detalles técnicos

**FastAPI** sabrá que puede usar la clase `OAuth2PasswordBearer` (declarada en una dependencia) para definir el esquema de seguridad en OpenAPI porque hereda de `fastapi.security.oauth2.OAuth2`, que a su vez hereda de `fastapi.security.base.SecurityBase`.

Todas las utilidades de seguridad que se integran con OpenAPI (y los docs automáticos del API) heredan de `SecurityBase`, así es como **FastAPI** puede saber cómo integrarlas en OpenAPI.

En casi cualquier framework el manejo de la seguridad se convierte en un tema bastante complejo rápidamente.

Muchos paquetes que lo simplifican tienen que hacer muchos compromisos con el modelo de datos, la base de datos y las funcionalidades disponibles. Y algunos de estos paquetes que simplifican las cosas demasiado en realidad tienen fallos de seguridad en el fondo.

---

///

/// info | Información

En este ejemplo usamos headers personalizados inventados `X-Key` y `X-Token`.

Pero en casos reales, al implementar seguridad, obtendrías más beneficios usando las [Utilidades de Seguridad integradas (el próximo capítulo)](../security/index.md){.internal-link target=_blank}.

///

## Errores de dependencias y valores de retorno

Estos ejemplos son intencionalmente simples, pero muestran cómo funciona todo.

En los capítulos sobre seguridad, hay funciones utilitarias que se implementan de esta misma manera.

Si entendiste todo esto, ya sabes cómo funcionan por debajo esas herramientas de utilidad para seguridad.