Administre JSON Web Tokens en desarrollo con dotnet user-jwts

Artículo
11/30/2023

La herramienta de línea de comandos de dotnet user-jwts puede crear y administrar JS ON Web Tokens locales específicos de la aplicación (JWT).

Sinopsis

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

Descripción

Crea y administra JSON Web Tokens específicos del proyecto.

Argumentos

PROJECT | SOLUTION

Proyecto de MSBuild en el que se va a aplicar un comando. Si no se especifica un proyecto, MSBuild busca en el directorio de trabajo actual un archivo que tenga una extensión de archivo que termine en proj y usa ese archivo.

Comandos:

Command	Descripción
clear	Eliminar todos los JWT emitidos para un proyecto.
create	Emitir un nuevo JSON Web Token.
remove	Eliminar un JWT determinado.
key	Mostrar o restablecer la clave de firma usada para emitir JWT.
list	Enumerar los JWT emitidos para el proyecto.
imprimir	Mostrar los detalles de un JWT determinado.

Crear

Uso: dotnet user-jwts create [options]

Opción	Descripción
-p \| --project	La ruta de acceso del proyecto sobre el que actuar. El valor predeterminado es el proyecto en el directorio actual.
--scheme	Nombre del esquema que se va a usar para el token generado. El valor predeterminado es "Portador".
-n \| --name	Nombre del usuario para el que se va a crear el JWT. El valor predeterminado es el usuario del entorno actual.
--audience	Público para el que se va a crear el JWT. El valor predeterminado son las direcciones URL configuradas en el archivo launchSettings.json del proyecto.
--issuer	Emisor del JWT. El valor predeterminado es "dotnet-user-jwts".
--scope	Notificación de ámbito que se va a agregar al JWT. Especificar una vez para cada ámbito.
--role	Notificación de rol que se va a agregar al JWT. Especificar una vez para cada rol.
--claim	Notificaciones que se van a agregar al JWT. Especificar una vez para cada notificación con el formato "name=value".
--not-before	La fecha y hora UTC en la que el JWT no debe ser válido antes, debe estar en formato "aaaa-MM-dd [[HH:mm[[:ss]]]]". El valor predeterminado es la fecha y hora en la que se crea el JWT.
--expires-on	La fecha y hora UTC en la que el JWT debe expirar, debe estar en el formato "aaaa-MM-dd [[[ [HH:mm]]:ss]]". El valor predeterminado es de 6 meses después de la fecha --not-before. No use esta opción junto con la opción --valid-for.
--valid-for	El período tras el cual debe caducar el JWT. Especificar utilizando un número seguido de un tipo de duración como "d" para días, "h" para horas, "m" para minutos y "s" para segundos, por ejemplo 365d'. No use esta opción junto con la opción --expires-on.
-o \| --output	Formato que se va a usar para mostrar la salida del comando. Puede ser "default", "token" o "json".
-h \| --help	Mostrar información de ayuda.

Ejemplos

Ejecute los siguientes comandos para crear un proyecto web vacío y agregar el paquete NuGet Microsoft.AspNetCore.Authentication.JwtBearer:

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

Reemplace el contenido de Program.cs por el código siguiente:

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

En el código anterior, una solicitud GET a /secret devuelve un error 401 Unauthorized. Una aplicación de producción podría obtener el JWT de un servicio de token de seguridad (STS), quizás como respuesta al inicio de sesión mediante un conjunto de credenciales. Para trabajar con la API durante el desarrollo local, la herramienta de línea de comandos dotnet user-jwts se puede usar para crear y administrar JWT locales específicos de la aplicación.

La herramienta user-jwts es similar en concepto a la herramienta user-secrets, se puede utilizar para administrar valores para la aplicación que solo son válidos para el desarrollador en el equipo local. De hecho, la herramienta user-jwts utiliza la infraestructura de user-secrets para administrar la clave con la que se firman los JWT, garantizando que se almacena de forma segura en el perfil del usuario.

La herramienta user-jwts oculta los detalles de implementación, como dónde y cómo se almacenan los valores. La herramienta se puede usar sin conocer los detalles de implementación. Los valores se almacenan en un archivo JSON en la carpeta de perfil de usuario del equipo local:

Windows
Linux/macOS

Ruta del sistema de archivos:

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

Crear un JWT

El comando siguiente crea un JWT local:

dotnet user-jwts create

El comando anterior crea un JWT y actualiza el archivo appsettings.Development.json del proyecto con un JSON similar al siguiente:

{
  "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 el JWT y el ID creado en el comando anterior. Use una herramienta como Curl para probar el /secret:

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

Donde {token} es el JWT generado anteriormente.

Mostrar información de seguridad de JWT

El siguiente comando muestra la información de seguridad de JWT, incluida la expiración, los ámbitos, los roles, el encabezado y la carga del token, y el token compacto:

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

Crear un token para un usuario y un ámbito específicos

Consulte Crear en este tema para ver las opciones de creación admitidas.

El comando siguiente crea un JWT para un usuario denominado MyTestUser:

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

El comando anterior tiene una salida similar a la siguiente:

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

Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.{Remaining token deleted}

El token anterior se puede usar para probar el punto de conexión de /secret2 en el código siguiente:

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