Documentation: Static Keys

[adeutscher]

I am considering using this this template as a basis for a service that uses static keys. The project wouldn't need complex permissions, just a flat key for an authorized user.

I am very happy with keeping authentication of the base template as JWT-based with different authorization permissions. It's still my go-to boilerplate answer for how I'd like to present my API usage. That said, a documentation markdown detailing the steps for static keys wouldn't go amiss.

[adeutscher]

Documenting Composer's 2 cents on the general issue. The final document to close this issue needs to be filtered through my own experience.

Prompt: I am considering using this ASP.NET template to create a service that accepts a static header value as a key for authentication rather than JWT tokens. Describe to me how I might go about doing this.

Composer Response

This section describes how to replace JWT bearer authentication with a static header value (API key) while keeping this template's authorization model.

Authorization vs. Authentication

Authentication and authorization remain separate:

• Authentication: the client proves it is a caller this API recognizes (valid API key in a configured header).
• Authorization: the authenticated caller's claims are checked against policies (permissions, GET-only rules, resource scoping, etc.).

Replacing JWT does not require rewriting controllers or bespoke [Authorize...] attributes. Those depend on claims on HttpContext.User, not on JWT specifically.

Logic Flow

1. The client sends a request with a static key in a configured header (for example X-Api-Key).
   • The API compares the header value to known keys using constant-time comparison.
   • Keys should live in environment variables or a secrets manager, not committed configuration.
   • On success, the handler builds a ClaimsPrincipal for that key.
2. The principal may be enriched by a transformer (optional).
   • Key -> roles: attach role claims and keep BespokeRolePermissionClaimsTransformation to map roles to permission claims via BespokeRolePermissionMap.
   • Key -> permissions: attach permission claims directly in the handler. The transformer no-ops when permissions are already present.
   • For customer-scoped endpoints, also set customer_id (BespokeAuthorizationClaims.CustomerId) on the principal.
3. Authorization policies are unchanged.
   • Policies still require authenticated users and specific permission claims.
   • Custom requirements (HTTP GET checks, customer/upload scoping) still apply.
   • Only the authentication scheme name changes: replace JwtBearerDefaults.AuthenticationScheme with your API key scheme in ConfigureApiPolicy.
4. Controllers and endpoints keep their existing authorization attributes.
   • Fallback policy behavior is unchanged.
   • Requests without a valid key fail authentication (401). Requests with a valid key but insufficient permissions fail authorization (403).

Recapped in reverse:

1. A controller/endpoint is assigned a policy, which is set up with requirements.
2. Requirements may use request properties or the request's identity (claims established by the API key handler).
3. The identity may be enriched by a transformer (for example mapping roles to permissions).

Implementation Outline

Configuration

Extend AuthenticationOptions (or add a sibling section) with:

• Header name (for example ApiKeyHeaderName)
• Key entries mapping each secret to roles, permissions, and optional customer_id

Authentication handler

Implement ApiKeyAuthenticationHandler : AuthenticationHandler<ApiKeyAuthenticationOptions> that:

• Reads the configured header from Request.Headers
• Validates against configured keys
• Returns AuthenticateResult.Success with a ClaimsIdentity, or AuthenticateResult.Fail otherwise

Register in ConsiderAddingAuthentication:

.AddAuthentication("ApiKey")
.AddScheme<ApiKeyAuthenticationOptions, ApiKeyAuthenticationHandler>("ApiKey", ...)

Authorization Wiring

In AuthorizationServiceCollectionExtensions.ConfigureApiPolicy, change:

.AddAuthenticationSchemes(JwtBearerDefaults.AuthenticationScheme)

to:

.AddAuthenticationSchemes("ApiKey")

Swagger

Replace the bearer JWT security definition with an API key scheme:

document.AddSecurity("ApiKey", [], new OpenApiSecurityScheme
{
    Type = OpenApiSecuritySchemeType.ApiKey,
    Name = "X-Api-Key",
    In = OpenApiSecurityApiKeyLocation.Header,
    Description = "Static API key for service-to-service calls."
});

