Adicionar autenticação a um aplicativo da web tradicionalmente significa escolher entre construir seu próprio sistema (com todas as suas complexidades de segurança) ou integrar-se a um provedor centralizado como Auth0, Firebase ou serviços OAuth de grandes empresas de tecnologia.

Mas há uma terceira opção que está ganhando força: autenticação descentralizada. E com Autenticação Flowstavocê pode adicioná-lo ao seu aplicativo da web em menos de 30 minutos.

O que é Flowsta Auth?

Autenticação Flowsta é um sistema de autenticação descentralizado e de conhecimento zero baseado em Holochain. Ele fornece um botão “Entrar com Flowsta” semelhante aos provedores OAuth, mas com uma diferença crucial: verdadeira privacidade do usuário.

Principais recursos

• Arquitetura de Conhecimento Zero: os dados do usuário são criptografados e distribuídos em uma rede ponto a ponto. Mesmo o próprio Flowsta não pode acessar as informações do usuário – é criptograficamente impossível sem as chaves do usuário.
• Não é necessário back-end: diferentemente dos sistemas de autenticação tradicionais, você não precisa gerenciar bancos de dados de usuários, sessões ou senhas. Flowsta lida com a verificação de identidade por meio de provas criptográficas descentralizadas.
• Padrões DID W3C: Uso de identidades Flowsta Identificadores Descentralizados W3C (DIDs)tornando-os interoperáveis ​​com outros sistemas que suportam o padrão.
• Uma conta, vários sites: os usuários criam uma conta Flowsta e a utilizam em todos os sites integrados — sem formulários de registro repetidos, sem riscos de reutilização de senha.

Por que a autenticação descentralizada é importante

Em uma era de violações de dados e preocupações com a privacidade, a autenticação centralizada cria honeypots de dados do usuário. Sistemas descentralizados como o Flowsta distribuem dados por uma rede, eliminando pontos únicos de falha e tornando praticamente impossíveis violações de dados em massa.

Para desenvolvedores, isso significa:

• Responsabilidade reduzida: você não está armazenando dados confidenciais do usuário
• Conformidade com GDPR/Privacidade: Integrado por design
• Melhor experiência do usuário: Logon único sem rastreamento
• Custos mais baixos: Nenhuma infraestrutura de autenticação para manter

O que estamos construindo

Neste tutorial, integraremos o Flowsta Auth em uma aplicação web existente. Nosso exemplo usa um site de notícias Qwik/React chamado Os tempos AGORAmas os princípios se aplicam a qualquer estrutura JavaScript.

Bem:

1. Configure um aplicativo Flowsta e obtenha credenciais
2. Instalar e configurar o Flowsta Auth SDK
3. Crie fluxos de autenticação (login, tratamento de retorno de chamada)
4. Bloqueie o conteúdo por trás da autenticação
5. Exibir informações do usuário

No final, você terá um sistema de autenticação funcional com zero código de back-end.

Pré-requisitos

• Node.js 16+ e npm/yarn
• Um aplicativo da web existente (qualquer estrutura JS moderna funciona)
• Compreensão básica dos conceitos de fluxo OAuth
• 20-30 minutos

Etapa 1: registre seu aplicativo

Antes de escrever o código, registre seu aplicativo no Flowsta:

1. Visita dev.flowsta.com e crie uma conta
2. Clique “Criar novo aplicativo”
3. Dê ao seu aplicativo um nome descritivo (por exemplo, “Meu site de notícias”)
4. Copie seu ID do cliente (formato: flowsta_app_…)

Observação: Voltaremos aqui mais tarde para adicionar URIs de redirecionamento assim que os conhecermos.

Passo 2: Instale o SDK

Instale o SDK do Flowsta Auth:

npm install @flowsta/auth

Ou com Fio:

yarn add @flowsta/auth

O SDK é independente de estrutura e funciona com React, Vue, Svelte, Angular, Qwik ou Vanilla JavaScript.

