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 (ASP.NET Core / Web)

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();

1.1 Настройка в Program.cs (Generic Host / Console / Worker, non-web)

Пошаговый non-web bootstrap:

1. Создайте Generic Host через Host.CreateDefaultBuilder(args).
2. Зарегистрируйте AuthClient в ConfigureServices через services.AddAuthClient(context.Configuration).
3. Получайте нужные сервисы (IAuthenticationService, ITokenValidationService и т.д.) через DI в worker/service классах.
4. Не добавляйте UseAuthClient() - middleware работает только в ASP.NET Core pipeline.

using AuthClient.Extensions;
using AuthClient.Services.Interfaces;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureServices((context, services) =>
    {
        // Полная конфигурация (читает секцию AuthClient из IConfiguration)
        services.AddAuthClient(context.Configuration);

        // Эквивалентный вариант через явную секцию:
        // services.AddAuthClient(context.Configuration.GetSection("AuthClient"));
    })
    .Build();

using var scope = host.Services.CreateScope();
var tokenValidation = scope.ServiceProvider.GetRequiredService<ITokenValidationService>();

Для non-web приложений middleware UseAuthClient() не используется, так как нет ASP.NET Core pipeline.

1.2 Пример hosted service (Worker)

using AuthClient.Extensions;
using AuthClient.Services.Interfaces;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureServices((context, services) =>
    {
        services.AddAuthClient(context.Configuration);
        services.AddHostedService<PermissionProbeWorker>();
    })
    .Build();

await host.RunAsync();

public sealed class PermissionProbeWorker : BackgroundService
{
    private readonly ITokenValidationService _tokenValidation;

    public PermissionProbeWorker(ITokenValidationService tokenValidation)
    {
        _tokenValidation = tokenValidation;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var check = await _tokenValidation.CheckPermissionAsync(
            userId: "user-id",
            serviceId: "service-id",
            permissionCode: "users.read",
            cancellationToken: stoppingToken);

        Console.WriteLine($"Permission granted: {check.HasPermission}");
    }
}

В non-web сценариях UseAuthClient() не требуется и не используется.

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

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

Параметр	Тип	Обязательный	По умолчанию	Описание
ServerUrl	string	Да	-	URL gRPC сервера аутентификации
ServiceId	string	Да	-	ID вашего сервиса/приложения
OperationTimeout	TimeSpan	Нет	30 сек	Таймаут для операций
UseSsl	bool	Нет	true	Использовать SSL/TLS
ApiKey	string	Нет	null	API ключ для админ операций

TokenStorageOptions

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

Параметр	Тип	По умолчанию	Описание
StorageType	enum	InMemory	Тип хранилища: InMemory, File, SystemKeyStore, Custom
EncryptTokens	bool	true	Шифровать токены при хранении
EncryptionKey	string	-	Ключ шифрования (требуется если EncryptTokens = true)
FilePath	string	-	Путь к файлу (для StorageType = File)
KeyPrefix	string	"AuthClient"	Префикс ключей в системном хранилище
CacheDuration	TimeSpan	1 час	Время жизни кеша в памяти

TokenRefreshOptions

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

Параметр	Тип	По умолчанию	Описание
EnableAutoRefresh	bool	true	Включить автообновление токенов
RefreshCheckInterval	TimeSpan	1 мин	Интервал проверки токенов
RefreshBeforeExpiration	TimeSpan	5 мин	За сколько до истечения обновлять
MaxRefreshAttempts	int	3	Макс. попыток обновления
RefreshRetryDelay	TimeSpan	5 сек	Задержка между попытками
RefreshOnFirstUse	bool	true	Обновлять при первом использовании

RetryOptions

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

Параметр	Тип	По умолчанию	Описание
EnableRetry	bool	true	Включить повторные попытки
MaxRetryAttempts	int	3	Максимальное количество попыток
BaseDelay	TimeSpan	1 сек	Базовая задержка
MaxDelay	TimeSpan	30 сек	Максимальная задержка
Strategy	enum	ExponentialBackoff	Стратегия: Fixed, Linear, ExponentialBackoff
BackoffMultiplier	double	2.0	Множитель для экспоненциальной стратегии
UseJitter	bool	true	Использовать случайную задержку
MaxJitterPercent	int	20	Максимальный процент jitter (0-100)

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

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() - получение статистики токенов

ITokenValidationService

Сервис runtime-проверок токена и разрешений:

• ValidateTokenAsync(accessToken, serviceId, cancellationToken) - проверка валидности access token
• CheckPermissionAsync(userId, serviceId, permissionCode, organizationId?, cancellationToken) - проверка конкретного разрешения пользователя (organizationId опционален)
• GetUserAvailableServicesAsync(userId, cancellationToken) - список доступных сервисов пользователя
• GetTokenInfoAsync(tokenId, cancellationToken) - информация о токене

Актуальная сигнатура CheckPermissionAsync включает 5 параметров:

Task<PermissionCheckResult> CheckPermissionAsync(
    string userId,
    string serviceId,
    string permissionCode,
    string? organizationId = null,
    CancellationToken cancellationToken = default);

IPermissionService используется для административного управления правами/ролями, а не как замена runtime-проверок в сценариях типа IsAdmin.

Рекомендованный вызов CheckPermissionAsync:

• Без organizationId (глобальная проверка в контексте сервиса):

var result = await tokenValidationService.CheckPermissionAsync(
    userId: userId,
    serviceId: serviceId,
    permissionCode: "users.read",
    cancellationToken: cancellationToken);

• С organizationId (org-scoped проверка в рамках конкретной организации):

var result = await tokenValidationService.CheckPermissionAsync(
    userId: userId,
    serviceId: serviceId,
    permissionCode: "users.read",
    organizationId: organizationId,
    cancellationToken: cancellationToken);

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();

Для Generic Host / Console / Worker сценариев middleware не требуется: используйте сервисы через DI после AddAuthClient(...).

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