Saltar al contenido principal

Invitar miembros a la organización

Como una aplicación multi-organización, un requisito común es invitar miembros a tu organización. En esta guía, te mostraremos los pasos y detalles técnicos para implementar esta función en tu aplicación.

Descripción general del flujo​

El proceso general se ilustra en el siguiente diagrama:

Crear roles de organización​

Antes de invitar miembros a tu organización, necesitas crear roles de organización. Consulta la Plantilla de organización para aprender más sobre roles y permisos de organización.

En esta guía, vamos a crear dos roles típicos de organización: admin y member.

El rol admin tiene acceso completo a todos los recursos de la organización, mientras que el rol member tiene acceso limitado. Por ejemplo, cada rol puede tener un conjunto de permisos como los siguientes:

  • Rol admin:
    • read:data - Acceso de lectura a todos los recursos de datos de la organización.
    • write:data - Acceso de escritura a todos los recursos de datos de la organización.
    • delete:data - Acceso de eliminación a todos los recursos de datos de la organización.
    • invite:member - Invitar miembros a la organización.
    • manage:member - Gestionar miembros en la organización.
    • delete:member - Eliminar miembros de la organización.
  • Rol member:
    • read:data - Acceso de lectura a todos los recursos de datos de la organización.
    • write:data - Acceso de escritura a todos los recursos de datos de la organización.
    • invite:member - Invitar miembros a la organización.

Esto se puede hacer fácilmente en la Consola de Logto. También puedes usar la Logto Management API para crear roles de organización de forma programática.

Configura tu conector de correo electrónico​

Dado que las invitaciones se envían por correo electrónico, asegúrate de que tu conector de correo electrónico esté correctamente configurado. Para enviar invitaciones, necesitas configurar un tipo de uso de plantilla de correo electrónico - OrganizationInvitation. También puedes incluir variables de organización (por ejemplo, nombre de la organización, logo) y del invitador (por ejemplo, correo electrónico del invitador, nombre) variables en el contenido, o personalizar plantillas multilingües según sea necesario.

Un ejemplo de plantilla de correo electrónico para el tipo de uso OrganizationInvitation se muestra a continuación:

{
  "subject": "Bienvenido a mi organización",
  "content": "<p>Únete a {{organization.name}} mediante este <a href=\"{{link}}\" target=\"_blank\">enlace</a>.</p>",
  "usageType": "OrganizationInvitation",
  "type": "text/html"
}

El marcador {{link}} en el contenido del correo será reemplazado por el enlace real de invitación al enviar el correo. En esta guía, supongamos que sería https://your-app.com/invitation/accept/{your-invitation-id}.

nota:

El "servicio de correo electrónico de Logto" integrado en Logto Cloud no admite actualmente el tipo de uso OrganizationInvitation. En su lugar, debes configurar tu propio conector de correo electrónico (por ejemplo, Sendgrid) y establecer la plantilla OrganizationInvitation.

Gestionar invitaciones con Logto Management API​

nota:

Si aún no has configurado la Logto Management API, consulta Interactuar con Management API para más detalles.

Para usuarios de Cloud y OSS v1.27.0+​

Ahora podemos usar la función de Enlace mágico (Token de un solo uso) para gestionar el flujo de invitación.

Simplemente llama a la Management API para crear un token de un solo uso y compón un enlace mágico de invitación con el token y el correo electrónico del invitado. Inserta el enlace en el marcador {{link}} de la plantilla de correo anterior y envía el correo al invitado. Puedes componer un enlace como https://your-app.com/landing-page?token={your-one-time-token}&email={invitee-email} en lugar de uno que contenga el ID de la invitación.

Este es el enfoque recomendado, ya que registrará automáticamente al invitado con el enlace mágico si aún no tiene una cuenta.

Consulta la página de Enlace mágico (Token de un solo uso) para más detalles.

Para usuarios de OSS v1.26.0 o anteriores​

