jwt（JWT 安全）

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

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:

1. Use mcp__context7__resolve-library-id to search for "asp.net core authentication jwt"
2. Prefer website documentation (IDs starting with /websites/) over source code repositories
3. Query with mcp__context7__query-docs using the resolved library ID

Recommended Queries:

• "JWT Bearer authentication setup"
• "authorization policies claims"
• "token validation parameters"