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

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 asegurar 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 app, 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 refresh token o el flujo de client credentials.
  5. Valida los tokens de acceso en la interfaz o backend de tu app 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/app. 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/app 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 refresh token flow o el client credentials flow.

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 puedes usar una librería 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 a 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 los tokens de organización​

Los tokens de organización emitidos por Logto (JWTs) contienen reclamos que tu app/interfaz/backend 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 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.

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; concede 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 de tokens

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