Phoesion.DevJwt 1.0.1

Phoesion.DevJwt

Library and dotnet-tool for developing and testing JWT-protected web API services. Create and validate custom tokens that can be used locally, without an external authority.

How to use in your service

1. Install the dotnet tool

dotnet tool install --global phoesion.devjwt.cli

2. Generate token using

dotnet devjwt create myApi --email user@mail.com

3. Configure in appsetting.Development.json

"Authentication": {
   "Schemes": {
      "Bearer": {
         "ValidAudience": "myApi",
         "ValidIssuer": "phoesion.devjwt",
         "SigningKeys": [
          {
             "Issuer": "phoesion.devjwt",
             "Value": "c29tZV9kZWZhdWx0X2tleV9mb3JfZGV2c18yNTZiaXQ="
          }
         ]
      }
   }
}

4. You can now use the token for your requests.

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

Samples

The repository contains the following samples projects in the Samples folder :

• SampleWebApi : an ASP.Net core web API application (net7.0 and above)
• SampleWebApi_Older : an ASP.Net core web API application (net6.0 and net5.0)
• SampleGlowMicroservice : a Phoesion Glow microservice
• TokenGeneratorSample : a console application that demonstrates how to generate token programmatically

Custom signing key

By default, the generator and validator use a predefined key for signing/verifying the token. This way it will pass validation and you don't need to care about where/how the token was generated (doesn't use UserSecrets store), which is fine since it's for local development and testing.

You can however generate/validate tokens using a custom key like so :

• In the tool specify a key to be used for signing the token using the --signkey parameter :

dotnet devjwt create myApi --email user@mail.com --sub 42 --signkey thiskeyisverylargetobreak

• Encode the key in base64 format (so you can add it in your appsettings.Development.json)

dotnet devjwt encode-key thiskeyisverylargetobreak

• Add the key in your appsettings.Development.json

"Authentication": {
   "Schemes": {
      "Bearer": {
         "ValidAudience": "myApi",
         "ValidIssuer": "phoesion.devjwt"
         "SigningKeys": [
          {
             "Issuer": "phoesion.devjwt",
             "Value": "dGhpc2tleWlzdmVyeWxhcmdldG9icmVhaw==" // <-- Set your new encoded key here
          }
         ]
      }
   }
}

Generate tokens programmatically

You can also generate tokens programmatically using the TokenGenerator

1. Add the NuGet package to your project

dotnet add package Phoesion.DevJwt

2. Use TokenGenerator

string userId = new Guid().ToString();
string email = "john.doe@example.com";
string audience = "myApi";

var token = TokenGenerator.Create(audience, email, userId)
                          .AddScope("openid", "profile")
                          .AddRole("admin")
                          .AddClaim("username", "johndoe")
                          .ExpiresIn(TimeSpan.FromDays(365))
                          .Build();

How to use in net6.0 and net5.0 projects

1. Add the NuGet package to your web API project

dotnet add package Phoesion.DevJwt

2. Enable dev-jwt on your JWT authorization services using the UseDevJwt() extension

services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
        .AddJwtBearer(o => o.UseDevJwt(builder.Environment));

Notes : it only enables in 'Development' and 'Testing' environments

3. Configure in appsetting.Development.json

"Authentication": {
   "Schemes": {
      "Bearer": {
         "ValidAudience": "myApi",
         "ValidIssuer": "phoesion.devjwt"
      }
   }
}