Middleware

On Disabling Authentication

The same "fail closed" behavior applies. Authorization policies still run even if authentication middleware is not registered. Endpoints that require authorization will fail when authentication is disabled. This is intentional.
A static header off switch is no safer than disabling JWT. Prefer valid test keys in local configuration rather than turning authentication off for routine development.

Security Notes

Static header keys suit service-to-service or internal APIs. They differ from JWT in important ways:

• No built-in expiry. Plan explicit key rotation.
• Replayable. Anyone who captures the header can reuse it. Require HTTPS in production.
• Shared key, shared access. Prefer one key per integration with a tailored claim set.
• Logging. Do not log header values in access logs or APM.

Migration Strategies

When replacing JWT bearer authentication with a static header key, choose how the API key handler populates the caller's identity. The authorization layer (policies, bespoke attributes, resource scoping) stays the same in all cases. Only authentication and optional claim enrichment change.

Strategy	Handler emits	Transformer	Best when
Minimal change	role claims	Keep BespokeRolePermissionClaimsTransformation	You want the smallest diff and to reuse BespokeRolePermissionMap
Simplified	permission claims	Optional (no-op when permissions already present)	Each key maps to a fixed permission set and roles add no value
Resource-scoped	roles or permissions + customer_id	As above, depending on whether you emit roles	Callers must be limited to a single customer's data

Minimal change

The handler validates the header and attaches role claims to the principal, mirroring what a JWT would provide. BespokeRolePermissionClaimsTransformation continues to map those roles to permission claims via BespokeRolePermissionMap.

• Pros: Reuses existing role-to-permission logic. One place to define what each role may do.
• Cons: Two-step claim pipeline (roles, then permissions). Key configuration must use role names the map understands.

Simplified

The handler validates the header and attaches permission claims directly. BespokeRolePermissionClaimsTransformation sees existing permissions and returns without change.

• Pros: Straightforward mental model. No dependency on role names or the role map for key-based callers.
• Cons: Permission sets for each key must be maintained separately from BespokeRolePermissionMap unless you share a helper.

Resource-scoped

Same as minimal or simplified, but the handler also sets customer_id (BespokeAuthorizationClaims.CustomerId) on the principal. CustomerScopedResourceEnforcer and related policies use that claim to restrict access.

• Pros: Supports multi-tenant or per-integration isolation with distinct keys.
• Cons: Each key needs explicit scoping metadata in configuration. Admin or unrestricted access requires the appropriate permission claims (for example api:unrestricted).

Choosing a strategy

• Prefer minimal change if you are migrating from JWT and already rely on roles and BespokeRolePermissionMap.
• Prefer simplified if callers are fixed integrations with known, static permission sets.
• Add resource-scoped metadata whenever keys must not see data outside a single customer.

[adeutscher]

This comment logs Composer's 2 cents on actually storing the keys. Paraphrasing this time rather than copying in verbatim.

Suggestions:

• Strategy suggestions:
  • In general, treat the key like a password and store some flavour of hash rather than the plain value. Makes sense.
  • Suggests supporting configuration that maintains roles/user-ids so as not to break downstream authentication. Probably a bit more complex than the applied API that sparked this issue needs, but good to keep in mind and worth mentioning in the document that closes this issue.
• Storage suggestions:
  • Static secrets for low number of keys
  • Hashed keys in database (supports dynamic management)
    • Suggests storing KeyId, KeyHash, Salt values, role data, and revocation/expiry data.

For my applied project, I'm just thinking of an SQLite database.

[adeutscher]

Not super-relevant to this issue, but on reflection I think that my applied project is small enough that I don't even need SQLite. It's going to need some flavour of secret manager for an unrelated purpose anyways. Going go with .env file values expressed through Docker Secrets.

[adeutscher]

Upon reflection, I don't need static authentication in my project and I'm pivoting in another direction.

This issue stays open because the fundamental question of "but what if I need static keys" could still come up later, and the what-if should be documented.