Saltar al contenido principal

Protege recursos globales de API

Protege las APIs de todo el producto utilizando el control de acceso basado en roles (RBAC) en Logto. Asigna roles y permisos globales para controlar el acceso de todos los usuarios y clientes en tu aplicación.

¿Qué son los recursos globales de API?​

Los recursos globales de API son endpoints o servicios en tu aplicación que son accesibles para todos los usuarios, sin importar la organización o el inquilino. Normalmente, estos son APIs públicos, servicios centrales del producto o cualquier endpoint que no esté limitado a una organización específica.

Casos de uso incluyen

  • APIs públicas o endpoints compartidos entre toda tu base de usuarios.
  • Microservicios que no están ligados a la multi-tenencia.
  • APIs centrales de la aplicación (por ejemplo, /api/users, /api/products) utilizadas por todos los clientes.

Logto te permite asegurar estas APIs usando OAuth 2.1, combinado con un control de acceso flexible basado en roles.

Cómo funciona en Logto​

  • Los recursos de API y permisos se registran globalmente: Cada API que deseas proteger se define con un indicador de recurso único (URI) y un conjunto de permisos (alcances) que controlan el acceso.
  • El acceso se controla mediante roles globales: Puedes asignar permisos a roles, que luego se asignan a usuarios o clientes.
  • Separado de los permisos a nivel de organización: Los recursos globales de API no tienen contexto de organización. Sin embargo, pueden usarse junto con roles de organización para proporcionar una capa adicional de contexto si es necesario. Para proteger APIs a nivel de organización, consulta Proteger recursos de API a nivel de organización.
Recursos globales de API RBAC

Resumen de la implementación​

  1. Registra tu recurso de API y define sus permisos en Logto.
  2. Define roles con los permisos necesarios para acceder a la API.
  3. Asigna roles a usuarios o clientes.
  4. Utiliza los flujos de autorización OAuth 2.0 para obtener tokens de acceso para la API (el parámetro resource debe coincidir con el identificador de API registrado).
  5. Valida los tokens de acceso en tu API para hacer cumplir los permisos.

Entendiendo los indicadores de recurso​

Logto modela los recursos de API según RFC 8707: Indicadores de recurso para OAuth 2.0. Un indicador de recurso es un URI que identifica de manera única la API o servicio objetivo solicitado.

