Autenticación y autorización de una API

Autenticar es comprobar quién llama: un token válido, firmado por quien corresponde, vigente y emitido para esta API. Autorizar es decidir qué puede hacer esa identidad, y se decide en dos niveles. El primero es la función: el permiso (el scope) dice que este cliente puede leer pólizas. El segundo es el objeto: de todas las pólizas que existen, esta identidad solo puede ver las suyas.

El primer nivel se resuelve con el permiso del token y suele estar bien hecho. El segundo no lo puede resolver el token, porque el token no sabe qué póliza se pedirá mañana: lo resuelve el servicio al leer el dato, comparando el dueño del recurso con la identidad de la petición. La falla de olvidarlo es la primera del catálogo de riesgos de APIs de OWASP de 2023 (API1:2023, autorización rota a nivel de objeto) y es la que más aparece en las revisiones de diseño.

Abre diseno/endpoints.txt. La última columna dice, endpoint por endpoint, si el servicio comprueba que el recurso pertenece al corredor del token. Las filas de crear un recurso nuevo no tienen objeto previo que comprobar. Busca el endpoint que entrega un recurso existente, por su id, y no hace la comprobación. Escribe el identificador de la fila.

Un arquitecto no propone la solución más elegante, propone la que cierra el riesgo con el menor costo para quien la va a construir. Para decidirlo se mira qué parte de la cadena ya existe: si otros endpoints del mismo servicio ya hacen la comprobación, la solución más barata suele ser hacer que el endpoint que falta la use igual, no rediseñar el sistema.

Lee diseno/notas-de-diseno.txt: explica cómo se identifican las pólizas y qué supuso el equipo. Una suposición que nadie ha comprobado no es un control. Después compara las tres propuestas.

Para obtener un token hay varios flujos de OAuth 2.0, y la elección depende de quién es el cliente. Una aplicación de navegador o móvil no puede guardar un secreto, así que usa el flujo de código de autorización con PKCE (RFC 7636): el token no viaja por la barra de direcciones y el código solo sirve a quien lo pidió. Un servidor de un aliado, que sí guarda secretos, usa credenciales de cliente.

La guía de seguridad actual de OAuth 2.0 (RFC 9700, enero de 2025) desaconseja el flujo implícito, que entrega el token directamente en la respuesta del navegador, porque ese token se filtra con facilidad. En diseno/clientes-oauth.txt está la lista de clientes de Guacamaya con su flujo y la vida de su token.

El principio de menor privilegio también se aplica a los permisos de los clientes: cada cliente recibe solo los que necesita su función. Un permiso administrativo en un cliente que usan corredores externos es una puerta abierta a una función que no es suya, aunque nadie la haya usado todavía.

En diseno/permisos-por-cliente.txt está lo que se concede a cada cliente y, al final, qué hace cada permiso. Compara las funciones de los corredores con lo que ese archivo les concede.