Ao longo dos anos desenvolvendo em Java, muitos de nós, tanto iniciantes quanto experientes, já enfrentamos dificuldades com a autenticação e autorização. Seja mergulhando nas complexas configurações do Spring Security, lutando com cadeias de filtros, adaptando o Shiro para projetos de front-end/back-end separados, ou até mesmo implementando funcionalidades como "expulsar usuário" manualmente com Redis, lidando com expiração de sessões e potenciais problemas de concorrência.

Muitos desenvolvedores dedicam um tempo precioso em código de autenticação repetitivo e complicado, em vez de focar na lógica de negócios. Projetos simples de gerenciamento de back-end podem acabar com centenas de linhas de configuração de permissão, e interfaces de microsserviços exigem depuração constante de CORS e renovação de tokens.

O Sa-Token surge como uma solução para esse problema. Ele foi projetado para ser um parceiro de desenvolvimento que entende as suas necessidades, eliminando a complexidade e a burocracia. Este guia irá introduzir o Sa-Token, compará-lo com outras abordagens e fornecer um tutorial prático para que você possa começar a usá-lo imediatamente, deixando para trás o estresse da autenticação.

1. Comparativo: Sa-Token vs. Outros Frameworks de Autenticação

Ao pensar em frameworks de autenticação Java, Spring Security e Apache Shiro são frequentemente os primeiros que vêm à mente. São soluções robustas e estabelecidas, com vastos ecossistemas, ideais para muitos projetos tradicionais. No entanto, eles foram concebidos em uma era dominada pelo JSP, e seus conceitos de design podem não se alinhar perfeitamente com as arquiteturas modernas de front-end/back-end separados e microsserviços.

Spring Security

O Spring Security é inegavelmente poderoso, oferecendo controle de acesso granular, suporte robusto a OAuth2.0 e integração perfeita com o ecossistema Spring. Contudo, seu poder vem com uma curva de aprendizado acentuada. Para iniciantes, entender conceitos como cadeias de filtros, gerenciadores de autenticação e decisores de autorização pode levar semanas. Mesmo desenvolvedores experientes podem precisar de uma quantidade significativa de configuração e reescrita de código para adaptá-lo a cenários de front-end/back-end separados.

Apache Shiro

O Shiro é consideravelmente mais simples que o Spring Security, com funcionalidades centrais claras de autenticação, autorização e gerenciamento de sessões, tornando sua curva de aprendizado mais acessível. Ele atende bem a muitos projetos de pequeno e médio porte. No entanto, sua adaptabilidade em cenários de front-end/back-end separados e microsserviços é limitada. Ele não possui suporte nativo a Token, exigindo integração manual de JWT. Soluções de sessão distribuída não são prontas para uso, necessitando de integração com Redis. Funcionalidades comuns como "expulsar usuário" ou "login simultâneo limitado por dispositivo" exigem extensões manuais, aumentando a complexidade do código e o potencial de problemas de compatibilidade.

Sa-Token

O Sa-Token preenche as lacunas deixadas por esses frameworks, mantendo suas vantagens e adaptando-se melhor aos cenários de desenvolvimento atuais. Ele se concentra em ser "pequeno e refinado", com todas as suas funcionalidades voltadas para resolver os pontos problemáticos dos desenvolvedores. Não introduz conceitos complexos nem funcionalidades redundantes, focando na simplicidade, eficiência e facilidade de uso da autenticação.

A tabela abaixo resume as diferenças práticas:

