Быстрый старт

Установка

go get github.com/cybergodev/jwt

Требуется Go 1.25+.

Базовое использование

1. Создание Processor

package main

import (
    "fmt"
    "time"

    "github.com/cybergodev/jwt"
)

func main() {
    cfg := jwt.DefaultConfig()
    cfg.SecretKey = "hmac-key-that-has-at-least-32-bytes!" // HMAC минимум 32 байта
    cfg.AccessTokenTTL = 15 * time.Minute
    cfg.RefreshTokenTTL = 7 * 24 * time.Hour

    processor, err := jwt.New(cfg)
    if err != nil {
        panic(err)
    }
    defer processor.Close() // Безопасная очистка ключей
}

2. Выпуск токена

claims := &jwt.Claims{
    UserID:   "user123",
    Username: "alice",
    Role:     "admin",
    Permissions: []string{"read", "write"},
}

// Токен доступа (краткосрочный)
accessToken, err := processor.Create(claims)
if err != nil {
    panic(err)
}

// Токен обновления (долгосрочный)
refreshToken, err := processor.CreateRefresh(claims)
if err != nil {
    panic(err)
}

3. Проверка токена

parsed, valid, err := processor.Validate(accessToken)
if err != nil {
    // Обработка ошибок: истёк срок, недействительная подпись и т.д.
    panic(err)
}
if valid {
    fmt.Println("UserID:", parsed.UserID)
    fmt.Println("Role:", parsed.Role)
    fmt.Println("ExpiresAt:", parsed.ExpiresAt.Time)
}

4. Обновление токена

newAccessToken, err := processor.Refresh(refreshToken)
if err != nil {
    panic(err)
}
fmt.Println("New Access Token:", newAccessToken)

5. Отзыв токена

// Добавление токена в чёрный список
err := processor.Revoke(accessToken)
if err != nil {
    panic(err)
}

// Проверка отзыва
revoked, err := processor.IsRevoked(accessToken)
if err != nil {
    panic(err)
}
fmt.Println("Revoked:", revoked) // true

Дополнительные возможности

Описанные выше шаги охватывают основной жизненный цикл токена. CyberGo JWT также предоставляет следующие возможности — перейдите в соответствующее руководство для подробного описания:

Возможность	Описание	Руководство
Алгоритмы подписи	HMAC, RSA, RSA-PSS, ECDSA — 12 алгоритмов в 4 семействах	Алгоритмы подписи
Пользовательские Claims	Определение бизнес-полей через интерфейс CustomClaims	Пользовательские Claims
Обновление и ротация токенов	Двухуровневый TTL, стратегии повторного использования и одноразовой ротации	Обновление и ротация токенов
Чёрный список токенов	Отзыв, встроенное хранилище в памяти, пользовательские бэкенды Redis	Чёрный список токенов
Ограничение скорости	Алгоритм token bucket для защиты конечных точек выпуска	Ограничение скорости
Подробная конфигурация	Проверка издателя/аудитории, допуск часов, обязательный срок, проверка ввода	Подробная конфигурация
Обработка ошибок	19 категорий ошибок-сигналов и сопоставление errors.Is	Обработка ошибок
Тестирование и внедрение часов	FixedClock для детерминированного управления временем без sleep	Тестирование и внедрение часов

Дальнейшие шаги

• Алгоритмы подписи — выбор алгоритма и настройка ключей
• Обновление и ротация токенов — двухуровневые токены и стратегии ротации
• Подробная конфигурация — настройки безопасности и проверка ввода
• Справочник API — полная документация API
• Базовые примеры — готовые к запуску примеры
• Интеграция с веб-сервером — Middleware аутентификации и RBAC на практике