Введение

Плагин token, основанный на фреймворке GoFrame, реализует аутентификацию token посредством серверной проверки. Он полностью готов к использованию для аутентификации token в продакшене и поддерживает кластерный режим через Redis. Его легко использовать, вы можете смело его применять.

Полностью совместим с GoFrame v2.0.0; для GoFrame v1.X.X используйте соответствующую версию gtoken v1.4.X.

• Адрес на GitHub: https://github.com/goflyfox/gtoken
• Адрес на Gitee: https://gitee.com/goflyfox/gtoken

Преимущества gtoken

1. gtoken поддерживает использование памяти для хранения данных при тестировании одноточечных приложений, а также хранение файлов для личных проектов и работу с кластерами Redis для корпоративных сред. Подходит для использования в производственных условиях предприятия.
2. Эффективно решает проблему невозможности выхода из системы при использовании JWT на сервере.
3. Устраняет необходимость ждать истечения срока действия токена для его аннулирования, что является проблемой JWT.
4. Хранит пользовательские данные расширения на сервере, решая проблему снижения эффективности передачи данных из-за необходимости JWT переносить большой объём информации о пользователе.
5. Позволяет избежать необходимости реализации функции продления токена на клиенте, увеличивая сложность клиента. Поддерживает автоматическое продление на сервере, избавляя клиента от управления логикой продления.

Описание функций

1. Поддержка аутентификации по токену без сильной зависимости от session и cookie, подходит для всех сценариев аутентификации JWT и session.
2. Поддержка режимов кэширования gcache и gredis на одном сервере и в кластере.

# Режим кэширования 1 gcache 2 gredis 3 fileCache
CacheMode = 2

2. Функция автоматического продления срока службы кэша на сервере поддерживается.

// Примечание: по умолчанию срок действия обновляется, когда пользователь заходит на сайт на пятый день
// Тайм-аут по умолчанию составляет 10 дней
Timeout int
// Время обновления кэша по умолчанию равно половине времени ожидания
MaxRefresh int

4. Поддерживаются групповые, глобальные и глубокоуровневые перехваты, что позволяет настраивать перехватчики в соответствии с индивидуальными требованиями. Рекомендуется использовать групповой перехват.
5. Простота использования фреймворка, требуется только настроить метод входа в систему и маршруты входа и выхода.
6. Начиная с версии gtoken v1.4.0, поддерживается реализация промежуточного программного обеспечения для групповых групп, но сохраняется совместимость с глобальной и глубокой реализацией промежуточного программного обеспечения.
7. В версии gtoken v1.5.0 полностью адаптирован GoFrame v2.0.0; Для GoFrame v1.X.X используйте соответствующие версии GfToken v1.4.X.

Инструкция по установке

• В режиме gopath: go get github.com/goflyfox/gtoken
• Или добавьте в go.mod: require github.com/goflyfox/gtoken latest

Реализация группового промежуточного ПО

GoFrame официально рекомендует использовать Group для реализации маршрутизации и промежуточного программного обеспечения.

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

Рекомендуется использовать групповую реализацию.

    // Запуск gtoken
    gfToken := &gtoken.GfToken{
        LoginPath:        "/login",
        LoginBeforeFunc:  loginFunc,
        LogoutPath:       "/user/logout",
    }
    s.Group("/admin", func(group *ghttp.RouterGroup) {
        group.Middleware(CORS)
        gfToken.Middleware(group)

        group.ALL("/system/user", func(r *ghttp.Request) {
            r.Response.WriteJson(gtoken.Succ("system user"))
        })
        ………………
    })

Реализация метода входа, возврат пустого значения или r.ExitAll()\r.Exit() при неудачной аутентификации.

Особое примечание: зарегистрированные пути должны строго соответствовать формату группы GF, поэтому зарегистрированные пути — это /admin/login и /admin/user/logout.

func Login(r *ghttp.Request) (string, interface{}) {
    username := r.GetPostString("username")
    passwd := r.GetPostString("passwd")

    // TODO провести проверку входа
    if username == "" || passwd == "" {
        r.Response.WriteJson(gtoken.Fail("账号或密码错误."))
        r.ExitAll()
    }

    // Первое поле — уникальный идентификатор пользователя, второе поле — дополнительные данные пользователя
    return username, ""
}

Получение информации для входа с помощью gtoken.GetTokenData(r).

Правила перехвата пути

    AuthExcludePaths: g.SliceStr{"/user/info", "/system/user/*"}, // Не перехватывать пути  /user/info,/system/user/info,/system/user,

1. Реализация промежуточного программного обеспечения на уровне группы не требует настройки путей аутентификации AuthPaths, так как настройка не имеет эффекта, пути аутентификации — это все маршруты в данной группе;
2. Групповой перехват осуществляется с помощью метода group.Middleware(authMiddleware) GoFrame для всех маршрутов в этой группе;
3. Перехват путей входа loginPath и выхода logoutPath для предотвращения ситуации, когда после истечения срока аутентификации невозможно выйти из системы;
4. Строго следуйте приоритету перехвата промежуточного программного обеспечения GoFrame Group; если используется междоменное программное обеспечение, рекомендуется размещать его после междоменного программного обеспечения;
5. Если настроен путь исключения AuthExcludePaths, указанные пути не будут перехвачены.