• Curva de Aprendizado: Spring Security (Muito Alta) > Apache Shiro (Média) > Sa-Token (Muito Baixa). O Sa-Token permite inicialização sem configuração, necessitando apenas de algumas linhas de código para começar.
• Adaptação a Front-end/Back-end Separados: Sa-Token (Suporte Nativo) > Spring Security (Requer Configuração Extensiva) > Apache Shiro (Requer Integração JWT Manual). O Sa-Token suporta nativamente vários cenários de front-end/back-end separados, como apps, mini-programas e SPAs, sem a necessidade de lidar manualmente com CORS ou passagem de token.
• Adaptação a Microsserviços: Sa-Token (Pronto para Uso) > Spring Security (Requer Integração com Spring Cloud Security) > Apache Shiro (Requer Extensões Significativas). O Sa-Token oferece soluções prontas para sessões distribuídas, autenticação unificada em gateways e autenticação de chamadas RPC, facilitando a interoperabilidade entre sistemas.
• Funcionalidades Comuns: Sa-Token (Pronto para Uso) > Spring Security (Requer Configuração/Extensão) > Apache Shiro (Requer Extensão). Funções como login, controle de permissão, expulsão de usuário, bloqueio de conta, renovação de token, login simultâneo limitado e single sign-on (SSO) são integradas, exigindo apenas uma linha de código.
• Extensibilidade: Spring Security (Muito Alta) > Sa-Token (Alta) > Apache Shiro (Média). A maioria dos componentes do Sa-Token oferece interfaces de extensão, permitindo personalização para atender a requisitos de projetos de grande escala.

O Sa-Token não busca substituir o Spring Security ou Shiro, mas oferece uma alternativa mais leve e focada para a maioria dos desenvolvedores que não necessitam da complexidade total desses frameworks. Muitos desenvolvedores relatam que, após usar o Sa-Token, a autenticação se tornou surpreendentemente simples, com tarefas que antes levavam um dia inteiro agora sendo resolvidas com uma única linha de código.

2. Visão Geral do Sa-Token: Simplicidade e Elegância em Autenticação

O Sa-Token é definido como um framework de autenticação de permissões Java, de código aberto, gratuito e leve, focado em simplificar e otimizar o processo de login, controle de permissões e gerenciamento de sessões. Sua essência reside em entender as necessidades do desenvolvedor: evitar configurações complexas, oferecer APIs intuitivas e incluir funcionalidades comuns prontas para uso.

Seguindo o princípio de implementar apenas o que é necessário para as demandas do negócio, o Sa-Token evita conceitos obscuros e foca em resolver problemas práticos:

• Autenticação de Login: StpUtil.setLoginId(userId) para marcar o login e StpUtil.checkLogin() para verificar, sem necessidade de configurar Realms ou filtros globais.
• Controle de Permissões: @SaCheckPermission("user:add") para validação de permissões de API e StpUtil.hasRole("super-admin") para verificação de roles, eliminando a necessidade de consultas manuais a tabelas de permissão.
• Expulsão de Usuário: StpUtil.logoutByLoginId(userId) para desconectar um usuário em todas as suas sessões, sem manipulação manual de Redis ou sessões.
• Sessões Distribuídas: Integração simplificada com Redis para persistência de sessão em ambientes distribuídos, garantindo que os dados não sejam perdidos ao reiniciar o projeto.
• Login Simultâneo Limitado por Dispositivo: StpUtil.setLoginId(userId, "deviceType") para gerenciar logins por dispositivo, permitindo expulsar sessões antigas no mesmo dispositivo.

Além disso, o Sa-Token suporta OAuth2.0, SSO, criptografia de senha, troca temporária de identidade e renovação automática de token, cobrindo a maioria dos cenários de autenticação. Seu tamanho reduzido e poucas dependências o tornam ideal para qualquer tipo de projeto, de pequenas aplicações a microsserviços complexos.

A documentação do Sa-Token é abrangente, com exemplos claros e soluções para problemas comuns. A comunidade é ativa, e o autor mantém o framework atualizado. Em sete anos, o Sa-Token evoluiu de uma pequena ferramenta para um dos frameworks de autenticação leves mais populares na China, graças à confiança e ao feedback dos desenvolvedores.

3. Introdução Prática ao Sa-Token

Este tutorial guiará você através da integração e uso básico do Sa-Token em um projeto Spring Boot 2.x/3.x.

Passo 1: Adicionando a Dependência

Integre o Sa-Token ao seu projeto Spring Boot adicionando a seguinte dependência ao seu pom.xml:

<dependency>
   <groupId>cn.dev33</groupId>
   <artifactId>sa-token-spring-boot-starter</artifactId>
   <version>1.44.0</version> <!-- Verifique a versão mais recente -->