Etapa 3: configurar o SDK

Crie um arquivo utilitário para inicializar e gerenciar a instância do SDK. Esse padrão singleton garante que não reinicializemos desnecessariamente:

// src/lib/flowsta.ts
import { FlowstaAuth } from '@flowsta/auth';

const CLIENT_ID = import.meta.env.VITE_FLOWSTA_CLIENT_ID || 'your_client_id_here';

let authInstance: FlowstaAuth | null = null;

export const getAuth = () => {
  if (typeof window === 'undefined') return null; // SSR safety
  
  if (!authInstance) {
    authInstance = new FlowstaAuth({
      clientId: CLIENT_ID,
      redirectUri: `${window.location.origin}/auth/callback`,
      scopes: ('openid', 'email', 'display_name')
    });
  }
  
  return authInstance;
};

Detalhamento da configuração:

• clientId: seu identificador de aplicativo de dev.flowsta.com
• redireccionamentoUri: para onde o Flowsta envia os utilizadores após a autenticação (construiremos esta rota a seguir)
• escopos: quais dados do usuário você está solicitando (openid é obrigatório, outros são opcionais)

Configuração de variável de ambiente:

Crie um arquivo .env:

VITE_FLOWSTA_CLIENT_ID=flowsta_app_your_actual_id_here

Etapa 4: crie a rota de retorno de chamada

Quando os usuários são autenticados, o Flowsta os redireciona de volta ao seu aplicativo com um código de autorização. Você precisa de uma rota para lidar com essa troca:

// src/routes/auth/callback/index.tsx (or your framework's equivalent)
import { component$, useVisibleTask$ } from '@builder.io/qwik';
import { useNavigate } from '@builder.io/qwik-city';
import { getAuth } from '~/lib/flowsta';

export default component$(() => {
  const nav = useNavigate();

  useVisibleTask$(async () => {
    const auth = getAuth();
    if (!auth) return;

    try {
      // Exchange authorization code for access token
      await auth.handleCallback();
      
      // Redirect to home or original destination
      window.location.href = "
    } catch (error) {
      console.error('Authentication failed:', error);
      // Handle error (show message, redirect to login, etc.)
    }
  });

  return (
    

      
Authenticating...
      
Please wait while we log you in.
    
  );
});

Para aplicativos Reactuse useEffect:

useEffect(() => {
  const auth = getAuth();
  if (!auth) return;

  auth.handleCallback()
    .then(() => window.location.href = "
    .catch(err => console.error('Auth failed:', err));
}, ());

Etapa 5: adicione o botão de login

Flowsta fornece designs de botões oficiais. Visite o Galeria de botões para baixar ativos SVG em vários estilos (escuro, claro, neutro) e formas (comprimido, retângulo).

Baixe seu estilo preferido e coloque-o em sua pasta pública (por exemplo, public/flowsta_signin.svg).

Crie um componente de botão:

// src/components/FlowstaButton.tsx
import { component$, $ } from '@builder.io/qwik';
import { getAuth } from '~/lib/flowsta';

export default component$(() => {
  const handleLogin = $(async () => {
    const auth = getAuth();
    if (auth) {
      await auth.login(); // Redirects to login.flowsta.com
    }
  });

  return (
          onClick$={handleLogin} 
      style={{ 
        background: 'none', 
        border: 'none', 
        cursor: 'pointer',
        padding: 0 
      }}
      aria-label="Sign in with Flowsta"
    >
              src=" 
        alt="Faça login com Flowsta"
        width="175"
        height="40"
      />
    
  );
});

Etapa 6: configurar URIs de redirecionamento

Agora que você conhece seu URL de retorno de chamada, adicione-o às configurações do aplicativo Flowsta:

1. Volte para dev.flowsta.com
2. Selecione seu aplicativo
3. Navegue até “URIs de redirecionamento permitidos”
4. Adicione ambos:
   • (desenvolvimento)
   • (produção)

Nota de segurança: o Flowsta redirecionará apenas para URIs nesta lista de permissões, evitando ataques de redirecionamento.

Etapa 7: verifique o status de autenticação

Para verificar se um usuário está logado:

import { getAuth } from '~/lib/flowsta';

const auth = getAuth();
const isAuthenticated = auth?.isAuthenticated() ?? false;

Para obter informações do usuário:

const user = auth?.getUser();
console.log(user?.displayName); // User's display name
console.log(user?.email);       // User's email (if scope granted)

Etapa 8: conteúdo do portal

Aqui está um exemplo prático: mostrar conteúdo de visualização para usuários anônimos, mas conteúdo completo para usuários autenticados.

import { component$, useStore, useVisibleTask$ } from '@builder.io/qwik';
import { getAuth } from '~/lib/flowsta';
import FlowstaButton from '~/components/FlowstaButton';

export default component$(() => {
  const store = useStore({ 
    isAuthenticated: false,
    userName: ''
  });

  // Check auth status on mount
  useVisibleTask$(() => {
    const auth = getAuth();
    if (auth?.isAuthenticated()) {
      store.isAuthenticated = true;
      store.userName = auth.getUser()?.displayName || 'User';
    }
  });

  return (
    

      {/* Always show first 4 articles */}
      

      {/* Gate remaining content */}
      {!store.isAuthenticated ? (
        
          textAlign: 'center', 
          padding: '3rem',
          background: '#f9fafb',
          borderRadius: '8px',
          margin: '2rem 0'
        }}>
          
Want to read more?
          
Sign in with Flowsta to access all articles
          
                      Free account • No credit card • 30 seconds to sign up
          
        
      ) : (
        
                      Welcome back, {store.userName}!
          
          
        >
      )}
    
  );
});

Etapa 9: adicionar funcionalidade de logout

Para desconectar usuários:

const handleLogout = $(async () => {
  const auth = getAuth();
  if (auth) {
    await auth.logout();
    window.location.reload(); // Refresh to update UI
  }
});

// In your component
Sign Out

Avançado: exibição do perfil do usuário

Crie um componente de perfil de usuário:

export const UserProfile = component$(() => {
  const store = useStore({
    user: null as any,
    loading: true
  });

  useVisibleTask$(() => {
    const auth = getAuth();
    if (auth?.isAuthenticated()) {
      store.user = auth.getUser();
    }
    store.loading = false;
  });

  if (store.loading) return 
Loading...
;
  if (!store.user) return null;

  return (
    

      
Profile
      
Name: {store.user.displayName}
      
Email: {store.user.email}
      
DID: {store.user.did.substring(0, 20)}...
    
  );
});

Usando assistentes de IA para acelerar o desenvolvimento

Embora este tutorial demonstre a integração manual, você pode acelerar o processo usando editores com tecnologia de IA, como Cursor ou GitHub Copilot.

Dica: Faça referência ao Documentação do Flowsta diretamente em seu assistente de IA, fornecendo o URL como contexto. Isso permite que a IA gere código específico da estrutura que segue as práticas recomendadas da Flowsta.

Por exemplo, no Cursor, você pode usar @ para dar à IA acesso à documentação completa enquanto ela gera código de integração para sua pilha de tecnologia específica.

Considerações de segurança

Armazenamento de tokens: o SDK armazena tokens com segurança no armazenamento do navegador. Nunca exponha tokens em códigos ou logs do lado do cliente.

• HTTPS obrigatório: na produção, seus URIs de redirecionamento devem usar HTTPS. Flowsta rejeitará conexões inseguras.
• Permissões de escopo: solicite apenas escopos que seu aplicativo precisa. Os usuários veem quais dados você está solicitando e podem negar o acesso.
• Gerenciamento de sessão: implemente tempos limite de sessão adequados e atualize o tratamento de tokens para sessões de longa duração.

