Pular para o conteúdo principal

Convidar membros da organização

Como um aplicativo multi-organização, um requisito comum é convidar membros para sua organização. Neste guia, vamos mostrar os passos e detalhes técnicos para implementar esse recurso em seu aplicativo.

Visão geral do fluxo​

O processo geral é ilustrado no diagrama abaixo:

Criar papéis da organização​

Antes de convidar membros para sua organização, você precisa criar papéis da organização. Confira o Template de organização para saber mais sobre papéis e permissões da organização.

Neste guia, vamos criar dois papéis típicos de organização: admin e member.

O papel admin tem acesso total a todos os recursos da organização, enquanto o papel member tem acesso limitado. Por exemplo, cada papel pode ter um conjunto de permissões como segue:

  • Papel admin:
    • read:data - Acesso de leitura a todos os recursos de dados da organização.
    • write:data - Acesso de escrita a todos os recursos de dados da organização.
    • delete:data - Acesso de exclusão a todos os recursos de dados da organização.
    • invite:member - Convidar membros para a organização.
    • manage:member - Gerenciar membros na organização.
    • delete:member - Remover membros da organização.
  • Papel member:
    • read:data - Acesso de leitura a todos os recursos de dados da organização.
    • write:data - Acesso de escrita a todos os recursos de dados da organização.
    • invite:member - Convidar membros para a organização.

Isso pode ser feito facilmente no Logto Console. Você também pode usar o Logto Management API para criar papéis de organização programaticamente.

Configure seu conector de e-mail​

Como os convites são enviados por e-mail, certifique-se de que seu conector de e-mail está devidamente configurado. Para enviar convites, você precisa configurar um tipo de uso de template de e-mail - OrganizationInvitation. Você também pode incluir variáveis de organização (por exemplo, nome da organização, logo) e do convidador (por exemplo, e-mail do convidador, nome) variáveis no conteúdo, ou personalizar templates multilíngues conforme necessário.

Um exemplo de template de e-mail para o tipo de uso OrganizationInvitation é mostrado abaixo:

{
  "subject": "Bem-vindo à minha organização",
  "content": "<p>Junte-se à {{organization.name}} por este <a href=\"{{link}}\" target=\"_blank\">link</a>.</p>",
  "usageType": "OrganizationInvitation",
  "type": "text/html"
}

O placeholder {{link}} no conteúdo do e-mail será substituído pelo link real do convite ao enviar o e-mail. Neste guia, vamos supor que seria https://your-app.com/invitation/accept/{your-invitation-id}.

nota:

O "serviço de e-mail Logto" integrado do Logto Cloud não suporta o tipo de uso OrganizationInvitation no momento. Em vez disso, você precisa configurar seu conector de e-mail (por exemplo, Sendgrid) e configurar o template OrganizationInvitation.

Gerencie convites com Logto Management API​

nota:

Se você ainda não configurou o Logto Management API, confira Interaja com Management API para detalhes.

Para usuários Cloud e OSS v1.27.0+​

Agora podemos usar o recurso Magic link (Token de uso único) para gerenciar o fluxo de convite.

Basta chamar o Management API para criar um token de uso único e compor um magic link de convite com o token e o e-mail do convidado. Insira o link no placeholder {{link}} do template de e-mail acima e envie o e-mail para o convidado. Você pode compor um link como https://your-app.com/landing-page?token={your-one-time-token}&email={invitee-email} em vez de um contendo o ID do convite.

Esta é a abordagem recomendada, pois irá registrar automaticamente o convidado com o magic link caso ele ainda não tenha uma conta.

Confira a página Magic link (Token de uso único) para mais detalhes.

Para usuários OSS v1.26.0-​

Fornecemos um conjunto de APIs de convite relacionadas no recurso de organizações. Com essas APIs, você pode:

  • POST /api/organization-invitations criar um convite de organização com um papel de organização atribuído.

  • POST /api/organization-invitations/{id}/message enviar o convite da organização para o convidado por e-mail. Nota: Este payload da API suporta uma propriedade link, você pode compor seu link de convite com base no ID do convite. Por exemplo:

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

    Assim, você precisa implementar uma landing page quando seu convidado acessar o link de convite em seu aplicativo.

  • GET /api/organization-invitations & GET /api/organization-invitations/{id} obter todos os seus convites ou um específico pelo ID. Em sua landing page, use essas APIs para listar todos os convites ou detalhes de um convite que um usuário recebeu.

  • PUT /api/organization-invitations/{id}/status aceitar ou recusar o convite atualizando o status do convite. Use esta API para lidar com a resposta do usuário ao convite.

Use controle de acesso baseado em papel (RBAC) da organização para gerenciar permissões de usuários​

Com as configurações acima, agora você pode enviar convites por e-mail, e os convidados podem ingressar na organização com o papel atribuído.

Usuários com diferentes papéis de organização terão diferentes escopos (permissões) em seus tokens de organização. Assim, tanto seu app cliente quanto os serviços de backend devem verificar esses escopos para determinar recursos visíveis e ações permitidas.

Gerencie atualizações de escopo em tokens de organização​

nota:

Esta seção envolve tópicos avançados sobre gerenciamento de template de organização e cenários de autorização. Se você não está familiarizado com esses conceitos, leia Autorização e Template de organização primeiro.

Gerenciar atualizações de escopo em tokens de organização envolve:

Revogar escopos existentes​

Por exemplo, rebaixar um admin para membro não-admin deve remover escopos do usuário. Nesse caso, basta limpar o token de organização em cache e buscar um novo com o token de atualização. Os escopos reduzidos serão refletidos imediatamente no novo token de organização emitido.

Conceder novos escopos​

Isso pode ser dividido em dois cenários:

Conceder novos escopos já definidos em seu sistema de autenticação​

Semelhante à revogação de escopos, se o novo escopo concedido já estiver registrado no servidor de autenticação, basta emitir um novo token de organização, e os novos escopos serão refletidos imediatamente.

Conceder novos escopos recém-introduzidos em seu sistema de autenticação​

Neste caso, você precisa acionar um processo de novo login ou novo consentimento para atualizar o token de organização do usuário. Por exemplo, chamando o método signIn no Logto SDK.

Implemente verificação de permissão em tempo real e atualize o token de organização​

O Logto fornece Management API para buscar permissões de usuário em tempo real na organização.

Você pode então comparar os escopos no token de organização do usuário com as permissões em tempo real para determinar se o usuário foi promovido ou rebaixado.

  • Se rebaixado, basta limpar o token de organização em cache e o SDK emitirá automaticamente um novo com os escopos atualizados.

    const { clearAccessToken } = useLogto();

    ...
    // Se os escopos em tempo real buscados forem menores que os escopos do token de organização
    await clearAccessToken();

    Isso não requer um novo login ou processo de consentimento. Novos tokens de organização serão emitidos automaticamente pelo Logto SDK.

  • Se um novo escopo for introduzido em seu sistema de autenticação, acione um novo login ou processo de consentimento para atualizar o token de organização do usuário. Vamos usar o SDK React como exemplo:

    const { clearAllTokens, signIn } = useLogto();

    ...
    // Se os escopos em tempo real buscados tiverem escopos recém-atribuídos em relação aos escopos do token de organização
    await clearAllTokens();
    signIn({
      redirectUri: '<your-sign-in-redirect-uri>',
      prompt: 'consent',
    });

    O código acima acionará uma navegação para a tela de consentimento e redirecionará automaticamente de volta ao seu app, com escopos atualizados no token de organização do usuário.

Como implementamos colaboração de usuários em um app multi-inquilino