Saltar al contenido principal

Protege los permisos de organización (no API)

Utiliza la plantilla de organización para gestionar y aplicar roles y permisos a nivel de organización en Logto, controlando el acceso a funciones y flujos dentro de la aplicación en el contexto de una organización.

¿Qué son los permisos de organización (no API)?​

Los permisos de organización (no API) controlan lo que los usuarios pueden hacer dentro del contexto de una organización, pero no se aplican a nivel de API. En cambio, gobiernan el acceso a funciones de la aplicación, elementos de la interfaz, flujos de trabajo o acciones de negocio, en lugar de APIs de backend.

Los casos de uso incluyen

  • Invitar o gestionar miembros dentro de una organización
  • Asignar o cambiar roles de organización
  • Gestionar la facturación, configuraciones o funciones administrativas de una organización
  • Acceso a paneles, analíticas o herramientas internas que no tienen endpoints de API

Logto te permite proteger estos permisos de organización usando OAuth 2.1 y control de acceso basado en roles (RBAC), mientras soporta arquitecturas SaaS multi-tenant.

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​

  • RBAC a nivel de organización: Los roles y permisos se definen en la plantilla de organización. Cuando un usuario se une a una organización, se le asignan uno o más roles, otorgando permisos específicos.
  • Aplicación no API: Los permisos se verifican y aplican en la interfaz de tu aplicación, flujo de trabajo o lógica de backend, no necesariamente por un gateway de API.
  • Separación de la protección de API: Los permisos de organización (no API) son distintos de los permisos de recursos de API. Puedes combinar ambos para escenarios avanzados.
Permisos de organización RBAC

Resumen de la implementación​

  1. Define los permisos de organización en Logto bajo la plantilla de organización.
  2. Crea roles de organización que agrupen los permisos necesarios para tus acciones específicas de organización.
  3. Asigna roles a usuarios o clientes dentro de cada organización.
  4. Obtén un token de organización (JWT) para la organización actual usando el flujo de refresh token o client credentials.
  5. Valida los tokens de acceso en la interfaz o backend de tu aplicación para aplicar los permisos de organización.

Flujo de autorización: autenticando y asegurando permisos de organización​

El siguiente flujo muestra cómo un cliente (web, móvil o backend) obtiene y utiliza tokens de organización para la aplicación de permisos no API.

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/aplicación. M2M = servicio de backend o script usando client credentials + contexto de organización.

Pasos de implementación​

Registra permisos de organización​

  1. Ve a Consola → Plantilla de organización → Permisos de organización.
  2. Define los permisos de organización que necesitas (por ejemplo, invite:member, manage:billing, view:analytics).

Para ver los pasos completos de configuración, consulta Definir permisos de organización.

Configura roles de organización​

  1. Ve a Consola → Plantilla de organización → Roles de organización.
  2. Crea roles que agrupen los permisos de organización que definiste antes (por ejemplo, admin, member, billing).
  3. Asigna estos roles a usuarios o clientes dentro de cada organización.

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

Obtén tokens de organización (no API)​

Tu cliente/aplicación debe obtener un token de organización (no API) para acceder a los permisos de organización. Logto emite tokens de organización como JSON Web Tokens (JWTs). Puedes obtenerlos usando el flujo de refresh token o el flujo de client credentials.

Flujo de refresh token​

Casi todos los SDK oficiales de Logto admiten la obtención de tokens de organización usando el flujo de refresh token 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 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.

Utiliza getOrganizationToken o un método similar (como getAccessToken con un ID de organización) para solicitar un token de organización para una organización específica.

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

Flujo de client credentials​

Para escenarios máquina a máquina (M2M), puedes usar el flujo de client credentials para obtener un token de acceso para permisos de organización. Haciendo una solicitud POST al endpoint /oidc/token de Logto con 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:

  • organization_id: El ID de la organización para la que deseas el token.
  • scope: Los permisos 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 grant 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
&organization_id=your-organization-id
&scope=invite:member manage:billing

Valida tokens de organización​

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

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

  • 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 organización formateado (por ejemplo, urn:logto:organization:{organization_id}).
  • 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.

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​

  • Nunca confíes solo en la aplicación en la interfaz: Siempre valida los permisos en el backend para acciones críticas.
  • Usa restricciones de audiencia: Comprueba siempre el reclamo aud para asegurarte de 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).
  • Revisa la plantilla de organización regularmente a medida que evoluciona tu producto.

Preguntas frecuentes​

¿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.

¿Dónde debo aplicar los permisos no API?​

Verifica los permisos no API tanto en la interfaz (para limitar funciones) como en la lógica del servidor para acciones sensibles.

Más información​

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

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