¿Cómo define OpenAPI los flujos de seguridad de OAuth 2.0?

¿Cómo define OpenAPI los flujos de seguridad de OAuth 2.0? #

OAuth 2.0 es el marco de autorización estándar del sector para las API REST. Define una familia de tipos de concesión (grant types, también llamados “flujos”) que describen cómo un cliente obtiene un token de acceso para llamar a una API protegida. La especificación OpenAPI ofrece un tipo de esquema de seguridad específico, oauth2, que describe los cuatro tipos de concesión de OAuth 2.0 con sus URL de autorización y de token, sus ámbitos (scopes) y su contexto de aplicación. Documentar correctamente OAuth 2.0 en OpenAPI permite que los portales de documentación muestren interfaces de autenticación interactivas, que los generadores de código produzcan código de cliente completo y que las herramientas de gobernanza verifiquen la cobertura de seguridad.

Declarar un esquema de seguridad de OAuth 2.0 #

Los esquemas de seguridad de OAuth 2.0 se declaran en components/securitySchemes:

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/oauth/authorize
          tokenUrl: https://auth.example.com/oauth/token
          refreshUrl: https://auth.example.com/oauth/token
          scopes:
            read:users: Read user profiles
            write:users: Create and update users
            read:orders: Read order data
            write:orders: Create and manage orders

El objeto flows contiene una o más definiciones de tipos de concesión. Cada flujo definido describe dónde se obtienen los tokens y qué scopes protegen cada funcionalidad.

Los cuatro flujos de OAuth 2.0 #

1. Código de autorización (`authorizationCode`) #

El flujo de código de autorización (authorization code) es el tipo de concesión más seguro y el más recomendado para aplicaciones en las que el cliente puede mantener un secreto (aplicaciones web de servidor) o para clientes públicos que usan PKCE (aplicaciones móviles y de página única). Implica una redirección a un servidor de autorización donde el usuario se autentica y concede su consentimiento.

flows:
  authorizationCode:
    authorizationUrl: https://auth.example.com/oauth/authorize
    tokenUrl: https://auth.example.com/oauth/token
    refreshUrl: https://auth.example.com/oauth/token
    scopes:
      read:users: Read user profiles
      write:users: Create and modify users

authorizationUrl: la URL a la que se redirige el navegador del usuario para la autenticación y el consentimiento.
tokenUrl: el endpoint donde se intercambia el código de autorización por un token de acceso.
refreshUrl: el endpoint para renovar los tokens de acceso caducados (opcional; suele ser el mismo que tokenUrl).
scopes: un mapa de nombres de scope con descripciones legibles por personas.

Herramientas como Swagger UI usan estos campos para mostrar un flujo de inicio de sesión de OAuth 2.0 directamente en el portal de documentación, de modo que los desarrolladores puedan autenticarse y hacer llamadas reales a la API.

2. Credenciales de cliente (`clientCredentials`) #

El flujo de credenciales de cliente (client credentials) está diseñado para la comunicación entre máquinas (M2M), donde no interviene ningún usuario humano. Un servicio se autentica directamente con su ID de cliente y su secreto para obtener un token de acceso.

flows:
  clientCredentials:
    tokenUrl: https://auth.example.com/oauth/token
    scopes:
      api:read: Read-only access to all resources
      api:write: Read and write access to all resources

Este es el flujo adecuado para:

Servicios de backend que llaman a otros servicios
Tareas programadas y procesadores por lotes
Pipelines de CI/CD que llaman a API de despliegue

3. Implícito (`implicit`) #

El flujo implícito se diseñó para aplicaciones de página única (SPA) basadas en navegador, antes de que existiera PKCE. Devuelve el token de acceso directamente en el fragmento de la URL tras la redirección de autorización, sin un intercambio intermedio de código.

flows:
  implicit:
    authorizationUrl: https://auth.example.com/oauth/authorize
    scopes:
      read:profile: Read the user's profile

Nota: hoy el flujo implícito se considera obsoleto e inseguro según las buenas prácticas actuales de seguridad de OAuth 2.0 (BCP). Las aplicaciones nuevas deben usar en su lugar el flujo de código de autorización con PKCE. Su presencia en la documentación de OpenAPI indica una API heredada.

4. Credenciales de contraseña del propietario del recurso (`password`) #

