configuration.md

Configuration Reference

All configurable options across the AAuth .NET SDK, grouped by component.

Signature Verification

AAuthVerifier

Property	Type	Default	Description
MaxAge	TimeSpan	60 seconds	Maximum signature age before rejection
MaxFutureSkew	TimeSpan	5 seconds	Clock skew tolerance into the future
Clock	Func<DateTimeOffset>	UtcNow	Clock source (override for testing)

AAuthVerificationOptions (via UseAAuthVerification)

Property	Type	Default	Description
ResourceIdentifier	string?	null	Resource's own identifier for aud checks. When null, audience validation is skipped.
RequireIssuerVerification	bool	true	When true, verifies JWT signatures against the issuer's published JWKS via metadata discovery.
TrustedAgentProviderIssuers	IReadOnlySet<string>?	null	Optional allow-list of trusted AP issuers (null = any)
TrustedAuthTokenIssuers	IReadOnlySet<string>?	null	Fail-closed allow-list of trusted auth token (PS/AS) issuers. When null or empty, every auth token is rejected — set the issuers you trust to honor PS-asserted tokens.
MaxActDepth	int	10	Maximum delegation chain depth for nested act claims
ClockSkew	TimeSpan	30 seconds	Tolerance applied to exp/iat checks
MaxFutureSkew	TimeSpan	5 seconds	Maximum allowed skew into the future for HTTP signature timestamps
Clock	Func<DateTimeOffset>?	null (UtcNow)	Clock source for all time-dependent checks. Inject for deterministic testing.

AAuthResourceOptions (via AddAAuthResource)

Property	Type	Default	Description
Issuer	string	— (required)	HTTPS issuer URL for this resource
SigningKeys	Dictionary<string, AAuthKey>	{}	Key-id → signing key map
ClientName	string?	null	Human-readable resource name
ScopeDescriptions	Dictionary<string, string>?	null	Scope → description map for metadata
SignatureWindow	int?	null	Advertised signature validity (seconds)
AuthorizationEndpoint	string?	null	AS authorization URL
RevocationEndpoint	string?	null	Revocation endpoint URL

Token Builders

ResourceTokenBuilder

Property	Type	Default	Description
Lifetime	TimeSpan	5 minutes	Token validity duration
IssuedAt	DateTimeOffset?	Now	Override issuance timestamp
TokenId	string?	Auto (UUID)	Custom jti value

AuthTokenBuilder

Property	Type	Default	Description
Lifetime	TimeSpan	1 hour	Token validity duration
Dwk	string	"aauth-person.json"	Discovery well-known path
IssuedAt	DateTimeOffset?	Now	Override issuance timestamp
TokenId	string?	Auto (UUID)	Custom jti value

AgentTokenBuilder

Property	Type	Default	Description
Lifetime	TimeSpan	1 hour	Token validity duration
IssuedAt	DateTimeOffset?	Now	Override issuance timestamp
TokenId	string?	Auto (UUID)	Custom jti value

Token Verification

TokenVerifier

Property	Type	Default	Description
Clock	Func<DateTimeOffset>	UtcNow	Clock source
ClockSkew	TimeSpan	30 seconds	Tolerance for exp/iat validation
MaxActDepth	int	10	Maximum delegation chain depth

Deferred Consent (Polling)

DeferredPollerOptions

Property	Type	Default	Description
MaxTotalWait	TimeSpan	5 minutes	Maximum time to poll before timeout
DefaultPollInterval	TimeSpan	5 seconds	Base interval between polls
MinPollInterval	TimeSpan	100ms	Minimum interval floor
PreferWaitSeconds	int?	null	Send Prefer: wait=N header (long-poll)
OnPoll	Action<HttpResponseMessage>?	null	Callback after each poll response

Server Retry-After headers override DefaultPollInterval (clamped to MinPollInterval).

ChallengeHandlingOptions

