# flare-starter

**Repository Path**: itz001/flare-starter

## Basic Information

- **Project Name**: flare-starter
- **Description**: A Login Starter Base on SpringSecurity
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-05
- **Last Updated**: 2026-06-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# flare-starter

A comprehensive authentication and authorization starter library for Spring Boot applications.

## Features

- **JWT Token Authentication** - Issues, validates, and refreshes JWT tokens with device tracking
- **Multiple Login Methods**
  - Username/Password authentication
  - SMS authentication (phone number + verification code)
- **Multi-Device Session Management**
  - Current device logout
  - All devices logout
  - Same type devices logout
- **Password Encryption Support**
  - NONE (plaintext)
  - AES encryption
  - SM4 encryption
  - RSA encryption
- **Token Blacklist** - Invalidates tokens on logout
- **User Caching** - Redis and in-memory implementations
- **Automatic Token Refresh** - Refreshes tokens before expiration

## Tech Stack

| Component | Technology |
|-----------|------------|
| Framework | Spring Boot 4.0.1 |
| Security | Spring Security |
| Token | JWT (jjwt 0.13.0) |
| Encryption | BouncyCastle, Spring Security Crypto |
| Cache | Spring Data Redis |
| Build | Maven (Java 21) |

## Project Structure

```
flare-starter/
├── auth-spring-boot-starter/           # Starter module
└── auth-spring-boot-autoconfigure/     # Auto-configuration module
    └── src/main/java/com/isoft/flare/starter/auth/
        ├── config/                     # Auto-configuration classes
        ├── enhance/                    # Enhanced services
        ├── enums/                      # Enumerations
        ├── filter/                     # Authentication filters
        ├── handler/                    # Auth handlers
        ├── properties/                  # Configuration properties
        ├── provider/                   # Token provider
        ├── records/                    # DTOs
        └── support/                    # Adapters, cache, crypto, strategies
```

## Quick Start

### 1. Add Dependency

```xml
<dependency>
    <groupId>com.isoft.flare</groupId>
    <artifactId>auth-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 2. Configure Application

```yaml
flare:
  auth:
    jwt:
      secret-key: your-secret-key
      expiration: 86400000        # 24 hours in milliseconds
      refresh-threshold: 1800000  # 30 minutes in milliseconds
    login:
      username-url: /login
      sms-url: /sms/login
    device:
      device-id-header: X-Device-Id
      device-type-header: X-Device-Type
```

### 3. Implement UserDetails

```java
@Component
public class MyUserDetailsService implements UserLoadingStrategy {
    
    @Override
    public UserDetails loadUser(String username) {
        // Load and return user details
    }
}
```

## Configuration Properties

| Property | Description | Default |
|----------|-------------|---------|
| `flare.auth.jwt.secret-key` | JWT signing key | - |
| `flare.auth.jwt.expiration` | Token expiration time | 86400000 (24h) |
| `flare.auth.jwt.refresh-threshold` | Time before expiration to refresh | 1800000 (30min) |
| `flare.auth.login.username-url` | Username/password login URL | /login |
| `flare.auth.login.sms-url` | SMS login URL | /sms/login |
| `flare.auth.white-list` | Public endpoint patterns | [] |

## Extensibility

- **PasswordDecoderStrategy** - Custom password decryption
- **LogoutStrategy** - Custom logout behavior
- **UserLoadingStrategy** - Custom user loading
- **AuthenticationStrategy** - Custom authentication logic
- **FlareResponseStrategy** - Custom response formatting

## Best Practices
### Password Encryption Transmission
When using AES or SM4 encryption for password transmission, the encryption key (`secretKey`) and initialization vector (`iv`) are generated as Base64-encoded strings. These strings may contain special characters like `+`, `/`, or `=` which can be corrupted during HTTP transmission.
**Problem**: Base64 strings containing `+` may be interpreted as spaces when sent via URL parameters or form-encoded request bodies.
**Solution**: Encode Base64 strings using URL encoding on the client side before transmission:
**Client-side (JavaScript example)**:
```javascript
const secretKey = "5BuEvFGdU+hJzzeqXHfCyQ==";  // Base64 encoded key
const iv = "randomBase64IV==";
const requestBody = {
    username: "user123",
    password: encryptedPassword,
    secretKey: encodeURIComponent(secretKey),  // "5BuEvFGdU%2BhJzzeqXHfCyQ%3D"
    iv: encodeURIComponent(iv)
};
```
**Note**: The starter will automatically decode the values internally. Ensure your client application properly encodes Base64 strings with special characters before sending login requests.

## License

MIT License