Testando sua integração

Teste de desenvolvimento:

npm run dev # Inicia seu servidor de desenvolvimento

1. Navegue até seu aplicativo
2. Clique no botão de login do Flowsta
3. Crie uma conta de teste ou faça login em login.flowsta.com
4. Verifique se você foi redirecionado de volta e autenticado

Problemas comuns:

• “Incompatibilidade de URI de redirecionamento”: certifique-se de que seu URL de retorno de chamada corresponda exatamente ao que está registrado em dev.flowsta.com
• “ID de cliente inválido”: Verifique novamente se sua variável de ambiente está carregada corretamente
• O retorno de chamada não é acionado: verifique se o caminho da rota corresponde à configuração do redirectUri

Implantação de produção

Antes de implantar:

1. Adicione o URI de redirecionamento de produção a dev.flowsta.com
2. Defina VITE_FLOWSTA_CLIENT_ID no ambiente de produção
3. Teste o fluxo de autenticação na preparação
4. Verifique se o HTTPS está ativado
5. Testar funcionalidade de logout
6. Monitore logs de erros para falhas de autenticação

Considerações de desempenho

O Flowsta SDK é leve (~15 KB compactado) e não afeta significativamente o carregamento da página. Para desempenho ideal:

• Carga preguiçosa a verificação de autenticação nas rotas que precisam dela
• Cache status de autenticação no gerenciamento de estado (Redux, Zustand, etc.)
• Pré-busca o pacote SDK em páginas com botões de login

Comparação com autenticação tradicional

OAuth tradicional (Auth0, Firebase):

• Centralizado (ponto único de falha)
• A empresa tem acesso aos dados do usuário
• Caro
• Preocupações com privacidade

Autenticação Flowsta:

• Descentralizado (sem ponto único de falha)
• Conhecimento zero (matematicamente privado)
• Nível gratuito generoso e acessível
• Os usuários possuem sua identidade

O que vem a seguir?

Agora você tem um sistema de autenticação descentralizado funcionando. Considere estas melhorias:

• Controle de acesso baseado em função: Armazene funções de usuário em seu banco de dados, codificadas por seu Flowsta DID
• Personalização do perfil: permite que os usuários atualizem preferências e configurações
• Divulgação progressiva: Solicite escopos adicionais somente quando necessário
• Sincronização de vários dispositivos: Flowsta lida com a sincronização de sessões entre dispositivos automaticamente

Assista à Integração em Ação

Quer ver esse processo de integração em tempo real? Assista a este vídeo passo a passo que mostra como o Flowsta Auth foi adicionado ao The NOW Times usando desenvolvimento assistido por IA:

Este vídeo demonstra a integração usando o Cursor AI, mostrando como os conceitos deste tutorial podem ser acelerados com ferramentas de desenvolvimento baseadas em IA.

Saber mais

Conclusão

A autenticação descentralizada representa uma mudança de paradigma na forma como lidamos com a identidade digital. Com o Flowsta Auth, você pode oferecer aos usuários privacidade verdadeira sem sacrificar a experiência do desenvolvedor ou a conveniência do usuário.

O processo de integração é simples, comparável a qualquer provedor OAuth, mas os benefícios são substanciais: nenhuma infraestrutura de autenticação de back-end, nenhuma responsabilidade pelos dados do usuário, conformidade de privacidade integrada e uma melhor experiência do usuário.

À medida que a web avança em direção à descentralização e à soberania do usuário, ferramentas como o Flowsta Auth fornecem uma ponte prática entre as expectativas de UX de hoje e os padrões de privacidade de amanhã.

Pronto para começar? Crie seu aplicativo Flowsta gratuito e integre a autenticação que prioriza a privacidade em seu próximo projeto.

Tem dúvidas sobre a integração do Flowsta Auth? Junte-se ao Comunidade Flowsta Discord ou confira o documentação.