Реализация авторизации для Swagger в ASP.NET Core.

При создании приложений .NET вам часто потребуется создавать документацию по API. Для этого вы можете использовать Swagger — набор инструментов, который упрощает графическое представление вашего API. Вы можете протестировать методы API в пользовательском интерфейсе Swagger, как только станет доступна документация по API.

Если вам пригодится введение в Swagger, я предоставил его в предыдущей статье. В этой статье я расскажу, как реализовать базовую аутентификацию для Swagger. Для работы с примерами кода, представленными в этой статье, в вашей системе должна быть установлена ​​Visual Studio 2022. Если у вас еще нет копии, вы можете скачать Visual Studio 2022 здесь.

Создайте проект веб-API ASP.NET Core в Visual Studio 2022.

Прежде всего давайте создадим проект ASP.NET Core в Visual Studio 2022. Выполнив следующие действия, вы создадите новый проект веб-API ASP.NET Core в Visual Studio 2022:

1. Запустите интегрированную среду разработки Visual Studio 2022.
2. Нажмите «Создать новый проект».
3. В окне «Создать новый проект» выберите «ASP.NET Core Web API» из списка отображаемых шаблонов.
4. Нажмите “Далее.
5. В окне «Настроить новый проект» укажите имя и местоположение нового проекта.
6. При желании установите флажок «Поместить решение и проект в один каталог», в зависимости от ваших предпочтений.
7. Нажмите “Далее.
8. В следующем окне «Дополнительная информация» выберите .NET 6 (или более позднюю версию) в качестве целевой платформы из раскрывающегося списка вверху. Установите для параметра «Тип аутентификации» значение «Нет» (по умолчанию) и установите два последних флажка («Использовать контроллеры» и «Включить поддержку OpenAPI»).
9. Убедитесь, что флажки «Включить Docker» и «Настроить HTTPS» сняты, поскольку мы не будем здесь использовать эти функции.
10. Нажмите Создать.

Теперь у вас должен быть готов к работе новый проект веб-API ASP.NET Core. Мы будем использовать этот проект для реализации базовой аутентификации для Swagger в последующих разделах этой статьи.

Настройте Swagger для включения поддержки OpenAPI.

Спецификация OpenAPI, ранее известная как Спецификация Swagger, определяет стандартный, машиночитаемый, независимый от языка программирования язык описания интерфейса для API. Путем эффективного сопоставления всех ресурсов и процессов, связанных с API, определение Swagger устанавливает интерфейс RESTful для удобного проектирования и использования API.

Поскольку мы включили поддержку OpenAPI при создании проекта веб-API ASP.NET Core, пакет Swashbuckle.AspNetCore будет добавлен в проект автоматически. Swashbuckle — это проект с открытым исходным кодом, который позволяет создавать документацию Swagger в ASP.NET Core.

Если вы создали проект без включения поддержки OpenAPI, вам придется установить пакет Swashbuckle через консоль диспетчера пакетов NuGet, как показано ниже.

PM> Install-Package Swashbuckle.AspNetCore

Когда вы откроете файл Program.cs, вы должны увидеть следующий код.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}
app.UseAuthorization();
app.MapControllers();
app.Run();

Использование пользовательского интерфейса Swagger

Когда вы запустите приложение, вы должны увидеть пользовательский интерфейс Swagger, отображаемый в веб-браузере, как показано на рисунке 1 ниже.

ИДГ

Как видите, в пользовательском интерфейсе Swagger показан контроллер WeatherForecast, который создается по умолчанию при создании нового проекта API ASP.NET Core. В этом контроллере есть только один метод действия HttpGet.

Вы можете выполнить конечную точку без указания какой-либо аутентификационной информации, и выходные данные должны быть аналогичны рис. 2.

ИДГ

Вскоре мы узнаем, как реализовать аутентификацию для Swagger. Давайте сначала создадим новый контроллер API для проверки учетных данных пользователя и возврата веб-токена JSON (JWT), если учетные данные действительны.

Создайте контроллер входа в ASP.NET Core.

Создайте новый класс с именем LoginDTO в файле с тем же именем и расширением .cs. Теперь введите следующий код в новый файл LoginDTO.

    public class LoginDTO
    {
        public string UserName { get; set; }
        public string Password { get; set; }
    }

Создайте новый контроллер API с именем LoginController и вставьте следующий код.

    [Route("api/[controller]")]
    [ApiController]
    public class LoginController : ControllerBase
    {
        [HttpPost, Route("login")]
        public IActionResult Login(LoginDTO loginDTO)
        {
            try
            {
                if (string.IsNullOrEmpty(loginDTO.UserName) ||
                string.IsNullOrEmpty(loginDTO.Password))
                    return BadRequest("Username and/or Password not specified");
                if (loginDTO.UserName.Equals("joydip") &&
                loginDTO.Password.Equals("joydip123"))
                {
                    var secretKey = new SymmetricSecurityKey
                    (Encoding.UTF8.GetBytes("thisisasecretkey@123"));
                    var signinCredentials = new SigningCredentials
                    (secretKey, SecurityAlgorithms.HmacSha256);
                    var jwtSecurityToken = new JwtSecurityToken(
                        issuer: "ABCXYZ",
                        audience: "http://localhost:51398",
                        claims: new List<Claim>(),
                        expires: DateTime.Now.AddMinutes(10),
                        signingCredentials: signinCredentials
                    );
                    Ok(new JwtSecurityTokenHandler().
                    WriteToken(jwtSecurityToken));
                }
            }
            catch
            {
                return BadRequest
                ("An error occurred in generating the token");
            }
            return Unauthorized();
        }
    }

LoginController содержит только один метод действия HttpPost. Обратите внимание, как проверяются учетные данные пользователя и генерируется веб-токен JSON.

Аутентификация пользовательского интерфейса Swagger в ASP.NET Core

Чтобы реализовать аутентификацию для Swagger, напишите следующий код в классе Program.

builder.Services.AddSwaggerGen(option =>
{
    option.SwaggerDoc("v1", new OpenApiInfo { Title = "Demo API", Version = "v1" });
    option.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        In = ParameterLocation.Header,
        Description = "Please enter a valid token",
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        BearerFormat = "JWT",
        Scheme = "Bearer"
    });
    option.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type=ReferenceType.SecurityScheme,
                    Id="Bearer"
                }
            },
            new string[]{}
        }
    });
});

Примените атрибут Authorize в ASP.NET Core.

Затем примените атрибут Authorize к методу действия HttpGet WeatherController, как показано в фрагменте кода, приведенном ниже.

[HttpGet(Name = "GetWeatherForecast"), Authorize]
public IEnumerable<WeatherForecast> Get()
{
   return Enumerable.Range(1, 5).Select(index => new WeatherForecast
   {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
   })
   .ToArray();
}

При применении атрибута авторизации для выполнения этой конечной точки в Swagger теперь потребуется токен аутентификации.

ИДГ

Создайте токен JWT в ASP.NET Core.

Теперь выполните метод действия HttpPost LoginController и укажите учетные данные, как показано на рисунке 4.

ИДГ

Наконец, вы можете снова выполнить ту же конечную точку в пользовательском интерфейсе Swagger после указания токена аутентификации. На этот раз конечная точка будет работать, и вы сможете увидеть результат в пользовательском интерфейсе Swagger.

Swashbuckle — отличный инструмент для создания документов Swagger для ваших API-интерфейсов ASP.NET Core. Его довольно легко настроить и настроить. Вы также можете использовать Swashbuckle и Swagger с минимальными API в ASP.NET Core.