El flujo de contraseña permite que los clientes recojan directamente el nombre de usuario y la contraseña del usuario y los intercambien por un token. Se desaconseja encarecidamente en la mayoría de los casos, ya que obliga al cliente a manejar directamente las credenciales del usuario.

flows:
  password:
    tokenUrl: https://auth.example.com/oauth/token
    scopes:
      read:profile: Read the user's profile

Al igual que el flujo implícito, el tipo de concesión de contraseña se considera un patrón heredado. Solo es adecuado para clientes propios de máxima confianza o para sistemas heredados que no pueden migrarse al flujo de código de autorización.

Aplicar la seguridad de OAuth 2.0 a las operaciones #

Los esquemas de seguridad se aplican a nivel de documento (como valor predeterminado global) o a nivel de operación. El campo security recibe un arreglo (array) de objetos de requisito de seguridad, donde cada objeto asocia el nombre de un esquema con una lista de scopes requeridos.

Seguridad global #

security:
  - OAuth2:
      - read:users

Todas las operaciones requieren el scope read:users, salvo que se sobrescriba a nivel de operación.

Seguridad a nivel de operación #

paths:
  /users:
    get:
      summary: List users
      security:
        - OAuth2:
            - read:users
      responses:
        "200":
          description: OK
        "401":
          description: Unauthorized — missing or invalid token
        "403":
          description: Forbidden — token lacks required scope

  /users/{id}:
    put:
      summary: Update a user
      security:
        - OAuth2:
            - write:users
      responses:
        "200":
          description: OK
        "401":
          description: Unauthorized
        "403":
          description: Forbidden

Cada operación especifica exactamente qué scopes se requieren, lo que ofrece a los consumidores una comprensión precisa de los permisos necesarios.

Excluirse de la seguridad #

Una operación puede excluirse de forma explícita del requisito de seguridad global mediante un arreglo vacío:

/health:
  get:
    summary: Health check
    security: []
    responses:
      "200":
        description: Service is healthy

Varios esquemas de seguridad #

OpenAPI admite varios esquemas de seguridad, lo que permite que una API ofrezca simultáneamente distintos métodos de autenticación:

security:
  - OAuth2:
      - read:users
  - ApiKey: []

Cuando los requisitos de seguridad se enumeran como elementos independientes del arreglo, se tratan como alternativas (lógica OR): el cliente puede cumplir cualquiera de ellos. Los esquemas enumerados dentro de un mismo objeto son acumulativos (lógica AND): deben cumplirse todos.

Documentar los scopes en el objeto Info #

Algunos equipos usan info.description o la description del esquema de seguridad para explicar la semántica de los scopes y el flujo de autorización a los consumidores de la API:

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: >
        This API uses OAuth 2.0 with the Authorization Code + PKCE flow for
        user-facing clients and the Client Credentials flow for M2M access.
        Register your application at https://developer.example.com to obtain
        a client_id. See https://developer.example.com/oauth for full documentation.
      flows:
        authorizationCode:
          ...
        clientCredentials:
          ...

Integración de OAuth 2.0 en Swagger UI #

Swagger UI lee las definiciones de los flujos de OAuth 2.0 y muestra un botón “Authorize” que inicia el flujo correspondiente. En el flujo de código de autorización, abre una ventana emergente hacia authorizationUrl, gestiona la redirección y almacena el token resultante para usarlo en las solicitudes posteriores de “Try it out”. Para que esto funcione correctamente, es necesario configurar oauth2RedirectUrl en la configuración de Swagger UI.

Conclusión #

El tipo de esquema de seguridad oauth2 de OpenAPI ofrece una documentación precisa y legible por máquinas de los cuatro tipos de concesión de OAuth 2.0. Al declarar los scopes con claridad, aplicarlos con exactitud a las operaciones y documentar el flujo de autorización para los consumidores, los equipos de API permiten que los portales de documentación muestren flujos de inicio de sesión interactivos, que los generadores de código produzcan lógica de autenticación completa y que las herramientas de gobernanza auditen la cobertura de seguridad. Para las API modernas, el flujo de código de autorización con PKCE (para clientes orientados al usuario) y el flujo de credenciales de cliente (para M2M) son los patrones recomendados para documentar e implementar.

Última actualización: 30 de abril de 2026.