Управление веб-токенами JSON в разработке с помощью dotnet user-jwts

Автор: Рик Андерсон (Rick Anderson)

Средство командной dotnet user-jwts строки может создавать и управлять конкретными локальными веб-маркерами JSON (JWTs).

Краткие сведения

dotnet user-jwts [<PROJECT>] [command]
dotnet user-jwts [command] -h|--help

Description

Создает и управляет определенными локальными веб-токенами JSON для проекта.

Аргументы

PROJECT | SOLUTION

Проект MSBuild для применения команды. Если проект не указан, MSBuild выполняет поиск текущего рабочего каталога для файла с расширением файла, который заканчивается proj и использует этот файл.

Команды

Команда	Description
clear	Удалите все выданные JWTs для проекта.
create	Выдача нового веб-токена JSON.
remove	Удаление заданного JWT.
key	Отображение или сброс ключа подписи, используемого для выдачи JWTs.
список	Выводит список JWTs, выданных для проекта.
…печать.	Отображение сведений о заданном JWT.

Создание

Использование: dotnet user-jwts create [options]

Вариант	Description
-p | --проект	Путь к проекту для работы. По умолчанию используется проект в текущем каталоге.
--схема	Имя схемы, используемое для созданного маркера. По умолчанию используется значение "Носитель".
-n | --имя	Имя пользователя для создания JWT. По умолчанию используется текущий пользователь среды.
--публика	Аудитории для создания JWT. По умолчанию URL-адреса, настроенные в launchSettings.json проекта.
--эмитент	Издатель JWT. По умолчанию используется значение dotnet-user-jwts.
--scope	Утверждение области для добавления в JWT. Укажите один раз для каждой области.
--role	Утверждение роли для добавления в JWT. Укажите один раз для каждой роли.
--требование	Утверждения для добавления в JWT. Укажите один раз для каждого утверждения в формате "name=value".
--not-до	Дата и время в формате UTC JWT не должно быть допустимым перед форматом "гггг-ММ-дд [[HH:mm[:ss]]]". По умолчанию используется дата и время создания JWT.
--срок действия истекает	Дата и время окончания срока действия JWT в формате y-MM-dd [[[ [[ [HH:mm]]:ss]". Значение по умолчанию — 6 месяцев после даты --not-до даты. Не используйте этот параметр в сочетании с параметром --valid-for.
--valid-for	Срок действия JWT должен истекать после. Укажите число, за которым следует тип длительности, например "d" в течение дней, "h" в течение нескольких часов, "m" в минутах и "s" в секундах, например 365d. Не используйте этот параметр в сочетании с параметром --expires-on.
-o | --выпуск	Формат, используемый для отображения выходных данных из команды. Может быть одним из значений по умолчанию, token или json.
-h | --Справка	Отображает справочные сведения.

Примеры

Выполните следующие команды, чтобы создать пустой веб-проект и добавить пакет NuGet Microsoft.AspNetCore.Authentication.JwtBearer :

dotnet new web -o MyJWT
cd MyJWT
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

Замените все содержимое Program.cs следующим кодом:

using System.Security.Claims;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();

var app = builder.Build();

app.UseAuthorization();

app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
    .RequireAuthorization();

app.Run();

В приведенном выше коде запрос GET возвращает /secret ошибку 401 Unauthorized . Производственное приложение может получить JWT из службы маркеров безопасности (STS), возможно, в ответ на вход с помощью набора учетных данных. Для работы с API во время локальной разработки dotnet user-jwts средство командной строки можно использовать для создания локальных JWT для конкретного приложения и управления ими.

Инструмент user-jwts похож на средство секретов пользователя, его можно использовать для управления значениями приложения, которые действительны только для разработчика на локальном компьютере. На самом деле средство user-jwts использует user-secrets инфраструктуру для управления ключом, подписанным JWTs, обеспечивая безопасное хранение в профиле пользователя.

Средство user-jwts скрывает сведения о реализации, например, где и как хранятся значения. Средство можно использовать без знания сведений о реализации. Значения хранятся в JSON-файле в папке профиля пользователя локального компьютера:

Windows

Путь к файловой системе:

%APPDATA%\Microsoft\UserSecrets\<secrets_GUID>\user-jwts.json

Linux или macOS

Путь к файловой системе:

~/.microsoft/usersecrets/<secrets_GUID>/user-jwts.json

Создание JWT

Следующая команда создает локальный JWT:

dotnet user-jwts create

Предыдущая команда создает JWT и обновляет файл проекта appsettings.Development.json с помощью JSON, аналогичного следующему:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "Authentication": {
    "Schemes": {
      "Bearer": {
        "ValidAudiences": [
          "http://localhost:8401",
          "https://localhost:44308",
          "http://localhost:5182",
          "https://localhost:7076"
        ],
        "ValidIssuer": "dotnet-user-jwts"
      }
    }
  }
}

Скопируйте JWT и ID созданный в предыдущей команде. Используйте средство, например Curl, чтобы проверить /secret:

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/secret

Где {token} находится ранее созданный JWT.

Отображение сведений о безопасности JWT

Следующая команда отображает сведения о безопасности JWT, включая срок действия, области, роли, заголовок маркера и полезные данные, а также компактный маркер:

dotnet user-jwts print {ID} --show-all

Создание маркера для конкретного пользователя и области

Сведения о поддерживаемых параметрах создания см . в разделе "Создание " в этом разделе.

Следующая команда создает JWT для пользователя с именем MyTestUser:

dotnet user-jwts create --name MyTestUser --scope "myapi:secrets"

Предыдущая команда имеет выходные данные, аналогичные следующему:

New JWT saved with ID '43e0b748'.
Name: MyTestUser
Scopes: myapi:secrets

Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.{Remaining token deleted}

Предыдущий маркер можно использовать для тестирования конечной /secret2 точки в следующем коде:

using System.Security.Claims;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();

var app = builder.Build();

app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
    .RequireAuthorization();
app.MapGet("/secret2", () => "This is a different secret!")
    .RequireAuthorization(p => p.RequireClaim("scope", "myapi:secrets"));

app.Run();