Sa-Token入门教程：轻松掌握权限认证与会话管理

概述

Sa-Token 是一个简单易用的权限认证与会话管理框架，适用于 Java 项目。它能够帮助开发者快速实现用户的身份认证、权限控制以及会话管理功能，并支持多种认证方式和分布式环境下的会话共享。Sa-Token 功能强大且易于集成，适用于各类 Java 应用程序，如 Web 应用、RPC 服务、微服务等。

Sa-Token简介

Sa-Token是什么

Sa-Token 是一个简单易用的权限认证与会话管理框架，适用于 Java 项目。它能够帮助开发者快速实现用户的身份认证、权限控制以及会话管理功能。Sa-Token 功能强大且易于集成，适用于各类 Java 应用程序，如 Web 应用、RPC 服务、微服务等。

Sa-Token的主要功能

1. 用户认证：Sa-Token 支持多种认证方式，包括用户名密码认证、JWT 认证等。
   2..* 权限控制：能够为用户和角色定义权限，并在请求拦截时进行权限校验。
2. 会话管理：支持会话的创建、存储、检索、更新和销毁，同时具有多种会话安全性设置。
3. 登录状态维护：通过单点登录（SSO）和多点登录（MMS）功能，保证用户在不同应用间的登录状态一致性。
4. 黑白名单：提供黑白名单功能，可以对特定 IP 或 URL 进行访问控制。
5. 分布式支持：支持分布式环境下的会话共享和同步，确保用户在多台服务器之间的登录状态一致性。
6. 自定义扩展：Sa-Token 提供丰富的扩展点，允许用户自定义各种权限校验逻辑。

Sa-Token的应用场景

1. Web 应用：在 Web 应用中，Sa-Token 可以用于用户登录、权限控制和会话管理。
2. 微服务架构：在微服务架构中，Sa-Token 可以用于服务间的认证与权限控制。
3. 移动应用后端：在移动应用的后端服务中，Sa-Token 可以用于处理用户的登录和权限管理。
4. API 服务：对于提供 API 接口的系统，Sa-Token 可以用于确保 API 的访问安全和权限控制。
5. 分布式系统：在分布式系统中，Sa-Token 的分布式支持功能确保用户在多个节点间的登录状态一致性。

安装与环境搭建

如何安装Sa-Token

1. 使用 Maven 添加依赖：

<dependency>
    <groupId>cn.fxp</groupId>
    <artifactId>sa-token</artifactId>
    <version>1.13.7</version>
</dependency>

1. 使用 Gradle 添加依赖：

implementation 'cn.fxp:sa-token:1.13.7'

1. 下载 Sa-Token JAR 文件：
   • 访问 Sa-Token 官方 GitHub 仓库下载 Sa-Token JAR 文件。
   • 将下载的 JAR 文件添加到项目的 classpath 中。

项目环境配置

为了能够正常使用 Sa-Token，需要配置一些基本的环境变量和配置项。以下是一个典型的配置示例：

1. 创建 Sa-Token 配置类：

import cn.fxp.sdk.starter.SaTokenAutoConfiguration;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SaTokenConfig {

    @Bean
    public SaTokenAutoConfiguration saTokenConfig() {
        return new SaTokenAutoConfiguration();
    }
}

1. 在 Spring Boot 应用程序中，可以通过 application.properties 或 application.yml 文件来配置 Sa-Token 相关的属性：

# Sa-Token 配置
sa-token.jwt.secret=your-secret-key
sa-token.session.timeout=3600000
sa-token.session.max-size=1000

快速入门示例

创建一个简单的 Spring Boot 应用程序，并集成 Sa-Token：

1. 创建一个 Spring Boot 项目，确保项目中已添加了前面提到的 Sa-Token 依赖。

2. 创建一个简单的控制器，用于测试 Sa-Token 的功能：

import cn.fxp.sdk.starter.SaTokenAutoConfiguration;
import cn.fxp.sdk.starter.SaTokenConfig;
import cn.fxp.sdk.starter.SaTokenManager;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class SaTokenController {

    @Autowired
    private SaTokenManager saTokenManager;

    @GetMapping("/login")
    public String login() {
        // 模拟用户登录
        String token = saTokenManager.createToken("user1");
        return "Login success. Token: " + token;
    }

    @GetMapping("/check")
    public String check() {
        // 检查 token 是否有效
        boolean valid = saTokenManager.validToken("user1");
        return "Token is " + (valid ? "valid" : "invalid");
    }
}