Property	Type	Default	Description
OnInteractionRequired	Func<Interaction, CancellationToken, Task>?	null	Callback for 202+interaction
PollingTimeout	TimeSpan	5 minutes	Maximum polling time
DefaultPollInterval	TimeSpan	5 seconds	Interval between polls
PreferWaitSeconds	int?	null	Prefer: wait=N header value
MinPollInterval	TimeSpan	100ms	Minimum poll interval floor
OnPoll	Action<HttpResponseMessage>?	null	Callback after each poll

InteractionHandlingOptions

Property	Type	Default	Description
OnInteractionRequired	Func<string, string, CancellationToken, Task>?	null	Callback for 202+interaction (URL, code)
OnApprovalPending	Func<CancellationToken, Task>?	null	Callback for 202+approval
PollingTimeout	TimeSpan	5 minutes	Maximum polling time
DefaultPollInterval	TimeSpan	5 seconds	Interval between polls
PreferWaitSeconds	int?	null	Prefer: wait=N header value
MinPollInterval	TimeSpan	100ms	Minimum poll interval floor
OnPoll	Action<HttpResponseMessage>?	null	Callback after each poll

Discovery

MetadataClient

Parameter	Type	Default	Description
http	HttpClient	— (required)	HTTP client for fetching documents
cacheTtl	TimeSpan?	null (no expiry)	Cache entry lifetime
clock	Func<DateTimeOffset>?	UtcNow	Clock source for cache expiration

Methods:

• BuildUrl(issuer, dwk) — constructs .well-known/{dwk} URL from issuer
• FetchAsync(url) — fetches and caches the JSON document
• Invalidate(url) — evicts a cached entry

Resource Metadata

AAuthResourceMetadataOptions

Property	Type	Required	Description
Issuer	string	Yes	Resource canonical URL
SigningKeys	IReadOnlyDictionary<string, AAuthKey>	Yes	Key-id → signing key map
ClientName	string?	No	Human-readable resource name
ScopeDescriptions	IReadOnlyDictionary<string, string>?	No	Scope → description
SignatureWindow	int?	No	Advertised signature validity (seconds)
AuthorizationEndpoint	string?	No	AS authorization URL
RevocationEndpoint	string?	No	Revocation endpoint URL

Key Storage

FileKeyStore (File-Based)

Property/Method	Description
Directory	Storage directory path
Default()	Creates store at ~/.aauth/keys/
LoadOrCreate(name)	Load key or generate new Ed25519 key

DefaultSignatureKeyResolver

Parameter	Type	Default	Description
jwksClient	JwksClient?	null	Client for fetching JWKS endpoints

Signing (Agent-Side)

AAuthSigningHandler

Standard DelegatingHandler — no configurable options. Requires an ISignatureKeyProvider to supply the signing key and Signature-Key header value.

ISignatureKeyProvider Implementations

Provider	Constructor Parameters
HwkSignatureKeyProvider	IAAuthKey key
JwksUriSignatureKeyProvider	string uri, string kid
JwtSignatureKeyProvider	Func<string> tokenFactory
JktJwtSignatureKeyProvider	IAAuthKey ephemeralKey, Func<string> namingJwtFactory

Dependency Injection Options

AAuthAgentOptions (AddAAuthAgent)

Property	Type	Required	Description
Key	IAAuthKey	Yes	Agent signing key
BaseAddress	Uri?	No	Target resource URL
SignatureKeyProvider	ISignatureKeyProvider?	No	Custom signature key provider
PersonServer	string?	No	Person Server URL (for challenge handling)
ChallengeHandling	bool	No	Enable challenge handling
ChallengeHandlingOptions	Action<ChallengeHandlingOptions>?	No	Configure challenge handling behavior
InteractionHandling	bool	No	Enable interaction handling
InteractionHandlingOptions	Action<InteractionHandlingOptions>?	No	Configure interaction handling behavior
TokenRefresher	ITokenRefresher?	No	Custom token refresh logic
RefreshThreshold	TimeSpan?	No	Time before expiry to trigger refresh
Capabilities	string[]?	No	Agent capabilities to advertise
InnerHandler	HttpMessageHandler?	No	Custom inner HTTP handler
CallChainProvider	Func<string?>?	No	Provider for upstream auth token (call chaining)

