JWT System Guide¶

Архитектура JWT¶

Два типа токенов¶

AdminClaims - для администраторов:

type AdminClaims struct {
    jwt.StandardClaims
    Email       string   `json:"email"`
    Permissions []string `json:"permissions"`
    Roles       []string `json:"roles"`
}

JWTClaims - для пользователей:

type JWTClaims struct {
    jwt.StandardClaims
    UserID      int64  `json:"user_id"`
    Email       string `json:"email"`
    WalletAddr  string `json:"wallet_address"`
}

Генерация токенов¶

Использование Makefile команд¶

# Админский токен
make jwt-admin EMAIL=admin@saga-test.com

# Пользовательский токен
make jwt-user EMAIL=user@saga-test.com

# Только токен (без логов)
make jwt-admin-token EMAIL=admin@saga-test.com

Программная генерация¶

import "github.com/aiseeq/saga/backend/auth/service"

// Генерация admin токена
jwtService := service.NewJWTService(cfg)
token, err := jwtService.GenerateAdminToken(email, permissions, roles)

// Генерация user токена
token, err := jwtService.GenerateUserToken(userID, email, walletAddress)

Валидация токенов¶

Middleware защита¶

import "github.com/aiseeq/saga/backend/shared/http"

// Admin endpoints
router.Use(middleware.AdminAuthMiddleware(cfg))

// User endpoints
router.Use(middleware.AuthMiddleware(cfg))

Ручная валидация¶

import "github.com/aiseeq/saga/backend/shared/http"

validator := http.NewJWTValidator(cfg)

// Валидировать admin токен
claims, err := validator.ValidateAdminToken(tokenString)

// Валидировать user токен
claims, err := validator.ValidateUserToken(tokenString)

️ Конфигурация¶

UnifiedConfig система¶

// Получение JWT настроек
cfg := config.LoadUnifiedConfig()

secret := cfg.GetJWTSecret()
expiration := cfg.GetJWTExpirationHours()
issuer := cfg.GetJWTIssuer()

nvironment variables¶

# .env файл
JWT_SECRET=your-secret-key-minimum-32-characters-required
JWT_EXPIRATION_HOURS=24
JWT_ISSUER=saga-platform

Тестирование¶

2E тесты с JWT¶

import { generateAdminJWT } from '@/utils/admin-jwt-helper';

// Генерация тестового токена
const adminToken = await generateAdminJWT('admin@saga-test.com');

// Использование в API запросах
const response = await fetch('/api/admin/users', {
  headers: {
    'Authorization': `Bearer ${adminToken}`
  }
});

Unit тесты¶

func TestJWTGeneration(t *testing.T) {
    cfg := config.LoadTestConfig()
    service := NewJWTService(cfg)

    token, err := service.GenerateAdminToken(
        "test@example.com",
        []string{"read:users"},
        []string{"admin"},
    )

    require.NoError(t, err)
    require.NotEmpty(t, token)
}

Troubleshooting¶

Типичные проблемы¶

"signature is invalid" - Проверьте что JWT_SECRET одинаковый в backend и helper - Убедитесь что используется правильный алгоритм (HS256)

"token contains invalid segments" - Проверьте формат токена (должен быть 3 части через точку) - Убедитесь что токен не поврежден при передаче

"token is expired" - Проверьте JWT_EXPIRATION_HOURS настройку - Сгенерируйте новый токен

"Требуется авторизация" - Убедитесь что передаете Bearer токен в Authorization заголовке - Проверьте что используете правильный тип токена (admin vs user)

Связанная документация¶

Дополнительные ресурсы¶

JWT RFC: https://datatracker.ietf.org/doc/html/rfc7519
Best Practices: https://tools.ietf.org/html/rfc8725
OWASP JWT Guide: https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html

📋 Метаданные¶

Версия: 2.4.82

Обновлено: 2025-10-21

Статус: Published