1. 运行 Spring Boot 应用程序，访问 http://localhost:8080/api/login 和 http://localhost:8080/api/check，验证 Sa-Token 的基本功能。

用户认证与授权

用户认证流程

用户认证是 Sa-Token 的核心功能之一。以下是一个简单的用户认证流程示例：

1. 用户提交登录请求：用户通过客户端提交用户名和密码。
2. 服务器端认证：服务器接收到请求后，调用 Sa-Token 提供的认证方法进行用户身份验证。
3. 生成认证令牌：认证成功后，服务器生成一个认证令牌（Token），并返回给客户端。
4. 客户端保存令牌：客户端保存返回的 Token，后续请求时需要携带该 Token。
5. 后续请求验证：在后续的请求中，服务器会验证 Token 的有效性，从而确认用户身份。

示例代码

import cn.fxp.sdk.starter.SaTokenManager;

public class AuthService {

    @Autowired
    private SaTokenManager saTokenManager;

    public String login(String username, String password) {
        // 用户认证
        if ("user1".equals(username) && "password1".equals(password)) {
            // 创建会话
            String token = saTokenManager.createToken(username);
            return token;
        }
        return null;
    }
}

权限授权方法

Sa-Token 支持多种权限授权方法，以下是一个简单的权限控制示例：

1. 定义权限规则：在 Sa-Token 配置中定义权限规则，例如：

# 定义权限规则
sa-token.permission.rule=admin:1,editor:2,viewer:3

1. 设置用户权限：为用户设置权限，例如：

import cn.fxp.sdk.starter.SaTokenManager;

public class AuthService {

    @Autowired
    private SaTokenManager saTokenManager;

    public void login(String username, String password) {
        // 用户认证
        if ("user1".equals(username) && "password1".equals(password)) {
            // 创建会话并设置角色
            String token = saTokenManager.createToken(username);
            saTokenManager.setRole(username, "admin");
            return token;
        }
        return null;
    }
}

1. 检查权限：在请求拦截时检查用户权限，例如：

import cn.fxp.sdk.starter.SaTokenManager;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class SaTokenController {

    @Autowired
    private SaTokenManager saTokenManager;

    @GetMapping("/admin")
    public String admin() {
        // 检查权限
        if (!saTokenManager.validRole("admin")) {
            return "Access denied";
        }
        return "Admin page";
    }
}

常见问题解答

Q: Token 过期后如何自动刷新？

A: Sa-Token 提供了自动刷新 Token 的功能，通过配置 sa-token.jwt.autoRefresh 属性，可以设置 Token 自动刷新的策略。

Q: 如何实现多点登录？

A: Sa-Token 提供了多点登录的支持，可以通过配置 sa-token.mms 相关属性来实现多点登录功能。

Q: 如何处理用户注销？

A: Sa-Token 提供了注销功能，可以通过调用 saTokenManager.clearToken 方法来注销用户。

会话管理

会话的基本概念

会话管理是 Sa-Token 的另一大核心功能。会话（Session）用于存储用户在服务器端的登录状态信息。Sa-Token 支持多种会话类型，包括内存会话、Redis 会话等。

内存会话

内存会话是将用户登录状态信息存储在服务器的内存中，适合于中小型应用，具有读写速度快、配置简单的特点。

Redis 会话

Redis 会话是将用户登录状态信息存储在 Redis 中，适合于分布式环境中的应用，具有高性能和高可用的特点。

会话的创建与管理

在 Sa-Token 中，可以通过以下步骤创建和管理会话：

1. 创建会话：

import cn.fxp.sdk.starter.SaTokenManager;

public class AuthService {

    @Autowired
    private SaTokenManager saTokenManager;

    public void login() {
        // 创建会话
        String token = saTokenManager.createToken("user1");
        // 设置角色
        saTokenManager.setRole("user1", "admin");
    }
}

1. 获取会话信息：

import cn.fxp.sdk.starter.SaTokenManager;

public class AuthService {

    @Autowired
    private SaTokenManager saTokenManager;

    public void getSessionInfo() {
        // 获取会话信息
        SaToken saToken = saTokenManager.getSaToken("user1");
        System.out.println(saToken.toString());
    }
}

1. 更新会话信息：

import cn.fxp.sdk.starter.SaTokenManager;

public class AuthService {

    @Autowired
    private SaTokenManager saTokenManager;

    public void updateSession() {
        // 更新会话信息
        saTokenManager.setRole("user1", "editor");
    }
}

1. 销毁会话：

import cn.fxp.sdk.starter.SaTokenManager;

