Gerencie Web Tokens JSON em desenvolvimento com dotnet user-jwts

Por Rick Anderson

A dotnet user-jwts ferramenta de linha de comandos pode criar e gerir Tokens Web JSON locais específicos da aplicação (JWTs).

Este artigo fornece detalhes da sintaxe do comando e exemplos.

Sinopse

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

Description

Cria e gere Tokens Web JSON locais específicos para projetos.

Arguments

PROJECT | SOLUTION

O projeto MSBuild sobre o qual aplicar um comando. Se um projeto não estiver especificado, o MSBuild procura no diretório de trabalho atual um ficheiro que tenha uma extensão de ficheiro que termine em proj. Depois, utiliza esse ficheiro para obter a informação do projeto para o comando.

Commands

Opções para o comando criar

Utilização: dotnet user-jwts create [options]

Examples

Execute os seguintes comandos para criar um projeto web vazio e adicionar o pacote NuGet Microsoft.AspNetCore.Authentication.JwtBearer :

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

Substitua o conteúdo do ficheiro Program.cs pelo seguinte código:

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

No código anterior, um pedido GET ao /secret endpoint devolve um 401 Unauthorized erro. Uma aplicação de produção pode obter o JWT de um serviço de token de segurança, talvez em resposta ao iniciar sessão com credenciais. Quando utiliza a API durante o desenvolvimento local, a dotnet user-jwts ferramenta de linha de comandos pode ser usada para criar e gerir JWTs locais específicos de uma aplicação.

A ferramenta user-jwts é semelhante, em termos conceptuais, à ferramenta user-secrets. Pode ser usado para gerir valores para a aplicação que são válidos apenas para o programador na máquina local. Na verdade, a ferramenta user-jwts utiliza a infraestrutura user-secrets para gerir a chave com a qual os JWTs são assinados. Esta abordagem garante que a chave é armazenada de forma segura no perfil do utilizador.

A user-jwts ferramenta esconde detalhes de implementação, como onde e como os valores são armazenados. A ferramenta pode ser usada sem conhecer os detalhes da implementação.

Os valores são armazenados em um arquivo JSON na pasta de perfil de usuário da máquina local:

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

• Linux/macOS: ~/.microsoft/usersecrets/<secrets_GUID>/user-jwts.json

Criar um JWT

O seguinte comando cria um JWT local:

dotnet user-jwts create

O comando anterior cria um JWT e atualiza o ficheiro do projeto appsettings.Development.json com JSON, semelhante ao seguinte exemplo:

{
  "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"
      }
    }
  }
}

Copie o JWT e o ID criado no comando anterior. Use uma ferramenta como o Curl para testar o /secret endpoint, onde {token} é o JWT previamente gerado:

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

Mostrar informação de segurança JWT

O comando seguinte apresenta a informação de segurança do JWT, incluindo expiração, escopos, funções, cabeçalho e carga útil do token, e o token compacto:

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

Crie um token para um utilizador específico e alcance

O comando seguinte cria um JWT para um utilizador chamado MyTestUser. Para as opções suportadas create, consulte a secção Opções do comando create.

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

O comando anterior tem uma saída semelhante ao seguinte exemplo:

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

Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.{Remaining token deleted}

O token anterior pode ser usado para testar o /secret2 endpoint no seguinte código:

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

Conteúdo relacionado

• Microsoft. AspNetCore.Authentication.JwtBearer
• JSON Web Tokens