Proteger endpoints con JWT en OpenAPI
Contenido del curso
Kevin David Garcia Castillo
Lucho Rodriguez
Leonardo Palacio Mejía
Miguel Angel Reyes Moreno
En OpenAPI, los corchetes vacíos en el campo security se utilizan para indicar que la autenticación es opcional. En el caso de JWT: [], significa que el endpoint puede ser accedido sin la necesidad de un token JWT específico. Esto es útil cuando se tiene un endpoint público que no requiere autenticación, mientras que otros endpoints pueden tener configuraciones de seguridad más estrictas. Recuerda que la especificación de seguridad define cómo se protege el acceso a la API.
En la documentación dice que los corchetes vacíos se usan porque hacen referencia a security scopes, que solo se configuran para OAuth y OpenID Connect.
La siguiente configuración permite definir un esquema de seguridad y usarlo de forma global en todos los endpoints de la api:
openapi: 3.1.1 ... components: ... securitySchemes: # Definición del esquema de seguridad JWT: # nombre arbitrario type: http scheme: bearer # Define el uso del esquema de seguridad de manera global security: - JWT: []
Si por el contrario, se desea usarlo para algunos endpoints y otros no, se debe omitir la llave security en la raíz del openapi.yml y especificarlo a nivel de los endpoints a autenticar.
paths: ... /products: get: ... security: - JWT: []
Es posible modularizar tu archivo OpenAPI en diferentes carpetas y archivos. Esto se logra usando $ref para hacer referencia a componentes definidos en otros archivos YAML, lo que te permite organizar tu especificación de forma limpia y reutilizable.
Es bueno saber esto, porque ya está bastante grande el archivo y es fácil confundirse.
Les comparto un ejemplo:
openapi: 3.1.1
info:
title: API First
version: 1.0.0
description: Designing an API using API First
servers:
- url: http://localhost:3000
paths:
/products:
$ref: './paths/products.yaml'
components:
schemas:
Product:
$ref: './schemas/Product.yaml'
Error:
$ref: './schemas/Error.yaml'
