SYW.Auth

ASP.NET Core authentication and authorization helpers for Authentik-backed SYW applications.

Provides:

• AddSywAuth() — one-call JWT Bearer + group-policy setup
• GroupRequirement / GroupHandler — policy enforcement via Authentik group claims
• ClaimsPrincipalExtensions — typed helpers for reading sub, name, email, groups from JWT claims

Installation

dotnet add package SYW.Auth --source https://nuget.sywapps.com/v3/index.json

Or add to nuget.config:

<configuration>
  <packageSources>
    <add key="syw-nuget" value="https://nuget.sywapps.com/v3/index.json" />
  </packageSources>
</configuration>

Target framework: net8.0 Dependencies: Microsoft.AspNetCore.Authentication.JwtBearer 8.x

Quick Start

Program.cs

using SYW.Auth;

// Register authentication + authorization
builder.Services.AddSywAuth(options =>
{
    options.Authority = builder.Configuration["Auth:Authority"]!;
    // e.g. "https://auth.sywapps.com/application/o/syw-music/"

    options.Audience = builder.Configuration["Auth:Audience"]!;
    // e.g. "syw-music"

    options.Policies.Add(new SywGroupPolicy
    {
        Name   = "AdminOnly",
        Groups = ["syw-music-admin", "admin"],
    });
    options.Policies.Add(new SywGroupPolicy
    {
        Name   = "DownloadAccess",
        Groups = ["syw-music-download", "syw-music-admin", "admin"],
    });
});

// Pipeline (order matters)
app.UseAuthentication();
app.UseAuthorization();

appsettings.json

{
  "Auth": {
    "Authority": "https://auth.sywapps.com/application/o/syw-music/",
    "Audience": "syw-music"
  }
}

Protecting Endpoints

// Require any authenticated user
[Authorize]
[HttpGet("profile")]
public IActionResult Profile() { ... }

// Require membership in the AdminOnly policy
[Authorize(Policy = "AdminOnly")]
[HttpDelete("songs/{id}")]
public IActionResult DeleteSong(Guid id) { ... }

// Require the DownloadAccess policy
[Authorize(Policy = "DownloadAccess")]
[HttpGet("songs/{id}/download")]
public IActionResult Download(Guid id) { ... }

ClaimsPrincipal Extensions

Import SYW.Auth and use directly on User inside any controller or Minimal API handler.

using SYW.Auth;

[HttpPost("streams")]
public async Task<IActionResult> TrackStream([FromBody] TrackStreamRequest req)
{
    var userId   = User.GetUserId();           // sub claim
    var userName = User.GetUserName();         // name claim
    var email    = User.GetEmail();            // email claim
    var groups   = User.GetGroups();           // all groups[]
    var isAdmin  = User.IsInSywGroup("admin"); // quick group check

    // ...
}

Available Extension Methods

SywAuthOptions Reference

SywGroupPolicy

Behind a Reverse Proxy

If your app runs behind NGINX or another proxy, add forwarded-headers middleware before UseAuthentication() so the correct client IP is resolved:

var fwdOpts = new ForwardedHeadersOptions
{
    ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto,
};
fwdOpts.KnownNetworks.Clear();
fwdOpts.KnownProxies.Clear();
app.UseForwardedHeaders(fwdOpts);

app.UseAuthentication();
app.UseAuthorization();

What AddSywAuth Registers

AddSywAuth is a thin convenience wrapper. It calls:

1. services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme).AddJwtBearer(...) — configures token validation parameters from SywAuthOptions.
2. services.AddSingleton<IAuthorizationHandler, GroupHandler>() — registers the groups claim handler.
3. services.AddAuthorization(...) — registers each SywGroupPolicy as a named IAuthorizationPolicy.

If you need to customise JWT events beyond what AddSywAuth provides, call AddAuthentication().AddJwtBearer() manually and use GroupHandler / GroupRequirement directly.

Compatibility

• .NET 8+
• Authentik (any version with OIDC support)
• Works with controllers, Minimal APIs, and SignalR hubs