¿Cómo gestiona OpenAPI la autenticación y la seguridad? #
OpenAPI es una herramienta potente y muy utilizada en el ámbito del desarrollo web para describir la estructura de las API. Aunque ofrece amplias capacidades de documentación, muchos desarrolladores también buscan mecanismos robustos para proteger sus API. Con este fin, OpenAPI incluye especificaciones y frameworks para gestionar la autenticación y la seguridad.
Este artículo analiza cómo gestiona OpenAPI la autenticación y la seguridad, y abarca distintos métodos como la autenticación Basic, la autenticación Bearer, las API keys y OAuth2. También exploraremos cómo se definen dentro de la especificación OpenAPI y cómo se relacionan con diversos casos de uso.
Introducción a OpenAPI #
OpenAPI, antes conocido como Swagger, es una especificación para crear API que permite que la documentación y las herramientas visuales interactúen con la API. Es independiente del lenguaje y permite que tanto las personas como los equipos informáticos comprendan las capacidades de un servicio web sin necesidad de acceder al código fuente, a la documentación ni de inspeccionar el tráfico de red.
Para obtener más información sobre OpenAPI, visita la OpenAPI Initiative.
Autenticación y seguridad en OpenAPI #
La autenticación y la seguridad son aspectos fundamentales del diseño de API, esenciales para proteger los datos y controlar el acceso. OpenAPI ofrece una forma estructurada de definir los métodos de autenticación y autorización dentro de la propia especificación de la API.
Esquemas de seguridad #
OpenAPI define esquemas de seguridad, que son los mecanismos que se pueden utilizar en la API para realizar la autenticación. Estos esquemas se definen en la sección components/securitySchemes del documento OpenAPI. Cada esquema de seguridad se puede referenciar después en las operaciones para especificar cómo se debe proteger la API.
Estos son los tipos de esquemas de seguridad que admite OpenAPI:
Esquemas de autenticación HTTP
- Autenticación Basic
- Autenticación Bearer (normalmente con JWT)
API key
- API keys en encabezados, parámetros de consulta o cookies
OAuth2
- Diversos flujos de OAuth2, como Authorization Code, Implicit, Password y Client Credentials
OpenID Connect Discovery
Veamos cada método con más detalle.
Autenticación Basic #
La autenticación Basic es uno de los métodos de autenticación más simples y directos. Consiste en enviar un nombre de usuario y una contraseña codificados en base64 como parte de los encabezados de la solicitud HTTP. Aunque es sencillo, no es el método más seguro a menos que se combine con HTTPS.
Así se puede definir la autenticación Basic en OpenAPI:
components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
Uso en una operación:
paths:
/secure-endpoint:
get:
security:
- BasicAuth: []
responses:
'200':
description: Successful response
Autenticación Bearer #
La autenticación Bearer suele consistir en utilizar un token, como un JWT (JSON Web Token), en el encabezado Authorization de la solicitud HTTP. Este método se usa con frecuencia por sus funciones de seguridad mejoradas.
Así se define la autenticación Bearer:
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
Uso en una operación:
paths:
/secure-endpoint:
get:
security:
- BearerAuth: []
responses:
'200':
description: Successful response
API keys #
Las API keys son tokens que se proporcionan a los clientes para acceder a la API. Pueden enviarse en distintas partes de la solicitud, como encabezados, parámetros de consulta o cookies. Las API keys ofrecen una forma sencilla de autenticación y son especialmente populares en las API de acceso público, donde se acepta una seguridad menos estricta.
Este es un ejemplo de definición de una API key:
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
Uso en una operación:
paths:
/secure-endpoint:
get:
security:
- ApiKeyAuth: []
responses:
'200':
description: Successful response
OAuth2 #
OAuth2 es un framework de autorización que permite a las aplicaciones obtener acceso limitado a las cuentas de usuario de un servicio HTTP. OAuth2 define varios flujos para adaptarse a distintos tipos de aplicaciones y métodos de autorización.
Esta es una definición de ejemplo de OAuth2 con el flujo Authorization Code:
components:
securitySchemes:
OAuth2:
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
delete: Grants delete access
Uso en una operación:
paths:
/secure-endpoint:
get:
security:
- OAuth2:
- read
responses:
'200':
description: Successful response
OpenID Connect Discovery #
OpenID Connect Discovery amplía OAuth2 para incluir una capa de identidad adicional. Se utiliza con frecuencia para el inicio de sesión único (Single Sign-On, SSO) y para compartir información de perfil de usuario.
Este es un ejemplo básico de OpenID Connect Discovery:
components:
securitySchemes:
openId:
type: openIdConnect
openIdConnectUrl: https://example.com/.well-known/openid-configuration
Uso en una operación:
paths:
/secure-endpoint:
get:
security:
- openId: []
responses:
'200':
description: Successful response
Aplicar la seguridad de forma global #
Aunque especificar esquemas de seguridad para cada endpoint por separado resulta útil, puede ser engorroso en API grandes. OpenAPI permite definir la seguridad de forma global, de modo que se aplique a todas las operaciones salvo que se sobrescriba explícitamente.
Este es un ejemplo de aplicación global de la autenticación Bearer:
security:
- BearerAuth: []
Esta definición compacta garantiza que todas las rutas de la API utilicen la autenticación Bearer de forma predeterminada.
Combinar varios requisitos de seguridad #
En algunos escenarios puede que necesites más de una forma de autenticación. OpenAPI permite combinar varios requisitos de seguridad dentro de una operación.
Este es un ejemplo en el que se requieren tanto una API key como un token OAuth2:
paths:
/secure-endpoint:
get:
security:
- ApiKeyAuth: []
OAuth2: []
responses:
'200':
description: Successful response
Casos de uso reales #
API públicas con control de acceso limitado #
Las API expuestas al público, como las de OpenWeather o NewsAPI, suelen utilizar API keys. Esto ofrece un medio sencillo de seguridad y, al mismo tiempo, un acceso controlado.
Sistemas empresariales con seguridad estricta #
En las aplicaciones empresariales son habituales los tokens Bearer y OAuth2. Por ejemplo, las API de Google utilizan OAuth2 para un acceso seguro y acotado a los recursos.
Identidad federada e inicio de sesión único #
Las plataformas que necesitan capacidades de federación o SSO, como las que utilizan Okta o Auth0, suelen recurrir a OpenID Connect.
Conclusión #
La disponibilidad de esquemas de seguridad en OpenAPI permite a los desarrolladores incluir medidas de seguridad robustas directamente en las especificaciones de sus API. Al atender distintas necesidades de autenticación mediante la autenticación Basic, los tokens Bearer, las API keys, OAuth2 y OpenID Connect, OpenAPI garantiza que los desarrolladores de API puedan diseñar sistemas seguros y accesibles.
Para obtener información adicional, aquí tienes algunos enlaces útiles:
Adoptar estas prácticas no solo protege tu API, sino que también facilita la integración y el cumplimiento de los estándares. Si aprovechas las capacidades de OpenAPI, podrás crear API seguras, escalables y bien documentadas.
Última actualización: 21 de mayo de 2024.