AIDeskLab.AuthClient

Версия 1.0.x

Универсальная клиентская библиотека для авторизации и регистрации пользователей через AuthServer. Предоставляет простой и мощный API для работы с gRPC сервером аутентификации, управления токенами, профилями пользователей и интеграции с Telegram.

Возможности

Аутентификация и авторизация

• Аутентификация пользователей - поддержка различных методов входа (логин/пароль, Telegram, телефон)
• Аутентификация сервисов - вход сервисов по API ключу и секрету
• Управление токенами - автоматическое обновление, безопасное хранение, отзыв токенов
• Проверка разрешений - валидация прав доступа пользователей

Управление пользователями

• Регистрация пользователей - подача заявок, одобрение/отклонение администраторами
• Управление профилями - полные профили пользователей с поддержкой Telegram аккаунтов
• Список пользователей - пагинация и поиск пользователей

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

• Интеграция с Telegram - работа с Telegram пользователями и ботами
• Middleware для ASP.NET Core - автоматическая интеграция в pipeline запросов
• Гибкое хранение токенов - в памяти, файл или системное хранилище ключей
• Политики повторных попыток - устойчивость к временным сбоям сети
• Полная типизация - строгая типизация всех моделей и ответов

Установка

Установите NuGet пакет в ваш проект:

dotnet add package AIDeskLab.AuthClient

Или через Package Manager Console:

Install-Package AIDeskLab.AuthClient

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

1. Настройка в Program.cs

using AuthClient.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Добавление AuthClient с настройками из конфигурации
builder.Services.AddAuthClient(builder.Configuration);

// Или минимальная настройка напрямую
// builder.Services.AddAuthClient("https://auth-server.example.com", "my-service-id");

var app = builder.Build();

// Добавление middleware для автоматической работы с токенами
app.UseAuthClient();

app.Run();

2. Конфигурация в appsettings.json

{
  "AuthClient": {
    "ServerUrl": "https://auth-server.example.com",
    "ServiceId": "my-service-id",
    "UseSsl": true,
    "OperationTimeout": "00:00:30",
    
    "TokenStorage": {
      "StorageType": "InMemory",
      "EncryptTokens": true,
      "EncryptionKey": "your-encryption-key-at-least-32-chars",
      "CacheDuration": "01:00:00"
    },
    
    "TokenRefresh": {
      "EnableAutoRefresh": true,
      "RefreshCheckInterval": "00:01:00",
      "RefreshBeforeExpiration": "00:05:00",
      "MaxRefreshAttempts": 3
    },
    
    "Retry": {
      "EnableRetry": true,
      "MaxRetryAttempts": 3,
      "BaseDelay": "00:00:01",
      "MaxDelay": "00:00:30",
      "Strategy": "ExponentialBackoff"
    }
  }
}

3. Использование в коде

using AuthClient.Services.Interfaces;

public class MyController : ControllerBase
{
    private readonly IAuthenticationService _authService;

    public MyController(IAuthenticationService authService)
    {
        _authService = authService;
    }

    [HttpPost("login")]
    public async Task<IActionResult> Login(LoginRequest request)
    {
        var result = await _authService.LoginAsync(
            request.Username,
            request.Password,
            "my-service-id"
        );

        if (result.Success)
        {
            return Ok(new { 
                AccessToken = result.AccessToken,
                RefreshToken = result.RefreshToken,
                User = result.User
            });
        }

        return Unauthorized(result.ErrorMessage);
    }
}

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

AuthClientOptions

Основные настройки клиента аутентификации:

TokenStorageOptions

Настройки хранения токенов:

TokenRefreshOptions

Настройки автоматического обновления токенов:

RetryOptions

Настройки политики повторных попыток:

Основные сервисы

IAuthenticationService

Сервис аутентификации с поддержкой различных методов входа:

• LoginAsync() - вход пользователя по логину и паролю
• LoginServiceAsync() - вход сервиса по API ключу и секрету
• LoginTelegramAsync() - вход через Telegram
• LoginByTelegramAndPhoneAsync() - вход по Telegram ID и телефону
• RefreshTokenAsync() - обновление токена доступа
• LogoutAsync() - выход из системы (отзыв токена)
• ChangePasswordAsync() - смена пароля

IRegistrationService

Универсальный сервис регистрации пользователей с системой заявок:

• SubmitRegistrationAsync() - подача заявки на регистрацию (поддерживает Telegram, Web, Mobile, API)
• GetRegistrationStatusAsync() - получение статуса заявки
• CancelRegistrationAsync() - отмена заявки
• ListRegistrationRequestsAsync() - список заявок (для администраторов)
• ApproveRegistrationAsync() - одобрение заявки
• RejectRegistrationAsync() - отклонение заявки
• VerifyEmailAsync() - верификация email (для веб-регистрации)
• ResendEmailVerificationAsync() - повторная отправка кода верификации email

Типы регистрации:

• Telegram - регистрация через Telegram бота (требует TelegramId + Phone)
• Web - регистрация через веб-интерфейс (требует Username + Password + Email)
• Mobile - регистрация через мобильное приложение
• API - регистрация через API

IUserRegistrationService

Сервис управления пользователями:

• RegisterUserAsync() - регистрация нового пользователя
• GetUserAsync() - получение информации о пользователе
• GetUserByUsernameAsync() - поиск пользователя по имени
• UpdateUserAsync() - обновление данных пользователя
• ActivateUserAsync() - активация пользователя
• DeactivateUserAsync() - деактивация пользователя
• ListUsersAsync() - список пользователей с пагинацией и поиском

ITokenManagementService

Административные функции управления токенами:

• GetUserActiveTokensAsync() - активные токены пользователя
• GetServiceActiveTokensAsync() - активные токены сервиса
• RevokeTokenAsync() - отзыв конкретного токена
• RevokeUserTokensAsync() - массовый отзыв токенов пользователя
• RevokeServiceTokensAsync() - массовый отзыв токенов сервиса
• CleanupExpiredTokensAsync() - очистка истекших токенов
• GetTokenStatisticsAsync() - получение статистики токенов

IProfileService

Сервис управления профилями пользователей:

• GetProfileAsync() - получение полного профиля
• UpdateProfileAsync() - обновление персонального профиля
• AddTelegramAccountAsync() - добавление Telegram аккаунта
• SetMainTelegramAccountAsync() - установка основного Telegram аккаунта

ITelegramService

Сервис для работы с Telegram интеграцией:

• GetTelegramUserAsync() - получение информации о Telegram пользователе
• UpdateTelegramUserAsync() - обновление данных Telegram пользователя
• DeactivateTelegramUserAsync() - деактивация Telegram пользователя
• ListTelegramUsersAsync() - список Telegram пользователей с пагинацией

Middleware

AuthClient предоставляет middleware для автоматической работы с токенами в ASP.NET Core приложениях:

app.UseAuthClient();

Middleware автоматически:

• Извлекает токен из заголовка Authorization
• Проверяет необходимость обновления токена
• Автоматически обновляет токен при необходимости
• Добавляет токен в HttpContext.Items для дальнейшего использования

Обработка ошибок

Все методы возвращают результаты с полем Success:

var result = await _authService.LoginAsync(username, password, serviceId);

if (!result.Success)
{
    // Обработка ошибки
    Console.WriteLine($"Ошибка: {result.ErrorMessage}");
}

Библиотека также определяет специфичные исключения:

• AuthClientException - базовое исключение
• AuthenticationException - ошибки аутентификации
• AuthorizationException - ошибки авторизации
• ConfigurationException - ошибки конфигурации
• ServerCommunicationException - ошибки связи с сервером
• TokenStorageException - ошибки хранилища токенов

Примеры использования

Для детальных примеров использования всех сервисов и сценариев см. usage_examples.md

История изменений

См. CHANGELOG.md для подробной истории изменений.

Лицензия

MIT License

Ссылки

• NuGet Package