Asymmetric Authentication Nuget Package

Guest accounts

The auth service issues guest accounts for players who are not logged in. Their JWT carries the claim "guest": true; regular accounts do not have this claim.

AddAsymmetricAuthentication registers the guest policies for you (GuestPolicy.AddGuestPolicies):

• Default policy ([Authorize], [Authorize(AuthenticationSchemes = ...)] without Policy, RequireAuthorization() without argument): authenticated users only, guests get 403.
• GuestPolicy.AllowGuests: any authenticated user, guests included.

The JWT Bearer scheme is registered as the default scheme, so a plain [Authorize] is enough: no need to specify AuthenticationSchemes.

Endpoints open to guests must opt in explicitly.

Controllers

using Terranaut.AsymmetricAuthentication;

[ApiController]
[Route("games")]
public class GamesController : ControllerBase
{
    [HttpGet]
    [Authorize(Policy = GuestPolicy.AllowGuests)]   // users + guests
    public IActionResult List() => Ok();

    [HttpPost]
    [Authorize]                                      // users only, guests get 403
    public IActionResult Create() => Ok();

    [HttpGet("public")]
    [AllowAnonymous]                                 // everyone, even without a token
    public IActionResult Public() => Ok();
}

Minimal APIs

app.MapGet("/games", ListGames).RequireAuthorization(GuestPolicy.AllowGuests); // guests allowed
app.MapPost("/games", CreateGame).RequireAuthorization();                     // guests get 403

Pitfalls

• Authorization attributes add up (logical AND). With [Authorize] on the controller and [Authorize(Policy = GuestPolicy.AllowGuests)] on an action, both policies apply, so guests are still refused by the default policy. To open some actions to guests, either put [Authorize] on each action instead of on the class, or put AllowGuests on the class and [Authorize] on the actions reserved for regular users:

  [Authorize]                                        // ❌ guests refused everywhere
  public class LobbyController : ControllerBase
  {
      [Authorize(Policy = GuestPolicy.AllowGuests)]  // has no effect for guests
      public IActionResult Join() => Ok();
  }
  
  [Authorize(Policy = GuestPolicy.AllowGuests)]      // ✅ guests allowed by default here
  public class LobbyController : ControllerBase
  {
      public IActionResult Join() => Ok();           // users + guests
  
      [Authorize]
      public IActionResult Delete() => Ok();         // users only
  }
  

• An endpoint without any authorization attribute is open to everyone, even without a token: the package does not set a FallbackPolicy. "Guests refused by default" only applies to endpoints that have [Authorize] / RequireAuthorization(). Don't forget to protect your endpoints.

Changelog

1.0.4

• Breaking behavior change: guests are now refused by default. Every endpoint that guests must reach (lobby creation, solo game, …) has to use GuestPolicy.AllowGuests, otherwise guests get 403 there.
• Added GuestPolicy (ClaimName, AllowGuests, AddGuestPolicies).