¿Qué son los esquemas de seguridad de OpenAPI? #

OpenAPI, antes conocida como Swagger, es un conjunto de reglas y una especificación creada para definir API RESTful. Una de sus características clave es la capacidad de definir mecanismos de seguridad de forma eficaz mediante los “esquemas de seguridad”. Este artículo explora el concepto de esquemas de seguridad de OpenAPI: qué son, cuáles son sus tipos y cómo se pueden implementar.

Comprender los esquemas de seguridad #

Definición #

Un esquema de seguridad en OpenAPI es un método de autenticación que los clientes de la API deben utilizar para acceder a recursos protegidos. Estos esquemas definen los tipos de autorización que requiere una API y ayudan a especificar cómo deben implementarse y configurarse los protocolos de seguridad.

Importancia #

Las API suelen estar expuestas a internet, lo que las hace vulnerables a diversos ataques. Implementar medidas de seguridad sólidas es crucial para garantizar que los usuarios no autorizados no accedan a datos sensibles ni realicen acciones no permitidas. Los esquemas de seguridad definen cómo se gestionan la autenticación y la autorización, y contribuyen a la seguridad global de la API.

Tipos de esquemas de seguridad de OpenAPI #

OpenAPI admite varios tipos de esquemas de seguridad, cada uno adecuado para distintos casos de uso. A continuación se ofrece un resumen de los principales tipos:

1. API key #

Una API key es una forma sencilla de autenticación, normalmente compuesta por una cadena larga que se envía como parámetro de consulta, encabezado o cookie. El servidor comprueba la validez de esta clave para determinar si el cliente está autorizado a acceder a determinados endpoints.

Ejemplo en OpenAPI 3.0 #

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - ApiKeyAuth: []

Ejemplo en OpenAPI 2.0 (Swagger) #

securityDefinitions:
  ApiKeyAuth:
    type: apiKey
    name: api_key
    in: header

security:
  - ApiKeyAuth: []

2. Autenticación HTTP #

La autenticación HTTP abarca varios esquemas de autenticación basados en HTTP, como la autenticación Basic y el token Bearer.

Autenticación Basic #

En la autenticación Basic, el usuario proporciona un nombre de usuario y una contraseña, que se codifican en Base64 y se incluyen en el encabezado Authorization de la solicitud HTTP.

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

security:
  - BasicAuth: []

Token Bearer #

El token Bearer se utiliza ampliamente en contextos de OAuth 2.0, donde se envía un token (normalmente un JWT) en el encabezado Authorization de la solicitud HTTP.

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - BearerAuth: []

3. OAuth2 #

OAuth2 es un framework de autorización que permite a aplicaciones de terceros obtener acceso limitado a cuentas de usuario. OAuth2 es muy configurable y admite distintos flujos, como:

• Authorization Code Flow
• Implicit Flow
• Password Flow
• Client Credentials Flow

Ejemplo en OpenAPI 3.0 (Authorization Code Flow) #

components:
  securitySchemes:
    OAuth2Auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Grants read access
            write: Grants write access
            admin: Grants access to admin operations

security:
  - OAuth2Auth:
      - read
      - write

4. OpenID Connect #

OpenID Connect (OIDC) es un protocolo de autenticación interoperable construido sobre el framework OAuth2. Permite a los clientes verificar la identidad de un usuario final a partir de la autenticación realizada por un servidor de autorización.

Ejemplo en OpenAPI 3.0 #

components:
  securitySchemes:
    OpenIDAuth:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration

security:
  - OpenIDAuth: []

Aplicar esquemas de seguridad en OpenAPI #

Definiciones de componentes #

Los esquemas de seguridad se definen dentro de la sección components de un archivo OpenAPI, lo que permite reutilizarlos en distintos endpoints.

Seguridad de los endpoints #

Una vez definidos los esquemas de seguridad, puedes aplicarlos de forma global o a rutas y endpoints concretos:

Seguridad global #

Una definición de seguridad global significa que los esquemas especificados se aplican a todos los endpoints de la API.

security:
  - ApiKeyAuth: []
  - OAuth2Auth:
      - read

Seguridad por endpoint #

Aplicar los esquemas de seguridad endpoint por endpoint ofrece flexibilidad, sobre todo si distintos endpoints requieren diferentes tipos de seguridad.

paths:
  /user:
    get:
      security:
        - BearerAuth: []
    post:
      security:
        - OAuth2Auth:
            - write

Buenas prácticas #

Al implementar esquemas de seguridad en OpenAPI:

1. Reutilización: define los esquemas de seguridad en la sección reutilizable components para evitar redundancias.

2. Control de acceso granular: aplica los esquemas de seguridad en varios niveles (global y por endpoint) para controlar de forma segura el acceso a tu API.

3. Usa HTTPS: utiliza siempre HTTPS para proteger la comunicación con la API, especialmente cuando uses esquemas como Basic Auth, que transmiten las credenciales codificadas pero no cifradas.

4. Mantenlo actualizado: actualiza con regularidad las definiciones de tus esquemas de seguridad para adaptarte a nuevas amenazas y vulnerabilidades.

5. Documentación de la API: documenta con claridad los requisitos de seguridad y cómo pueden obtener los desarrolladores las credenciales necesarias. Una documentación completa facilita la adopción de tu API.

Conclusión #

La seguridad es primordial al exponer API en internet. Los esquemas de seguridad de OpenAPI ofrecen una forma sólida de definir e implementar diversos métodos de autenticación y autorización, y así proteger tu API de manera eficaz. Si conoces los tipos de esquemas de seguridad y las buenas prácticas de implementación, podrás proteger tu API frente a accesos no autorizados y posibles amenazas de seguridad.

Para obtener información más detallada, puedes visitar la especificación OpenAPI o consultar la OpenAPI Initiative.

¡Feliz diseño de API!

Última actualización: 29 de mayo de 2024.