Table of Contents

Actor-Type Claim Trust Boundary

HttpContextGovernanceActorContextResolver can map an authenticated principal into an AsiBackbone actor context. That mapping is an audit and governance classification aid; it does not authenticate the caller, authorize an operation, or prove that the caller is a trusted system, service, or agent.

Trust requirement

HttpGovernanceActorContextOptions.ActorTypeClaimType must reference a claim that is protected by the host identity boundary.

Appropriate sources include:

  • a claim issued by a trusted identity provider under a validated token-signing and issuer policy;
  • a claim generated by the host after its own authentication and service-identity checks;
  • a claim added by a trusted claims-transformation component that cannot be influenced by request data.

Do not map actor type from:

  • request headers, query values, route values, form fields, or request bodies;
  • user-editable profile or registration data;
  • arbitrary scopes or roles whose values callers can request or influence;
  • unsigned external metadata;
  • claims copied from an upstream token without validating issuer, audience, signature, and claim provenance.

A caller-controlled actor_type=System value must never be treated as evidence that the caller is a trusted system process.

Conservative default

The default AllowedActorTypesFromClaims contains only Human.

Therefore, the following claim values fall back to DefaultAuthenticatedActorType unless the host explicitly allows them:

  • System
  • Service
  • Agent
  • Unknown
  • unrecognized or undefined enum values

This preserves a conservative HTTP edge boundary. It prevents an authenticated caller from self-classifying into a privileged software-actor category merely because a claim with a matching enum name is present.

Explicit opt-in

A host may enable trusted service or agent classification after establishing claim provenance:

builder.Services.AddAsiBackboneAspNetCore(options =>
{
    options.ActorTypeClaimType = "trusted_actor_type";
    options.AllowedActorTypesFromClaims =
    [
        GovernanceActorType.Human,
        GovernanceActorType.Service,
        GovernanceActorType.Agent,
    ];
});

Enable System only when the host can prove that the claim is created for a tightly controlled internal identity. A System result uses the framework's canonical system actor context, so accidental acceptance can distort audit attribution more severely than a normal display-name mismatch.

An empty AllowedActorTypesFromClaims collection disables actor-type claim mapping entirely and always uses DefaultAuthenticatedActorType for authenticated principals with a stable actor identifier.

Boundary with authorization

Actor type is descriptive governance context. Hosts must still apply normal ASP.NET Core authentication and authorization, resource checks, policy evaluation, capability validation, and execution-gateway controls.

Do not write authorization rules that assume ActorType == Service, System, or Agent is sufficient proof of privilege unless the host has independently established and documented the identity and claim trust chain.

  • validate token signatures, issuer, and audience before claims are consumed;
  • use a dedicated, namespaced claim type rather than a generic user profile field;
  • document which component emits the claim and which identities may receive each value;
  • test that unrecognized and disallowed values fall back safely;
  • monitor changes to identity-provider claim mappings;
  • keep privileged actor types out of end-user self-service configuration.

AsiBackbone validates enum membership and the configured allow-list. It cannot determine whether a claim issuer is trustworthy; that remains a host responsibility.

Edit this page