Saltar al contenido principal

Protege recursos de API a nivel de organización

Combina recursos de API con la plantilla de organización para restringir el acceso a las APIs y datos dentro de cada organización, asegurando el aislamiento a nivel de inquilino en tu SaaS.

¿Qué son los recursos de API a nivel de organización?​

Los recursos de API a nivel de organización son endpoints o servicios en tu aplicación que están limitados a una organización específica. Estas APIs aplican autorización y acceso basados en el contexto de la organización, asegurando que los usuarios o clientes solo accedan a datos y acciones relevantes para su organización.

Los casos de uso incluyen

  • APIs para gestionar miembros, roles o configuraciones de la organización (por ejemplo, /organizations/{organizationId}/members)
  • Paneles, analíticas o informes limitados a la organización
  • Endpoints de facturación, suscripción o auditoría vinculados a una organización
  • Cualquier API donde las acciones y los datos estén aislados por inquilino

Logto te permite asegurar estas APIs de organización usando OAuth 2.1 y control de acceso basado en roles (RBAC), mientras soporta arquitecturas SaaS multi-inquilino.

Estos permisos se gestionan a través de roles de organización definidos en la plantilla de organización. Cada organización utiliza la misma plantilla, asegurando un modelo de permisos consistente en todas las organizaciones.

Cómo funciona en Logto​

  • Los recursos de API y permisos se registran globalmente: Cada recurso de API se define con un indicador de recurso único (URI) y un conjunto de permisos (alcances) en Logto.
  • Roles a nivel de organización: Los roles de organización se definen en la plantilla de organización. Los permisos de recursos de API (alcances) se asignan a los roles de organización, que luego se asignan a usuarios o clientes dentro de cada organización.
  • Autorización consciente del contexto: Cuando un cliente solicita un token de acceso con un recurso de API y un organization_id, Logto emite un token que incluye tanto el contexto de la organización como la audiencia de la API. Los permisos (alcances) del token se determinan por los roles de organización del usuario para la organización especificada.
  • Separación de recursos globales: Los recursos de API pueden ser accedidos con o sin contexto de organización. El RBAC de organización solo se aplica si se incluye un organization_id en la solicitud. Para APIs compartidas entre todos los usuarios, consulta Protege recursos de API globales.
Recursos de API a nivel de organización RBAC

Resumen de la implementación​

  1. Registra tu recurso de API y define sus permisos (alcances) en Logto.
  2. Define roles de organización en la plantilla de organización y asigna los permisos de API relevantes.
  3. Asigna roles a usuarios o clientes dentro de cada organización.
  4. Solicita un token de acceso para la API con un organization_id para incluir el contexto de la organización.
  5. Valida los tokens de acceso en tu API, aplicando tanto el contexto de organización como los permisos.

Cómo aplica Logto el RBAC de organización​

  • Si solicitas un token de acceso sin un organization_id, solo se consideran los roles/permisos globales.
  • Si solicitas un token de acceso con un organization_id, Logto evalúa los roles de organización del usuario y sus permisos asociados para esa organización.
  • El JWT resultante contendrá tanto la audiencia de la API (reclamo aud) como el contexto de la organización (reclamo organization_id), con los alcances filtrados a los otorgados por los roles de organización del usuario.

Flujo de autorización: autenticando y asegurando APIs con contexto de organización​

El siguiente flujo muestra cómo un cliente (web, móvil o backend) obtiene y utiliza tokens de organización para acceder a recursos de API a nivel de organización.

Ten en cuenta que el flujo no incluye detalles exhaustivos sobre los parámetros o encabezados requeridos, sino que se centra 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 + contexto de organización.

Pasos de implementación​

Registra tu recurso 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 de organización​

  1. Ve a Consola → Plantilla de organización → Roles de organización.
  2. Crea roles de organización (por ejemplo, admin, member) y asigna permisos de API a cada rol.
  3. Asigna roles a usuarios o clientes dentro de cada organización. Si aún no son miembros, invítalos o agrégalos primero.

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

Obtén tokens de organización para recursos de API​

Tu cliente/app debe solicitar un token con ambos parámetros, resource y organization_id, para acceder a APIs a nivel de organización. Logto emite tokens de organización como JSON Web Tokens (JWTs). Puedes obtenerlos usando el flujo de token de actualización o el flujo de credenciales de cliente.

