中文文档 | English

Welcome to sa-token-rust documentation! All documentation is available in both English and Chinese (中文).

💡 New! Simplified Usage Guide - Get started with just one dependency!

Use release 0.1.13. Add exactly one sa-token-plugin-* crate for your web stack.

Rust import (rename module to match your crate):

use sa_token_plugin_axum::*;          // Axum — or sa_token_plugin_actix_web, etc.

Storage features apply to every plugin: default memory, or add redis, database, or full as in Simplified Usage.

Path-based middleware (SaTokenLayer::with_path_auth, etc.) ships for Actix v4, Axum, Poem, Tide, Salvo, Ntex. Rocket / Gotham / Warp layers authenticate globally (SaTokenLayer::new) — compose PathAuthConfig in handlers or macros where you need path rules (Path Auth).

Complete walkthrough → Main README — Quick Start.

All examples are located in the examples/ directory:

Run examples:

# Basic examples
cargo run --example event_listener_example
cargo run --example jwt_example

# WebSocket + Online users
cargo run --example websocket_online_example

# Distributed session
cargo run --example distributed_session_example

Dependency examples (0.1.13):

[dependencies]
sa-token-plugin-axum = "0.1.13"
# sa-token-plugin-actix-web = { version = "0.1.13", features = ["redis"] }
# sa-token-plugin-rocket = "0.1.13"

use sa_token_plugin_axum::*;  // swap crate name per framework

See the Quick Start section above and Main README — Quick Start for façade vs integrated features.

Bilingual Documentation (English + 中文):

• StpUtil API Reference
• Event Listeners
• JWT Guide
• OAuth2 Guide
• Permission Matching

Multi-language Documentation (7 languages):

• WebSocket Authentication
• Online User Management
• Distributed Session
• SSO Single Sign-On
• Error Reference

Supported Languages:

• 🇬🇧 English
• 🇨🇳 中文 (Chinese)
• 🇹🇭 ภาษาไทย (Thai)
• 🇻🇳 Tiếng Việt (Vietnamese)
• 🇰🇭 ភាសាខ្មែរ (Khmer)
• 🇲🇾 Bahasa Melayu (Malay)
• 🇲🇲 မြန်မာဘာသာ (Burmese)

• Authentication: Login, logout, token validation, session management
• Authorization: Permission and role-based access control with wildcards
• Event System: Listen to login, logout, kick-out, and custom events
• Token Styles: UUID, Random, JWT, Hash, Timestamp, Tik (7 options)

• JWT Support: 8 algorithms (HS256/384/512, RS256/384/512, ES256/384)
• OAuth2: Complete authorization code flow implementation
• Security: Nonce (replay attack prevention), Refresh token mechanism
• WebSocket: Authenticate WebSocket connections with multiple token sources
• Online Users: Real-time tracking and message push
• Distributed Session: Cross-service session sharing for microservices

• Memory (default): In-memory storage for development
• Redis: Production-ready Redis backend
• Database: Custom database storage (extensible)

Easy switch with features:

sa-token-plugin-axum = { version = "0.1.13", features = ["redis"] }

Looking for:

• Getting started? → Main README → Simplified Usage
• Authentication basics? → StpUtil API Reference
• Event monitoring? → Event Listener Guide
• JWT tokens? → JWT Guide
• OAuth2? → OAuth2 Guide
• WebSocket auth? → WebSocket Authentication
• Real-time features? → Online User Management
• Microservices? → Distributed Session
• Single Sign-On? → SSO Guide
• Error codes? → Error Reference
• Code examples? → Examples Directory

Contributions are welcome! Please feel free to submit:

• 🐛 Bug reports
• 💡 Feature requests
• 📖 Documentation improvements
• 🔧 Pull requests

See CONTRIBUTING.md for guidelines.

This project is dual-licensed under:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

You may choose either license at your option.

• 📚 Documentation: You're here!
• 💬 Issues: GitHub Issues
• 🌟 Star us: If you find this project helpful, give it a ⭐ on GitHub!

Made with ❤️ by the sa-token community