Administre JSON Web Tokens en desarrollo con dotnet user-jwts
Por Rick Anderson
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:
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();