DOCSEARCHbyAlgolia
Submit Docs

Sa-Token Java Permission and Authentication Framework

repository·dev·Indexed 12 days ago

https://github.com/dromara/sa-token

A lightweight, all-in-one Java framework for login authentication, permission management, SSO, and OAuth2.0. It features a simple API via StpUtil, supports RBAC, microservices authentication, and distributed sessions with Redis integration. Provides flexible permission checks using @SaCheckPermission annotations or SaInterceptor route matching.

Tokens
175.2K
Snippets
459
Records
622
Agent score
95%

What's inside Sa-Token

  1. What is Sa-Max Unified Authentication Commercial Edition?

    dev

    Sa-Max is a complete, commercial-grade unified authentication center system built on top of the Sa-Token framework. While Sa-Token is a library/framework you integrate into your own code, Sa-Max is a standalone, ready-to-run project designed to serve as a centralized authentication hub.

    Key features include:

    • Broad Architecture Support: Supports SSO authentication across same-domain, cross-domain, shared Redis, cross-Redis, monolithic (frontend/backend integrated), and decoupled (frontend/backend separated) architectures. It works with Java, non-Java, pure JS, Vue2, and Vue3 projects.
    • Advanced Auth Capabilities: Supports API Key and OAuth2.0 unified authentication.
    • Open Platform: Provides an open platform for third-party companies to apply for and integrate with the authentication capabilities.
    • Customization: Delivered as full source code (excluding encrypted JARs), allowing for complete secondary development without restrictions on domains or the number of projects.

  2. Overview of Sa-Token features

    dev

    Sa-Token is a comprehensive authentication and authorization framework providing a wide range of security capabilities:

    Authentication & Authorization

    • Login Modes: Supports one-way, multi-party, mutually exclusive login (e.g., preventing simultaneous logins on different devices), and "Remember Me" functionality.
    • Permission Management: Includes permission and role-based authentication, as well as secondary session authentication.
    • Annotation & Interceptor Based: Allows elegant separation of security logic from business code using annotations or route interceptors (ideal for RESTful APIs).
    • Account Security: Features account locking (login/business/scale-based), password encryption (MD5, SHA1, SHA256, AES), and support for HTTP Basic/Digest authentication.
    • Identity Management: Supports impersonating other users, temporary identity switching, and multi-account systems (e.g., separate tables for users and admins).

    Session & Token Management

    • Session Models: Supports shared sessions, exclusive sessions, and customizable sessions with easy value access.
    • Token Customization: Offers six built-in token styles and allows custom generation strategies.
    • Token Lifecycle: Supports automatic token renewal and temporary token authentication.
    • Persistence: Integrates with Redis to prevent data loss upon restart and supports distributed sessions for data center clusters.
    • Separation of Concerns: Supports architectures where front-end and back-end are separated (e.g., mobile apps/applets that don't support cookies).

    Advanced Security & Integration

    • SSO (Single Sign-On): Built-in support for same-domain, cross-domain, and Redis-based SSO.
    • OAuth2.0: Easily create OAuth2.0 services supporting OpenID mode.
    • Microservices & RPC: Supports authentication for microservice gateways (Gateway, ShenYu, Zuul, etc.) and maintains login status during RPC calls (Dubbo, gRPC).
    • Global Hooks: Provides Global Listeners (AOP for login/logout/offline events) and Global Filters (for CORS and security headers).
    • Modern Tech Stack: Compatible with SpringBoot 3.x and JDK 17.
    • JWT Integration: Provides three different JWT integration solutions with extensible token parameters.

  3. Introduction to Sa-Token

    dev

    Sa-Token is a lightweight Java authentication and authorization platform. It is designed to provide a simple and elegant way to handle security requirements in Java applications. The platform is composed of five core modules:

    1. Login Authentication: Managing user sessions and login states.
    2. Permission Authentication: Controlling access to specific resources or functions.
    3. SSO (Single Sign-On): Enabling single sign-on across multiple systems.
    4. OAuth2.0: Implementing standard OAuth2 authorization protocols.
    5. Microservice Authentication: Handling security in distributed microservice architectures.

  4. What is Sa-Token?

    dev

    Sa-Token is a lightweight Java permission and authentication framework. It provides a one-stop solution for common security requirements including:

    • Login Authentication: Single-device, multi-device, and mutual exclusion login.
    • Permission Authentication: Role-based access control (RBAC) and session-level secondary authentication.
    • Single Sign-On (SSO): Support for same-domain, cross-domain, and distributed architectures.
    • OAuth2.0: Easy setup for OAuth2.0 services, including OpenID support.
    • Microservices: Authentication for gateways (Gateway, ShenYu, Zuul) and RPC calls.
    • Distributed Sessions: Shared session data centers and Redis integration.

    Unlike other frameworks, Sa-Token is a self-developed, zero-dependency core engine designed for simplicity and elegance, with various integration packages for mainstream frameworks like SpringMVC, WebFlux, and Solon.

  5. View open-source projects using Sa-Token

    dev

    Sa-Token is integrated into several prominent open-source rapid development platforms and management systems, including:

    • Snowy: A rapid development platform using Vue3 + Vite + SpringBoot.
    • RuoYi-Vue-Plus: An enhanced version of RuoYi-Vue integrating Sa-Token, Mybatis-Plus, and more.
    • Smart-Admin: A high-quality rapid development platform.
    • Chengdan: A low-code generator supporting multi-tenancy and multi-channel.
    • Lamp-Cloud: A multi-tenant oriented rapid development platform.
    • Shiyi Blog: A Vue + SpringBoot blog system.

    For a full list of community projects, visit the Awesome-Sa-Token repository.

  6. Core modules of Sa-Token

    dev

    Sa-Token is a one-stop solution providing the following core capabilities:

    • Login Authentication: Supports single-end, multi-end, mutually exclusive login, and 'Remember Me' modes.
    • Permission Authentication: Includes permission/role authentication and session secondary authentication.
    • SSO (Single Sign-On): Supports various architectures (same/cross domain, shared/separate Redis).
    • OAuth2.0: Full support for standard OAuth2 flows.
    • Microservice Authentication: Adapted for common gateways (Gateway, ShenYu, Zuul) and RPC call authentication (Dubbo, gRPC).

  7. Key features of Sa-Token-SSO

    dev

    Sa-Token-SSO is designed to solve Single Sign-On challenges with the following capabilities:

    • Versatile Modes: Supports cross-domain, non-shared Redis, and decoupled frontend/backend architectures.
    • High Security: Includes built-in domain validation, Ticket validation, and Key validation to prevent Ticket劫持 (Ticket hijacking) and Token窃取 (Token theft).
    • Parameter Preservation: Uses specialized algorithms to ensure that URL parameters (e.g., http://a.com?id=1&name=2) are not lost during the redirection process after successful login.
    • Seamless Integration: Since it is built on top of Sa-Token, you can manage both standard 权限认证 (permission authentication) and 单点登录 (SSO) within a single framework.
    • Low Intrusion: The architecture allows for high customization by leveraging Sa-Token's routing interceptor features.

  8. Integrate Sa-Token with gRPC

    dev

    The sa-token-grpc plugin enables integration between Sa-Token and gRPC, solving three main problems:

    1. Secure API Access: Allows the [Callee] (the service being called) to safely invoke Sa-Token related APIs.
    2. Session Propagation: Automatically transfers the login session state from the [Caller] to the [Callee], and vice versa.
    3. Same-Token Security: Enables Same-Token security verification across RPC calls.

    Important Limitations:

    • SaStorage data cannot be shared between the [Caller] and the [Callee].
    • Code executed in the [Callee] that uses SaResponse.setHeader() or setStatus() will have no effect.

  9. Understand the Sa-Token Repository Structure

    dev

    The Sa-Token repository is organized into several functional modules. Understanding this structure helps you locate the core logic, integration starters, plugins, and practical examples.

    Core Modules

    • sa-token-core: The central Sa-Token logic.
    • sa-token-bom: Bill of Materials for managing Sa-Token dependency versions.
    • sa-token-dependencies: Centralized dependency version information.
    • sa-token-special-dependencies: Handles version isolation for different SpringBoot versions (2/3/4).

    Integration and Extensions

    • sa-token-starter: Contains various integration packages for different frameworks (e.g., SpringBoot, Servlet, Solon, JFinal).
    • sa-token-plugin: A collection of plugins for features like JSON serialization (Jackson, Fastjson), caching (Caffeine, Redis), and authentication protocols (SSO, OAuth2, APIKey, JWT).

    Support and Examples

    • sa-token-demo: A comprehensive collection of usage examples covering various scenarios (SSO, OAuth2, Dubbo, gRPC, etc.).
    • sa-token-test: Unit testing suites for the core and specific modules.
    • sa-token-doc: The official development documentation.

  10. What is the Sa-Token Firewall and how does it work?

    dev

    Sa-Token includes a built-in firewall component, SaFirewallStrategy, designed to intercept and block dangerous requests that could lead to attacks (e.g., path traversal, double slashes in URLs, or malicious parameters).

    The firewall operates using a hooks mechanism. When a request arrives, the strategy executes a series of registered hooks. If any hook determines the request is invalid (usually by throwing a FirewallCheckException), the request is blocked.

    Default Hooks provided by the framework:

    • SaFirewallCheckHookForWhitePath: Allows requests matching a white list.
    • SaFirewallCheckHookForBlackPath: Validates against a black list.
    • SaFirewallCheckHookForPathDangerCharacter: Checks for dangerous characters in the path.
    • SaFirewallCheckHookForPathBannedCharacter: Checks for banned characters in the path.
    • SaFirewallCheckHookForDirectoryTraversal: Detects directory traversal attempts.
    • SaFirewallCheckHookForHost: Validates the Host header.
    • SaFirewallCheckHookForHttpMethod: Validates the HTTP Method.
    • SaFirewallCheckHookForHeader: Validates request headers.
    • SaFirewallCheckHookForParameter: Validates request parameters.

  11. What is SaTokenContext and when to implement it

    dev

    Sa-Token uses the SaTokenContext interface to abstract away the differences between various Web frameworks (like SpringBoot, WebFlux, or Solon). This allows Sa-Token to use a single set of core logic to interact with different request/response objects.

    When to implement it:

    • If you are using a supported framework (SpringBoot, SpringMVC, WebFlux, Solon), you do not need to implement it; the corresponding starter package provides a built-in implementation (e.g., SaTokenContextForSpring).
    • If you are using a Web framework not on the supported list, you must include sa-token-core and manually implement the SaTokenContext interface to bridge your framework with Sa-Token.

  12. What is Sa-Sso-Pro and how does it differ from Sa-Token?

    dev

    It is important to distinguish between the Sa-Token framework and the Sa-Sso-Pro project:

    • Sa-Token: An open-source authentication and authorization framework. You integrate it into your existing projects by adding it as a dependency in your pom.xml.
    • Sa-Sso-Pro: A complete, commercial project designed to serve as a production-ready Single Sign-On (SSO) authentication center. Instead of being a library you call, it is a standalone system you download and run.

    Key differences:

    FeatureSa-TokenSa-Sso-Pro
    TypeFramework (Library)Complete Project (System)
    IntegrationAdd to pom.xmlDownload and start directly
    CostFree (Open Source)Paid (Commercial)
    PurposeProvides auth logic for your appProvides a ready-to-use Auth Center

    Use Sa-Sso-Pro if you need a commercial-grade authentication center with built-in features like user account maintenance, login logs, data reporting, and client application domain configuration without writing them from scratch.