Hemos proporcionado un conjunto de Management APIs relacionadas con invitaciones en la función de organizaciones. Con estas APIs, puedes:

  • POST /api/organization-invitations crear una invitación de organización con un rol de organización asignado.

  • POST /api/organization-invitations/{id}/message enviar la invitación de organización al invitado por correo electrónico. Nota: Esta API admite una propiedad link en el payload, puedes componer tu enlace de invitación basado en el ID de la invitación. Por ejemplo:

    {
      "link": "https://your-app.com/invitation/accept/{your-invitation-id}"
    }

    En consecuencia, necesitas implementar una página de destino cuando tu invitado navegue a través del enlace de invitación a tu aplicación.

  • GET /api/organization-invitations & GET /api/organization-invitations/{id} obtener todas tus invitaciones o una específica por ID. En tu página de destino, usa estas APIs para listar todas las invitaciones o los detalles de una invitación que un usuario ha recibido.

  • PUT /api/organization-invitations/{id}/status aceptar o rechazar la invitación actualizando el estado de la invitación. Usa esta API para gestionar la respuesta del usuario a la invitación.

Usa el control de acceso basado en roles (RBAC) de la organización para gestionar permisos de usuario​

Con las configuraciones anteriores, ahora puedes enviar invitaciones por correo electrónico, y los invitados pueden unirse a la organización con el rol asignado.

Los usuarios con diferentes roles de organización tendrán diferentes alcances (permisos) en sus tokens de organización. Por lo tanto, tanto tu aplicación cliente como los servicios backend deben comprobar estos alcances para determinar las funciones visibles y las acciones permitidas.

Gestionar actualizaciones de alcance en los tokens de organización​

nota:

Esta sección trata temas avanzados sobre la gestión de plantillas de organización y escenarios de autorización. Si no estás familiarizado con estos conceptos, por favor lee Autorización y Plantilla de organización primero.

Gestionar actualizaciones de alcance en los tokens de organización implica:

Revocar alcances existentes​

Por ejemplo, degradar un admin a un miembro no admin debería eliminar alcances del usuario. En tal caso, simplemente puedes limpiar el token de organización en caché y obtener uno nuevo con el token de actualización. Los alcances reducidos se reflejarán inmediatamente en el nuevo token de organización emitido.

Conceder nuevos alcances​

Esto se puede dividir en dos escenarios:

Conceder nuevos alcances ya definidos en tu sistema de autenticación​

Similar a revocar alcances, si el nuevo alcance concedido ya está registrado en el servidor de autenticación, simplemente puedes emitir un nuevo token de organización y los nuevos alcances se reflejarán inmediatamente.

Conceder nuevos alcances recién introducidos en tu sistema de autenticación​

En este caso, necesitas activar un proceso de re-inicio de sesión o re-consentimiento para actualizar el token de organización del usuario. Por ejemplo, llamando al método signIn en Logto SDK.

Implementar comprobación de permisos en tiempo real y actualizar el token de organización​

Logto proporciona Management API para obtener los permisos de usuario en tiempo real en la organización.

Luego puedes comparar los alcances en el token de organización del usuario con los permisos en tiempo real para determinar si el usuario ha sido promovido o degradado.

  • Si es degradado, simplemente puedes limpiar el token de organización en caché y el SDK emitirá automáticamente uno nuevo con los alcances actualizados.

    const { clearAccessToken } = useLogto();

    ...
    // Si los alcances en tiempo real obtenidos son menores que los alcances del token de organización
    await clearAccessToken();

    Esto no requiere un proceso de re-inicio de sesión o re-consentimiento. Los nuevos tokens de organización se emitirán automáticamente por el Logto SDK.

  • Si se introduce un nuevo alcance en tu sistema de autenticación, activa un proceso de re-inicio de sesión o re-consentimiento para actualizar el token de organización del usuario. Tomemos como ejemplo el SDK de React:

    const { clearAllTokens, signIn } = useLogto();

    ...
    // Si los alcances en tiempo real obtenidos tienen nuevos alcances asignados respecto a los del token de organización
    await clearAllTokens();
    signIn({
      redirectUri: '<your-sign-in-redirect-uri>',
      prompt: 'consent',
    });

    El código anterior activará una navegación a la pantalla de consentimiento y redirigirá automáticamente de vuelta a tu app, con los alcances actualizados en el token de organización del usuario.

Cómo implementamos la colaboración de usuarios dentro de una aplicación multi-tenant