Flujo de token de actualización​

Casi todos los SDK oficiales de Logto admiten la obtención de tokens de organización usando el flujo de token de actualización de forma nativa. También se puede usar una biblioteca estándar de cliente OAuth 2.0 / OIDC para implementar este flujo.

Al inicializar el Logto SDK, añade el alcance urn:logto:scope:organizations y los permisos de organización deseados (alcances) al parámetro scopes.

Algunos SDK de Logto tienen un alcance predefinido para organizaciones, como UserScope.Organizations en los SDK de JavaScript.

nota:

Inspecciona el reclamo organizations en el token de ID (ID token) para obtener una lista de los IDs de las organizaciones a las que pertenece el usuario. Este reclamo enumera todas las organizaciones de las que el usuario es miembro, lo que facilita enumerar o cambiar de organización en tu aplicación.

Al llamar a getAccessToken(), especifica tanto el recurso de API (resource) como el ID de la organización (organizationId) para obtener un token de organización.

Para detalles sobre cada SDK, consulta Guías rápidas.

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 con permisos de recursos de API a nivel de organización. Haciendo una solicitud POST al endpoint /oidc/token de Logto con los parámetros de organización, puedes solicitar un token de organización usando tu client ID y secret.

Estos son los parámetros clave que debes incluir en la solicitud:

  • resource: El identificador del recurso de API (por ejemplo, https://api.yourapp.com/org).
  • organization_id: El ID de la organización para la que deseas el token.
  • scope: Los permisos de recursos de API a nivel de organización que deseas solicitar (por ejemplo, invite:member, manage:billing).

Aquí tienes un ejemplo no normativo de la solicitud de token usando el tipo de concesión de credenciales de cliente:

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/org
&organization_id=your-organization-id
&scope=invite:member manage:billing

Valida los tokens de organización​

Los tokens de organización emitidos por Logto (JWTs) contienen reclamos que tu API puede usar para aplicar el control de acceso a nivel de organización.

Cuando tu app reciba un token de organización, deberías:

  • Verificar la firma del token (usando los JWKs de Logto).
  • Confirmar que el token no esté expirado (reclamo exp).
  • Comprobar que el iss (emisor) coincida con tu endpoint de Logto.
  • Asegurarte de que el aud (audiencia) coincida con el identificador del recurso de API que registraste (por ejemplo, https://api.yourapp.com/org).
  • Validar el reclamo organization_id para asegurar que el token esté limitado a la organización correcta.
  • Separar el reclamo scope (separado por espacios) y comprobar los permisos requeridos.
  • Si la ruta de tu API incluye el ID de la organización (por ejemplo, /organizations/{organizationId}/members), asegúrate de que el reclamo organization_id coincida con el parámetro de la ruta.

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

Mejores prácticas y consejos de seguridad​

  • Valida siempre el contexto de la organización: No confíes solo en el token; revisa el reclamo organization_id en cada llamada a una API limitada por organización.
  • Usa restricciones de audiencia: Revisa siempre el reclamo aud para asegurar que el token sea para la organización prevista.
  • Mantén los permisos orientados al negocio: Usa nombres claros que correspondan a acciones reales; otorga solo lo necesario para cada rol de organización.
  • Separa permisos de API y no-API donde sea posible (pero ambos pueden estar en un solo rol).
  • Mantén los tiempos de vida de los tokens cortos: Reduce el riesgo si un token se filtra.
  • Revisa regularmente tu plantilla de organización: Actualiza roles y permisos a medida que tu producto evoluciona.

Preguntas frecuentes​

¿Qué pasa si no incluyo organization_id en mi solicitud de token?​

Solo se evaluarán los roles/permisos globales. No se aplicará el RBAC de organización.

¿Puedo mezclar permisos de organización y no organización en un solo rol?​

No, los permisos de organización (incluidos los permisos de API a nivel de organización) se definen por la plantilla de organización y no pueden mezclarse con permisos globales de API. Sin embargo, puedes crear roles que incluyan tanto permisos de organización como permisos de API a nivel de organización.

Más información​

Cómo validar tokens de acceso Personalización de reclamos de tokens

Caso de uso: Construir una aplicación SaaS multi-inquilino

 RFC 8707: Indicadores de recurso