AIDeskLab.AuthClient

Версия 3.0 - Внедрение AutoMapper для оптимизации маппинга 🚀

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

Новое в версии 3.0:

🔄 Внедрен AutoMapper для централизованного маппинга (17 профилей)
⚡ Оптимизирована производительность конвертации данных
🧹 Устранено дублирование кода (удалено 29+ методов ручного маппинга)
🎯 Улучшена поддерживаемость и тестируемость кода
✅ Автоматическая валидация конфигурации маппинга в DEBUG режиме

Версия 2.0:

✨ 11 новых сервисов (роли, организации, отделы, модули, контрагенты, аналитика)
🚀 100% покрытие всех gRPC методов AuthServer (~130 методов)
📊 Полная система аналитики и мониторинга
🏢 Управление организационной структурой
📚 Расширенная документация с workflows и best practices

Возможности

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

Аутентификация пользователей - поддержка различных методов входа (логин/пароль, 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

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

Параметр	Тип	Обязательный	По умолчанию	Описание
`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() - получение статистики токенов

IProfileService

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

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

ITelegramService

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

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

IRoleService ⭐ НОВЫЙ СЕРВИС

Сервис управления ролями (legacy):

CreateRoleAsync() - создание новой роли
GetRoleAsync() - получение роли по ID
UpdateRoleAsync() - обновление роли
DeleteRoleAsync() - удаление роли
ActivateRoleAsync() - активация роли
DeactivateRoleAsync() - деактивация роли
ListRolesAsync() - список ролей с пагинацией

Примечание: Рекомендуется использовать ISystemRoleService и IOrganizationRoleService вместо этого сервиса для новых проектов.

ISystemRoleService ⭐ НОВЫЙ СЕРВИС

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

CreateSystemRoleAsync() - создание системной роли
GetSystemRoleAsync() - получение системной роли
GetSystemRoleByCodeAsync() - получение роли по коду
UpdateSystemRoleAsync() - обновление системной роли
DeactivateSystemRoleAsync() - деактивация роли
ActivateSystemRoleAsync() - активация роли
GetAllSystemRolesAsync() - получение всех системных ролей
AssignPermissionToSystemRoleAsync() - назначение разрешения
RemovePermissionFromSystemRoleAsync() - удаление разрешения
GetSystemRolePermissionsAsync() - получение разрешений роли
AssignSystemRoleToServiceAsync() - назначение роли сервису
RemoveSystemRoleFromServiceAsync() - удаление роли у сервиса

Особенности:

Поддержка двухфакторной аутентификации на уровне роли
Привязка ролей к сервисам
Глобальные роли для всей системы

IOrganizationRoleService ⭐ НОВЫЙ СЕРВИС

Сервис управления организационными ролями:

CreateOrganizationRoleAsync() - создание организационной роли
GetOrganizationRoleAsync() - получение роли по ID
UpdateOrganizationRoleAsync() - обновление роли
DeactivateOrganizationRoleAsync() - деактивация роли
ActivateOrganizationRoleAsync() - активация роли
GetOrganizationRolesAsync() - получение ролей организации
AssignPermissionToRoleAsync() - назначение разрешения
RemovePermissionFromRoleAsync() - удаление разрешения
GetRolePermissionsAsync() - получение разрешений роли

Особенности:

Роли специфичны для конкретной организации
Поддержка двухфакторной аутентификации
Глобальные роли-шаблоны (могут копироваться в организации)

IPermissionService ⭐ НОВЫЙ СЕРВИС

Сервис управления разрешениями:

CreatePermissionAsync() - создание разрешения
GetPermissionAsync() - получение разрешения по ID
UpdatePermissionAsync() - обновление разрешения
DeletePermissionAsync() - удаление разрешения
ListPermissionsAsync() - список разрешений
AssignPermissionToRoleAsync() - назначение разрешения роли
RemovePermissionFromRoleAsync() - удаление разрешения у роли
GetRolePermissionsAsync() - получение разрешений роли

IUserRoleService ⭐ НОВЫЙ СЕРВИС

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

AssignRoleToUserAsync() - назначение роли пользователю
RemoveRoleFromUserAsync() - удаление роли у пользователя
GetUserRolesAsync() - получение ролей пользователя

IOrganizationService ⭐ НОВЫЙ СЕРВИС

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

CreateOrganizationAsync() - создание организации
GetOrganizationAsync() - получение организации
UpdateOrganizationAsync() - обновление организации
ActivateOrganizationAsync() / DeactivateOrganizationAsync() - управление статусом
DeleteOrganizationAsync() - удаление организации
ListOrganizationsAsync() - список организаций с фильтрацией
GetChildOrganizationsAsync() - получение дочерних организаций
SetParentOrganizationAsync() - установка родительской организации
GetOrganizationUsersAsync() - получение пользователей организации

IUserOrganizationService ⭐ НОВЫЙ СЕРВИС

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

AddUserToOrganizationAsync() - добавление пользователя в организацию
RemoveUserFromOrganizationAsync() - удаление пользователя из организации
GetUserOrganizationsAsync() - получение организаций пользователя
SetUserPrimaryOrganizationAsync() - установка основной организации
GetUserServiceAccessAsync() - детальная информация о доступах к сервисам

IUserAssignmentService ⭐ НОВЫЙ СЕРВИС

Сервис управления назначениями пользователей (должности в организациях):

CreateUserAssignmentAsync() - создание назначения
UpdateUserAssignmentAsync() - обновление назначения
ArchiveUserAssignmentAsync() - архивирование назначения
DeactivateUserAssignmentAsync() - деактивация назначения
GetUserAssignmentsAsync() - получение назначений пользователя
GetOrganizationAssignmentsAsync() - получение назначений организации
SetPrimaryAssignmentAsync() - установка основного назначения

IDepartmentService ⭐ НОВЫЙ СЕРВИС

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

CreateDepartmentAsync() - создание отдела
GetDepartmentAsync() - получение отдела
UpdateDepartmentAsync() - обновление отдела
ActivateDepartmentAsync() / DeactivateDepartmentAsync() - управление статусом
DeleteDepartmentAsync() - удаление отдела
ListDepartmentsAsync() - список отделов организации
GetChildDepartmentsAsync() - получение дочерних отделов
GetRootDepartmentsAsync() - получение корневых отделов
GetDepartmentHierarchyAsync() - получение иерархии
GetDepartmentPathAsync() - получение пути отдела
GetDepartmentUsersAsync() - получение пользователей отдела

IServiceManagementService ⭐ НОВЫЙ СЕРВИС

Сервис управления сервисами:

RegisterServiceAsync() - регистрация нового сервиса
GetServiceAsync() - получение сервиса
UpdateServiceAsync() - обновление сервиса
ActivateServiceAsync() / DeactivateServiceAsync() - управление статусом
ListServicesAsync() - список сервисов
RegenerateCredentialsAsync() - генерация новых учетных данных
AssignPermissionToServiceAsync() - назначение разрешения сервису
RemovePermissionFromServiceAsync() - удаление разрешения
GetServicePermissionsAsync() - получение разрешений сервиса
GetServiceUsageStatsAsync() - статистика использования

IServiceModuleService ⭐ НОВЫЙ СЕРВИС

Сервис управления модулями сервисов:

Базовые операции: Create, Get, Update, Delete, Activate, Deactivate, List
Фильтрация: GetByType, GetByCategory, GetByService
Управление связями: Link, Unlink, UpdateLink, GetLink, ListLinks

ICounterpartyService ⭐ НОВЫЙ СЕРВИС

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

Базовые операции: Create, Get, Update, Activate, Deactivate, Delete
Поиск: List, Search, GetByJurisdiction
Контакты: Add, Update, Delete, GetContacts
Юрисдикция: GetJurisdictionData, UpdateJurisdictionData

IAccessLogService ⭐ НОВЫЙ СЕРВИС

Сервис логирования и статистики доступа:

GetAccessLogsAsync() - получение логов с фильтрацией
GetAccessLogsByUserAsync() - логи по пользователю
GetAccessLogsByServiceAsync() - логи по сервису
GetAccessStatisticsAsync() - статистика доступа
GetTopUsersByActivityAsync() - топ активных пользователей
GetTopServicesByUsageAsync() - топ используемых сервисов
GetErrorStatisticsAsync() - статистика ошибок
CleanupOldLogsAsync() - очистка старых логов

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 для подробной истории изменений.

Версия 2.0 (2024-10-31):

11 новых сервисов
100% покрытие AuthServer API
Расширенная документация
Дополнительные 100+ методов

Лицензия

MIT License

Ссылки

NuGet Package

No packages depend on AIDeskLab.AuthClient.

.NET 8.0

AIDesk.AuthServer.Contracts (>= 2.0.0)
AutoMapper (>= 12.0.1)
AutoMapper.Extensions.Microsoft.DependencyInjection (>= 12.0.1)
Google.Protobuf (>= 3.28.3)
Grpc.Net.Client (>= 2.70.0)
Microsoft.AspNetCore.Authentication.JwtBearer (>= 8.0.0)
Microsoft.Extensions.Caching.Memory (>= 9.0.3)
Microsoft.Extensions.Configuration.Abstractions (>= 9.0.3)
Microsoft.Extensions.DependencyInjection.Abstractions (>= 9.0.3)
Microsoft.Extensions.Http (>= 9.0.3)
Microsoft.Extensions.Logging.Abstractions (>= 9.0.3)
Microsoft.Extensions.Options.ConfigurationExtensions (>= 9.0.3)
Microsoft.IdentityModel.Tokens (>= 8.14.0)
System.IdentityModel.Tokens.Jwt (>= 8.14.0)

Version	Downloads	Last updated
2.0.0	1	01/14/2026

AIDeskLab.AuthClient 2.0.0

Readme