public class AuthService {

    @Autowired
    private SaTokenManager saTokenManager;

    public void logout() {
        // 销毁会话
        saTokenManager.clearToken("user1");
    }
}

会话的安全性设置

为了确保会话的安全性，Sa-Token 提供了多种安全性设置选项：

1. 设置 Token 过期时间：

# 设置 Token 过期时间
sa-token.jwt.timeout=3600000

1. 禁用自动刷新：

# 禁用 Token 自动刷新
sa-token.jwt.autoRefresh=false

1. 设置黑名单：

# 设置黑名单
sa-token.blacklist.ip=192.168.1.1,15.168.1.2
sa-token.blacklist.url=/admin/*

1. 启用 SSL 认证：

# 启用 SSL 认证
sa-token.ssl.enabled=true
sa-token.ssl.keystorePath=/path/to/keystore.jks
sa-token.ssl.keystorePassword=your-password

实战演练

构建一个简单的权限管理系统

构建一个简单的权限管理系统，包括用户登录、权限控制和会话管理。

1. 创建用户实体类：

public class User {
    private String id;
    private String username;
    private String password;
    private String role;

    // Getter 和 Setter 方法
}

1. 创建用户服务类：

import cn.fxp.sdk.starter.SaTokenManager;

public class AuthService {

    @Autowired
    private SaTokenManager saTokenManager;

    public String login(String username, String password) {
        // 模拟用户认证
        if ("user1".equals(username) && "password1".equals(password)) {
            // 创建会话并设置角色
            String token = saTokenManager.createToken(username);
            saTokenManager.setRole(username, "admin");
            return token;
        }
        return null;
    }
}

1. 创建权限控制示例：

import cn.fxp.sdk.starter.SaTokenManager;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class SaTokenController {

    @Autowired
    private SaTokenManager saTokenManager;

    @GetMapping("/admin")
    public String admin() {
        // 检查权限
        if (!saTokenManager.validRole("admin")) {
            return "Access denied";
        }
        return "Admin page";
    }
}

使用Sa-Token进行用户登录验证

1. 创建登录控制器：

import cn.fxp.sdk.starter.SaTokenManager;

@RestController
@RequestMapping("/api")
public class LoginController {

    @Autowired
    private SaTokenManager saTokenManager;

    @GetMapping("/login")
    public String login(String username, String password) {
        // 用户认证
        if ("user1".equals(username) && "password1".equals(password)) {
            // 创建会话
            String token = saTokenManager.createToken(username);
            return "Login success. Token: " + token;
        }
        return "Login failed";
    }
}

1. 创建权限控制示例：

import cn.fxp.sdk.starter.SaTokenManager;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class SaTokenController {

    @Autowired
    private SaTokenManager saTokenManager;

    @GetMapping("/check")
    public String check(String token) {
        // 验证 Token
        boolean valid = saTokenManager.validToken(token);
        return "Token is " + (valid ? "valid" : "invalid");
    }
}

会话超时与过期处理

1. 配置 Token 过期时间：

# 配置 Token 过期时间
sa-token.jwt.timeout=3600000

1. 处理过期逻辑：

import cn.fxp.sdk.starter.SaTokenManager;

@RestController
@RequestMapping("/api")
public class SaTokenController {

    @Autowired
    private SaTokenManager saTokenManager;

    @GetMapping("/timeout-check")
    public String timeoutCheck(String token) {
        // 验证 Token 是否过期
        boolean valid = saTokenManager.validToken(token);
        if (!valid) {
            return "Token has expired";
        }
        return "Token is valid";
    }
}

资源推荐与社区支持

官方文档和资源库

• 官方文档：Sa-Token 官方文档提供了详细的 API 文档和使用指南，帮助开发者快速上手。
• 资源库：Sa-Token 的 GitHub 资源库包含了大量的示例代码和测试用例，可以参考这些资源进行学习和实践。

开发者社区与论坛

• 开发者社区：Sa-Token 有一个活跃的开发者社区，开发者可以在社区中交流经验、分享问题和解决方案。
• GitHub Issues：在 GitHub 上的 Issues 列表中可以查看其他开发者提交的问题和解决方案。

常见问题和解决方案汇总

• Token 过期问题：检查配置文件中的 sa-token.jwt.timeout 是否设置正确。
• 权限控制问题：确保在配置文件中正确设置了权限规则，并在代码中正确设置了用户角色。
• 会话丢失问题：确保 Redis 服务正常运行，并检查相关配置是否正确。