AAuthResourceOptions (AddAAuthResource)

Property	Type	Required	Description
Issuer	string	Yes	Resource canonical URL
SigningKeys	Dictionary<string, AAuthKey>	Yes	Key-id → signing key map
ClientName	string?	No	Resource display name
ScopeDescriptions	Dictionary<string, string>?	No	Scope descriptions for metadata
SignatureWindow	int?	No	Advertised signature validity (seconds)
AuthorizationEndpoint	string?	No	AS authorization URL
RevocationEndpoint	string?	No	Revocation endpoint URL

AAuthDiscoveryOptions (AddAAuthDiscovery)

Property	Type	Default	Description
MetadataCacheTtl	TimeSpan	5 minutes	Metadata document cache lifetime
JwksCacheTtl	TimeSpan	1 hour	JWKS cache lifetime
JwksMinRefreshInterval	TimeSpan	1 minute	Minimum interval between JWKS fetches (rate limit)

ChallengeHandlingOptions (WithChallengeHandling)

Property	Type	Default	Description
OnInteractionRequired	Func<Interaction, CancellationToken, Task>?	null	Deferred consent callback
PollingTimeout	TimeSpan	5 minutes	Max deferred polling time
DefaultPollInterval	TimeSpan	5 seconds	Poll interval (overridden by Retry-After)
PreferWaitSeconds	int?	null	Sends Prefer: wait=N to long-poll
MinPollInterval	TimeSpan	100 ms	Minimum delay between polls
OnPoll	Action<HttpResponseMessage>?	null	Per-poll callback (logging/progress)
Capabilities	IList<string>?	null	Capabilities sent to the PS (null = infer)
Prompt	string?	null	OIDC prompt sent to the PS
AdditionalSignatureComponents	IReadOnlyDictionary<string, IReadOnlyList<string>>?	null	Per-origin extra covered components to seed

InteractionHandlingOptions (WithInteractionHandling)

Property	Type	Default	Description
OnInteractionRequired	Func<string, string, CancellationToken, Task>?	null	Interaction URL + code callback
OnApprovalPending	Func<CancellationToken, Task>?	null	Approval polling callback
PollingTimeout	TimeSpan	5 minutes	Max polling time

JSON Configuration Keys (samples)

The shipped samples bind a few AAuth:* keys from appsettings.json / environment variables / command line. These are conventions of the samples (not SDK-required), shown here as a reference for wiring your own hosts.

Key	Type	Used by	Description
AAuth:Issuer	string	WhoAmI, MockPersonServer, Orchestrator	The host's own canonical URL (resource/PS iss).
AAuth:SignatureWindow	int (seconds)	WhoAmI, MockPersonServer	Max HTTP-signature age accepted; default 60.
AAuth:TrustedPersonServers	string[]	WhoAmI	Fail-closed allow-list mapped to AAuthVerificationOptions.TrustedAuthTokenIssuers. When unset, defaults to http://localhost:5100; an empty array rejects all auth tokens.
AAuth:LocalKeyHandle	string	agent samples	Key handle in the IKeyStore for the agent's signing key.
AAuth:ApRefreshEndpoint	string	agent samples	Agent Provider refresh endpoint for enrolled agents.
AAuth:PersonServer	string	Orchestrator	Downstream Person Server URL.
AAuth:Downstream	string	Orchestrator	Downstream resource URL.
AAuth:AgentId	string	Orchestrator	The agent identifier this host signs as.
AAuth:SelfIssuer / AAuth:SelfAgentId	string	SampleApp	Self-issued agent issuer / identifier.

Further Reading

• Getting Started — minimal setup
• Error Handling — all error codes
• Verification Middleware — server setup