Логическое тестирование

См. образец проекта, сначала запустите main.go, затем запустите api_test.go для тестирования и просмотра результатов. Проверка логики:

1. Доступ к информации пользователя приводит к ошибке «отсутствует токен».
2. После входа в систему доступ к данным с использованием токена работает корректно.
3. Успешный выход из системы.
4. Попытка доступа с предыдущим токеном приводит к сообщению о том, что пользователь не вошёл в систему.

=== RUN   TestAdminSystemUser
    api_admin_test.go:22: 1. not login and visit user
    api_admin_test.go:29: {"code":-401,"msg":"请求错误或登录超时","data":""}
    api_admin_test.go:42: 2. execute login and visit user
    api_admin_test.go:45: {"code":0,"msg":"success","data":"system user"}
    api_admin_test.go:51: 3. execute logout
    api_admin_test.go:54: {"code":0,"msg":"success","data":"Logout success"}
    api_admin_test.go:60: 4. visit user
    api_admin_test.go:65: {"code":-401,"msg":"请求错误或登录超时","data":""}

Глобальная реализация промежуточного ПО

Применение

Требуется только настроить маршрут входа, маршрут выхода, маршрут перехвата и функцию проверки входа.

    // Запустить gtoken
    gtoken := &gtoken.GfToken{
        LoginPath:       "/login",
        LoginBeforeFunc: loginFunc,
        LogoutPath:      "/user/logout",
        AuthPaths:        g.SliceStr{"/user", "/system"}, // Здесь префикс используется для перехвата, перехватывая /user /user/list /user/add ...
        GlobalMiddleware: true,                           // Включить глобальный перехват, по умолчанию отключено
    }
    gtoken.Start()

Реализация функции входа, возвращение пустого значения или r.ExitAll()\r.Exit() при ошибке аутентификации.

func Login(r *ghttp.Request) (string, interface{}) {
    username := r.GetPostString("username")
    passwd := r.GetPostString("passwd")

    // TODO выполнить проверку входа
    if username == "" || passwd == "" {
        r.Response.WriteJson(gtoken.Fail("账号或密码错误."))
        r.ExitAll()
    }

    // Первый параметр — уникальный идентификатор пользователя, второй параметр — дополнительные данные пользователя
    return username, ""
}
``` Через `gtoken.GetTokenData(r)` получаем информацию для входа.

### Правила перехвата пути
```go
    AuthPaths:        g.SliceStr{"/user", "/system"},             // Здесь перехватывается по префиксу, перехватываются /user, /user/list, /user/add ...
    AuthExcludePaths: g.SliceStr{"/user/info", "/system/user/*"}, // Не перехватываемые пути  /user/info,/system/user/info,/system/user,
    GlobalMiddleware: true,                           // Включить глобальный перехват, по умолчанию выключено

1. GlobalMiddleware:true глобальный перехват выполняется через GF-метод BindMiddleware.
2. GlobalMiddleware:false перехват пути выполняется через метод GF BindMiddleware, создавая перехват /user* и /system/*.
3. Перехват пути с использованием промежуточного программного обеспечения имеет высокий приоритет; если некоторые промежуточные программы должны быть переключены на глобальный перехватчик перед аутентификацией, это должно быть сделано строго в порядке регистрации;
4. Программа сначала обрабатывает аутентифицированные пути, если они удовлетворяются; затем исключает неаутентифицированные пути;
5. Если вы хотите использовать только функцию исключения путей, установите перехваченный путь как /*.

Логическое тестирование

См. sample1 проект, сначала запустите main.go, затем можно запустить api_test.go для тестирования и просмотра результатов; проверка логики:

1. Доступ к информации о пользователе, сообщение об отсутствии токена.
2. После вызова входа в систему доступ с токеном работает нормально.
3. Вызов выхода из системы успешно.
4. Попытка доступа с предыдущим токеном приводит к сообщению о том, что пользователь не вошёл в систему.

=== RUN   TestSystemUser
    api_test.go:43: 1. not login and visit user
    api_test.go:50: {"code":-401,"msg":"请求错误或登录超时","data":""}
    api_test.go:63: 2. execute login and visit user
    api_test.go:66: {"code":0,"msg":"success","data":"system user"}
    api_test.go:72: 3. execute logout
    api_test.go:75: {"code":0,"msg":"success","data":"Logout success"}
    api_test.go:81: 4. visit user
    api_test.go:86: {"code":-401,"msg":"请求错误或登录超时","data":""}

Коды возврата и параметры конфигурации

1. Нормальный успешный возврат 0.
2. При попытке доступа без входа возвращается 401, требуя входа для доступа к ресурсу.
3. В случае ошибки программы возвращается -99, например, ошибка кодирования.

SUCCESS      = 0  // Нормальный
FAIL         = -1  // Ошибка
ERROR        = -99  // Исключение
UNAUTHORIZED = -401  // Неавторизованный

Описание параметров конфигурации

Для получения подробной информации см. структуру GfToken, описание полей: