S3.Box.Auth 1.0.0

S3.Box.Auth

Библиотека для аутентификации ASP.NET Core приложений с использованием API ключей.

Описание

S3.Box.Auth предоставляет простое и эффективное решение для защиты API endpoints с помощью API ключей. Библиотека включает в себя middleware для проверки заголовка X-API-Key и расширения для удобной интеграции в ASP.NET Core приложения.

Возможности

• 🔐 Аутентификация по API ключу через заголовок X-API-Key
• 🚫 Автоматическое отклонение запросов без валидного ключа
• 🔓 Исключения для определенных маршрутов (Scalar, OpenAPI)
• ⚡ Поддержка preflight запросов (OPTIONS)
• 🛠️ Простая интеграция через extension методы

Установка

NuGet Package

dotnet add package S3.Box.Auth

Требования

• .NET 9.0 или выше
• ASP.NET Core

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

1. Настройка конфигурации

Добавьте API ключ в ваш appsettings.json:

{
  "ApiKey": "your-secret-api-key-here"
}

2. Регистрация сервисов

В Program.cs или Startup.cs:

using s3.box.auth.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Добавление сервисов
builder.Services.AddApplicationReferences(builder.Configuration);

var app = builder.Build();

// Регистрация middleware
app.UseApiKeyMiddleware();

app.Run();

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

После настройки все запросы к вашему API должны включать заголовок X-API-Key с валидным ключом:

curl -H "X-API-Key: your-secret-api-key-here" https://your-api.com/endpoint

Исключения

Middleware автоматически пропускает следующие типы запросов:

• OPTIONS запросы (preflight для CORS)
• Scalar endpoints (/scalar/*)
• OpenAPI endpoints (/openApi/*)

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

Настройка API ключа

API ключ должен быть указан в конфигурации приложения:

{
  "ApiKey": "your-secret-api-key-here"
}

Переменные окружения

Для production окружения рекомендуется использовать переменные окружения:

export ApiKey="your-production-api-key"

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

Базовый пример

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddApplicationReferences(builder.Configuration);

var app = builder.Build();

// Middleware будет проверять API ключ для всех запросов
app.UseApiKeyMiddleware();

app.MapGet("/api/data", () => "Protected data");

app.Run();

С дополнительными middleware

var app = builder.Build();

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();

// API Key middleware
app.UseApiKeyMiddleware();

app.UseAuthorization();
app.MapControllers();

app.Run();

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

При отсутствии или неверном API ключе middleware возвращает:

• HTTP Status Code: 401 Unauthorized
• Response Body: "Unauthorized: Invalid or missing X-API-Key"

Безопасность

• API ключ должен быть достаточно длинным и случайным
• Используйте HTTPS в production окружении
• Не храните API ключи в исходном коде
• Регулярно ротируйте API ключи

Лицензия

MIT License

Автор

Sazonov Andrei

Версия

1.0.0