Saltar al contenido principal

Protege los recursos de API a nivel de organización

Combina los 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 asociados 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.

Casos de uso incluyen

  • APIs para gestionar miembros, roles o configuraciones de la organización (por ejemplo, /organizations/{organizationId}/members)
  • Paneles, analíticas o reportes asociados 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 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 Proteger 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 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 (aud claim) como el contexto de la organización (organization_id claim), 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 los pasos completos de configuración, consulta Definir recursos de API con permisos.

Configura los 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 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 puedes usar una biblioteca estándar de cliente OAuth 2.0 / OIDC para implementar este flujo.

Al inicializar el SDK de Logto, añade 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 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 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 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 (exp claim).
  • 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é asociado a la organización correcta.
  • Separar el reclamo scope (separado por espacios) y comprobar los permisos requeridos.
  • Si tu ruta de 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.

Optional: Handle user permission change​

User permissions can change at any time. Because Logto issues JWTs for RBAC, permission updates only appear in newly issued tokens, and never modify existing JWTs.

Scope subset rule:

An access token can only include scopes that were requested in the original OAuth authorization flow. Even if a user gains new permissions, the token issued later can only contain a subset of the originally requested scopes. To access newly granted scopes that were not part of the initial request, the client must run a new authorization flow.

Downscoped permissions​

When a user loses permissions:

  • Newly issued tokens immediately reflect the reduced scopes.
  • Existing JWTs keep the old scopes until they expire.
  • Your API should always validate scopes and rely on short token lifetimes.

If you need faster reactions, implement your own signal that tells clients to refresh their tokens.

Enlarged permissions​

For organization tokens, when a user gains permissions, enlarged permissions will show up on the next issuance (refresh or token request). A new token is still required, but no full re-auth is needed unless the new scopes exceed the original request set.

Recommendations​

  • Validate scopes in your API on every call.
  • Keep token expiration short.
  • Add optional notifications if you need immediate permission-change propagation.

Mejores prácticas y consejos de seguridad​

  • Valida siempre el contexto de organización: No confíes solo en el token; verifica el reclamo organization_id en cada llamada a una API asociada a organización.
  • Usa restricciones de audiencia: Comprueba siempre el reclamo aud para asegurar que el token es 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 cuando 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 de API globales. 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 token

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

 RFC 8707: Indicadores de recurso