jwt-auth
使用 Keycloak 为 affolterNET.Web.Api 配置 JWT 承载身份验证。在设置令牌验证、Keycloak 集成或 API 身份验证时使用。
📖 中文导读:使用 Keycloak 为 affolterNET.Web.Api 配置 JWT 承载身份验证。在设置令牌验证、Keycloak 集成或 API 身份验证时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: jwt-auth description: Configure JWT Bearer authentication with Keycloak for affolterNET.Web.Api. Use when setting up token validation, Keycloak integration, or API authentication.
JWT Bearer Authentication
Configure JWT Bearer authentication with Keycloak integration.
For complete reference, see Library Guide.
Quick Start
appsettings.json
{
"affolterNET": {
"Web": {
"Auth": {
"Provider": {
"Authority": "https://keycloak.example.com/realms/myrealm",
"ClientId": "my-api-client",
"ClientSecret": "your-client-secret"
}
}
}
}
}
Program.cs
var options = builder.Services.AddApiServices(isDev, builder.Configuration, opts => {
opts.ConfigureApi = api => {
api.AuthMode = AuthenticationMode.Authenticate;
};
});
Authentication Modes
| Mode | Description |
|---|---|
None |
No authentication required |
Authenticate |
Valid JWT required, no permission checks |
Authorize |
Valid JWT + Keycloak RPT permissions required |
Configuration Options
AuthProviderOptions
| Property | Description |
|---|---|
Authority |
Keycloak realm URL |
ClientId |
OIDC client identifier |
ClientSecret |
OIDC client secret |
Audience |
Expected JWT audience (optional) |
Permission-Based Authorization
When using AuthenticationMode.Authorize:
[Authorize(Policy = "admin-resource")]
[HttpGet("admin")]
public IActionResult AdminOnly() { ... }
// Multiple permissions (comma-separated, any match)
[Authorize(Policy = "resource1,resource2")]
[HttpGet("multi")]
public IActionResult MultiPermission() { ... }
Claims Enrichment
The API automatically enriches claims with:
- Standard JWT claims
- Aggregated roles from
ClaimTypes.Roleand"roles"claims - Permissions from RPT tokens (when AuthMode is Authorize)
Troubleshooting
Token validation fails
- Verify
AuthorityURL is correct and accessible - Check that
ClientIdmatches the Keycloak client - Ensure the JWT audience matches if configured
Permissions not recognized
- Confirm
AuthModeis set toAuthorize - Verify Keycloak client has authorization services enabled
- Check that resources and policies are configured in Keycloak