JWT Authentication Skill

Sorcha uses JWT Bearer authentication with the Tenant Service as the token issuer. All services validate tokens using shared JwtSettings from Sorcha.ServiceDefaults . Tokens support three types: user (email/password), service (client credentials), and delegated (service acting on behalf of user).

Quick Start

Service Authentication Setup

// Program.cs - Any Sorcha service var builder = WebApplication.CreateBuilder(args);

// 1. Add JWT authentication (shared key auto-generated in dev) builder.AddJwtAuthentication();

// 2. Add service-specific authorization policies builder.Services.AddBlueprintAuthorization();

var app = builder.Build();

// 3. CRITICAL: Order matters! app.UseAuthentication(); app.UseAuthorization();

app.MapBlueprintEndpoints(); app.Run();

Protect an Endpoint

// Minimal API pattern group.MapPost("/", CreateBlueprint) .WithName("CreateBlueprint") .RequireAuthorization("CanManageBlueprints");

Key Concepts

Concept Usage Example

Token Types Differentiate user vs service token_type claim: "user" or "service"

Organization Scope Isolate tenant data org_id claim in token

Signing Key Symmetric HMAC-SHA256 Auto-generated in dev, Azure Key Vault in prod

Token Lifetime Configurable per type Access: 60min, Refresh: 24hr, Service: 8hr

Common Patterns

Custom Authorization Policy

When: Endpoint requires specific claims beyond role-based auth.

// AuthenticationExtensions.cs options.AddPolicy("CanManageBlueprints", policy => policy.RequireAssertion(context => { var hasOrgId = context.User.Claims.Any(c => c.Type == "org_id" && !string.IsNullOrEmpty(c.Value)); var isService = context.User.Claims.Any(c => c.Type == "token_type" && c.Value == "service"); return hasOrgId || isService; }));

Extract Claims in Handler

When: Need user/org context in endpoint logic.

async Task<IResult> HandleRequest(ClaimsPrincipal user, ...) { var userId = user.FindFirst(JwtRegisteredClaimNames.Sub)?.Value; var orgId = user.FindFirst("org_id")?.Value;

if (string.IsNullOrEmpty(orgId))
    return Results.Forbid();

// Use orgId for data isolation

}

See Also

• patterns - Token generation, validation, policies

• workflows - Setup, testing, troubleshooting

Related Skills

• See the minimal-apis skill for endpoint configuration with .RequireAuthorization()

• See the aspire skill for shared configuration via ServiceDefaults

• See the redis skill for token revocation tracking

• See the yarp skill for gateway-level authentication

Documentation Resources

Fetch latest JWT/authentication documentation with Context7.

How to use Context7:

• Use mcp__context7__resolve-library-id to search for "asp.net core authentication jwt"

• Prefer website documentation (IDs starting with /websites/ ) over source code repositories

• Query with mcp__context7__query-docs using the resolved library ID

Recommended Queries:

• "JWT Bearer authentication setup"

• "authorization policies claims"

• "token validation parameters"