Puntos clave

  • Los indicadores de recurso deben ser URIs absolutas (por ejemplo, https://api.example.com)
  • Sin componente de fragmento; evita usar cadenas de consulta cuando sea posible.
  • Los indicadores de recurso permiten tokens restringidos por audiencia y soporte para arquitecturas multi-API.

Ejemplo

  • Management API: https://my-tenant.logto.app/api
  • API global personalizada: https://api.yourapp.com

Flujo de autorización: autenticando y asegurando tu API​

El siguiente flujo aplica tanto para la autenticación interactiva de usuarios (navegador / app) como para escenarios backend máquina a máquina (M2M).

Ten en cuenta que el flujo no incluye todos los detalles sobre los parámetros o encabezados requeridos, sino que se enfoca en los pasos clave involucrados. Continúa leyendo para ver cómo funciona el flujo en la práctica.

Autenticación de usuario = navegador / app. M2M = servicio backend o script usando credenciales de cliente.

nota:

El parámetro resource debe coincidir exactamente con el identificador de API (indicador de recurso) que registraste en Logto.

Pasos de implementación​

Registra tus recursos de API​

  1. Ve a Consola → Recursos de API.
  2. Crea un nuevo recurso de API (por ejemplo, https://api.yourapp.com/org) y define sus permisos (alcances).

Para ver los pasos completos de configuración, consulta Definir recursos de API con permisos.

Configura roles globales​

  1. Ve a Consola → Roles.
  2. Crea roles que correspondan a los permisos de tu API (por ejemplo, read:products, write:products).
  3. Asigna estos roles a los usuarios o clientes que necesiten acceso a la API.

Para ver los pasos completos de configuración, consulta Usar roles globales.

Obtén tokens de acceso para recursos globales de API​

Antes de acceder a un recurso global de API, tu cliente debe obtener un token de acceso. Logto emite JSON Web Tokens (JWTs) como tokens de acceso para recursos globales de API. Esto normalmente se realiza usando el flujo de código de autorización OAuth 2.0, flujo de refresh token, o el flujo de credenciales de cliente.

Flujo de código de autorización o refresh token​

Todos los SDK oficiales de Logto admiten la obtención de tokens de acceso para recursos globales de API usando el flujo de refresh token de forma predeterminada. También se puede usar una biblioteca cliente estándar de OAuth 2.0 / OIDC para implementar este flujo.

Al inicializar el cliente Logto, añade el indicador de recurso al parámetro resources (array), luego añade los permisos deseados (alcances) al parámetro scopes.

Una vez que el usuario está autenticado, pasa el indicador de recurso en el parámetro resource o en un parámetro de nombre similar al solicitar el token de acceso (por ejemplo, llamando a getAccessToken()).

Para detalles sobre cada SDK, consulta los Inicios rápidos.

Flujo de credenciales de cliente​

Para escenarios máquina a máquina (M2M), puedes usar el flujo de credenciales de cliente para obtener un token de acceso para tu recurso global de API. Haciendo una solicitud POST al endpoint /oidc/token de Logto, puedes solicitar un token de acceso usando tu client ID y secret.

Hay dos parámetros clave que debes incluir en la solicitud:

  • resource: El URI indicador de recurso de la API a la que deseas acceder (por ejemplo, https://api.yourapp.com).
  • scope: Los permisos que deseas solicitar para la API (por ejemplo, read:products write:products).

Aquí tienes un ejemplo no normativo de la solicitud de token usando el grant type client_credentials:

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials
&resource=https://api.yourapp.com
&scope=read:products write:products

Validando tokens de acceso JWT en tu API​

Los JWTs emitidos por Logto contienen reclamos que tu API puede usar para hacer cumplir la autorización.

Cuando tu API recibe una solicitud con un token de acceso emitido por Logto, debes:

  • Verificar la firma del token (usando los JWKs de Logto).
  • Confirmar que el token no ha expirado (reclamo exp).
  • Comprobar que el iss (emisor) coincide con tu endpoint de Logto.
  • Asegurarte de que el aud (audiencia) coincide con el identificador de recurso de API que registraste (por ejemplo, https://api.yourapp.com).
  • Separar el reclamo scope (separado por espacios) y comprobar los permisos requeridos.

Para guías paso a paso y específicas por lenguaje, consulta Cómo validar tokens de acceso.

Opcional: Manejar cambios de permisos de usuario​

info:

👷 Trabajo en progreso. 🚧

Mejores prácticas y consejos de seguridad​

  • Mantén los permisos orientados al negocio: Usa nombres claros que correspondan a acciones reales.
  • Mantén la expiración de los tokens corta: Reduce el riesgo si un token se filtra.
  • Limita los alcances concedidos: Solo otorga a los tokens los permisos que realmente necesitan.
  • Usa restricción de audiencia: Verifica siempre el reclamo aud para evitar usos indebidos.

Preguntas frecuentes​

¿Qué pasa si mi cliente no soporta el parámetro resource?​

Configura un recurso de API predeterminado en la Consola de Logto. Los tokens usarán esta audiencia por defecto cuando no se especifique el parámetro resource en la solicitud de token.

¿Por qué recibo 401 No autorizado de mi API?​

Verifica los siguientes problemas comunes:

  • Firma del token: Asegúrate de que tu backend obtiene los JWKs correctos de Logto
  • Expiración del token: Verifica que el token no haya expirado (reclamo exp)
  • Audiencia: Confirma que el reclamo aud coincide con el indicador de recurso de API registrado
  • Alcances requeridos: Verifica que el token contenga los permisos necesarios en el reclamo scope

¿Cómo pruebo sin un cliente completo?​

Utiliza un token de acceso personal para simular llamadas autenticadas. Esto te permite probar los endpoints de tu API sin implementar un flujo OAuth completo en tu aplicación cliente.

Lecturas adicionales​

Cómo validar tokens de acceso

RBAC en la práctica: Implementando autorización segura para tu aplicación

 Personalización de reclamos de tokens RFC 8707: Indicadores de recurso