klod68/auth-standards

---

name: auth-standards description: "Use when working with authentication, authorization, OAuth, JWT, identity, RBAC, claims, or secrets management in .NET projects. Provides domain-specific rules layered on top of base architectural standards."

Skill: Authentication & Authorization Standards

Identity

| Field | Value | |---|---| | Name | Authentication & Authorization Standards | | Domain | Security, Identity, Access Control | | Level | Feature | | Tags | auth, jwt, oauth, identity, rbac, claims |

When to Apply

Activate this skill when the task involves:

• Configuring authentication or authorization middleware
• JWT bearer token setup, validation, or refresh flows
• OAuth 2.0 / OpenID Connect integration
• Policy-based or resource-based authorization
• Claims transformation or identity providers
• Secrets management (Key Vault, user-secrets)

Rules

These rules layer on top of base architectural standards. On conflict, these win.

<!-- SHARED:rules/auth.md -->

Authentication & Authorization — Standards

Apply these rules in addition to _base.md for projects using authentication or authorization.

---

Authentication Configuration

• Configure authentication in Program.cs using AddAuthentication with explicit default scheme.
• JWT bearer: always validate Issuer, Audience, Lifetime, and IssuerSigningKey.
• Prefer asymmetric algorithms (RS256, ES256) over symmetric (HS256) for JWT signing.
• Cookie authentication: set HttpOnly = true, Secure = true, SameSite = Strict (or Lax for OAuth flows).
• Token lifetimes: access tokens ≤ 60 minutes, refresh tokens ≤ 14 days with absolute expiration.
• Store signing keys in Azure Key Vault or equivalent — never in appsettings.json or source code.

OAuth 2.0 / OpenID Connect

• Use Authorization Code flow with PKCE for all public clients (SPAs, mobile, CLI).
• Never use Implicit flow — it is deprecated.
• Validate id_token claims: iss, aud, exp, nonce.
• Store tokens server-side when possible — never in localStorage (use httpOnly cookies or BFF pattern).
• Configure AddOpenIdConnect with explicit Authority, ClientId, ResponseType = "code", and SaveTokens = true.

Authorization Patterns

• Prefer policy-based authorization over role-based: [Authorize(Policy = "CanEditOrders")] over [Authorize(Roles = "Admin")].
• Define policies in Program.cs using AddAuthorizationBuilder with explicit requirements.
• Implement resource-based authorization for owned data: inject IAuthorizationService and call AuthorizeAsync with the resource.
• Every endpoint declares its authorization requirement explicitly — never rely on global fallback alone.
• Use [AllowAnonymous] deliberately and sparingly — document why each anonymous endpoint is safe.

Claims-Based Identity

• Access claims via ClaimsPrincipal — never parse tokens manually in application code.
• Define claim type constants to avoid magic strings: public static class AppClaims { public const string TenantId = "tenant_id"; }.
• Transform external claims to application claims in IClaimsTransformation — keep application code provider-agnostic.
• Validate required claims in authorization handlers, not in controller actions.

Secrets Management

• Never commit secrets to source control — not in appsettings.json, *.cs, *.yml, or .env files.
• Development: use dotnet user-secrets (Secret Manager).
• Production: use Azure Key Vault, AWS Secrets Manager, or HashiCorp Vault.
• Connection strings: prefer Managed Identity over username/password.
• API keys: rotate regularly, set expiration, never pass in query strings.
• Add to .gitignore: appsettings.Development.json, appsettings.Local.json, .env, secrets.json.

Common Anti-Patterns

| Anti-Pattern | Fix | |---|---| | HS256 with short symmetric key in config | Use RS256 with asymmetric key from Key Vault | | Secrets in appsettings.json committed to VCS | Use user-secrets (dev) or Key Vault (prod) | | [Authorize] without specifying policy | Define explicit policy: [Authorize(Policy = "...")] | | Checking User.IsInRole("Admin") in action body | Create authorization policy with RequireRole or custom requirement | | localStorage.setItem("token", jwt) | Use httpOnly cookie or BFF pattern | | Missing ValidateLifetime = true in JWT config | Always validate token expiration | | Implicit flow for SPA | Use Authorization Code + PKCE | | Parsing JWT manually with JwtSecurityTokenHandler | Use ClaimsPrincipal from HttpContext.User | | Global [Authorize] without [AllowAnonymous] on health/status | Explicitly mark health endpoints as anonymous |

---

See Also

• api-design.md — RESTful conventions, HTTP methods, pagination, error responses
• minimal-api.md — Minimal API endpoint organization, handlers, filters, validation
• blazor.md — Blazor component design, state management, parameters, routing
• signalr.md — SignalR hub design, groups, streaming, authorization