</dependency>
   

Após adicionar a dependência e atualizar o Maven, o Sa-Token estará pronto para uso com configuração zero para suas funcionalidades principais.

Para projetos que requerem sessões distribuídas (como microsserviços), integre também o Redis. Para projetos monolíticos, o Sa-Token usará armazenamento em memória.

Passo 2: Utilizando as APIs Principais (Login e Permissões)

Login e Verificação

As operações de autenticação são simplificadas através da classe StpUtil.

import cn.dev33.satoken.stp.StpUtil;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class LoginController {

   @GetMapping("/login")
   public String login(String username, String password) {
       // Simula a validação de usuário e senha
       if ("admin".equals(username) && "123456".equals(password)) {
           // Marca o login com o ID do usuário
           StpUtil.setLoginId(10001); 
           return "Login successful!";
       }
       return "Invalid username or password!";
   }

   @GetMapping("/info")
   public String getInfo() {
       // Verifica se o usuário está logado; lança exceção se não estiver
       StpUtil.checkLogin();
       // Obtém o ID do usuário logado
       Object loginId = StpUtil.getLoginId();
       return "User info for ID: " + loginId;
   }

   @GetMapping("/logout")
   public String logout() {
       // Desloga o usuário
       StpUtil.logout();
       return "Logged out successfully!";
   }
}
   

Ao chamar StpUtil.setLoginId(), o Sa-Token gera um token e o armazena. Ao acessar endpoints protegidos, ele automaticamente lê e valida o token.

Controle de Permissões com Anotações

Para implementar controle de acesso baseado em roles e permissões, implemente a interface StpInterface:

import cn.dev33.satoken.stp.StpInterface;
import org.springframework.stereotype.Component;
import java.util.ArrayList;
import java.util.List;

@Component
public class StpInterfaceImpl implements StpInterface {

   @Override
   public List<string> getRoleList(Object loginId, String loginType) {
       // Lógica para obter roles do usuário (ex: consulta ao banco de dados)
       List<String> roleList = new ArrayList<>();
       if (loginId.equals(10001)) {
           roleList.add("super-admin");
       }
       return roleList;
   }

   @Override
   public List<string> getPermissionList(Object loginId, String loginType) {
       // Lógica para obter permissões do usuário
       List<String> permissionList = new ArrayList<>();
       if (loginId.equals(10001)) {
           permissionList.add("user:add");
           permissionList.add("user:delete");
       }
       return permissionList;
   }
}
   </string></string>

Utilize as anotações @SaCheckRole e @SaCheckPermission nos seus controllers:

import cn.dev33.satoken.annotation.SaCheckPermission;
import cn.dev33.satoken.annotation.SaCheckRole;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class PermissionController {

   @SaCheckRole("super-admin")
   @GetMapping("/admin/manager")
   public String adminManager() {
       return "Admin manager access granted.";
   }

   @SaCheckPermission("user:delete")
   @GetMapping("/user/delete")
   public String deleteUser() {
       return "User deletion permission granted.";
   }
}
   

Passo 3: Funcionalidades Adicionais Comuns

Expulsar Usuário

// Expulsa o usuário com ID 10002 de todas as suas sessões
StpUtil.logoutByLoginId(10002);
   

Login Simultâneo Limitado por Dispositivo

// Login com identificador de dispositivo "WECHAT"
StpUtil.setLoginId(10001, "WECHAT"); 
// Expulsar sessões antigas no dispositivo "WECHAT" para o usuário 10001
StpUtil.logoutByLoginId(10001, "WECHAT");
   

Renovação Automática de Token

Configure no application.yml:

sa-token:
 timeout: 86400 # Duração do token em segundos (padrão 24h)
 active-timeout: 3600 # Duração de atividade do token em segundos (padrão 1h)
   

O Sa-Token oferece uma abordagem simplificada para autenticação, permitindo que os desenvolvedores se concentrem na lógica de negócios. Sua facilidade de uso e conjunto robusto de funcionalidades o tornam uma excelente escolha para diversos tipos de projetos Java.