SecurityEventTokenBuilder Class
Builds a SET whose envelope satisfies RFC 8417 by construction: the required claims are enforced, the "typ" header is fixed, and the one claim the profile forbids cannot be written.
public sealed class SecurityEventTokenBuilderInheritance System.Object → SecurityEventTokenBuilder
Remarks
The builder is reusable: Build() materializes an independent token each time, so a transmitter may keep one builder per event shape and vary a claim between builds without the tokens sharing state.
Constructors
SecurityEventTokenBuilder(TimeProvider) Constructor
Builds a SET whose envelope satisfies RFC 8417 by construction: the required claims are enforced, the "typ" header is fixed, and the one claim the profile forbids cannot be written.
public SecurityEventTokenBuilder(System.TimeProvider? clock=null);Parameters
clock System.TimeProvider
Supplies "iat" when WithIssuedAt(DateTimeOffset) is not called. Defaults to the system clock; a test hands in a fake to build tokens at a chosen instant.
Remarks
The builder is reusable: Build() materializes an independent token each time, so a transmitter may keep one builder per event shape and vary a claim between builds without the tokens sharing state.
Properties
SecurityEventTokenBuilder.SingleEventStatement Property
Whether the token carries a single event statement, refusing a second where RFC 8417 would take it.
public bool SingleEventStatement { get; init; }Property Value
Remarks
RFC 8417 Section 2 lets one SET carry several statements about different aspects of one transition, and that is what this builder does by default, because it builds SETs for whatever profiles the deployment speaks. A profile may be tighter: the CAEP Interoperability Profile 1.0 says "The 'events' claim of the SET MUST contain only one event", and a deployment claiming it sets this.
Refused at the second statement - through either WithEvent(string, JsonObject) or WithEvent<TPayload>(string, TPayload, JsonSerializerOptions) - rather than at Build(), so the failure names the call that broke the rule instead of the one that noticed.
Methods
SecurityEventTokenBuilder.Build() Method
Materializes the SET, verifying the claims RFC 8417 Section 2.2 requires are in place.
public Abblix.SecurityEvents.SecurityEventToken Build();Returns
SecurityEventToken
An independent token; later builder changes do not reach it.
Exceptions
System.InvalidOperationException
The issuer or the token identifier is missing, or no event statement was added.
SecurityEventTokenBuilder.SignAsync(ISecurityEventTokenSigner, CancellationToken) Method
Materializes the SET and hands it to the signer, returning the compact serialization a transmitter delivers.
public System.Threading.Tasks.Task<string> SignAsync(Abblix.SecurityEvents.Abstractions.ISecurityEventTokenSigner signer, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));Parameters
signer ISecurityEventTokenSigner
The signer owning key and algorithm choice.
cancellationToken System.Threading.CancellationToken
Cancels the signing operation mid-flight.
Returns
System.Threading.Tasks.Task<System.String>
SecurityEventTokenBuilder.WithAudience(string[]) Method
Adds audiences to the "aud" claim. RECOMMENDED (RFC 8417 Section 2.2); calling more than once accumulates.
public Abblix.SecurityEvents.SecurityEventTokenBuilder WithAudience(params string[] audiences);Parameters
audiences System.String[]
The audience identifiers to add.
Returns
SecurityEventTokenBuilder.WithClaim(string, JsonNode) Method
Adds a profile-specific envelope claim, which RFC 8417 Section 2 explicitly leaves room for.
public Abblix.SecurityEvents.SecurityEventTokenBuilder WithClaim(string name, System.Text.Json.Nodes.JsonNode? value);Parameters
name System.String
The claim name.
value System.Text.Json.Nodes.JsonNode
The claim value.
Returns
Exceptions
System.ArgumentException
The name is "exp", a claim a dedicated builder method manages, or a name already written
through this method - every claim has exactly one writer. "exp" is rejected
outright: RFC 8417 Section 2.2 already advises against it for a token that records
history, and Sections 4.1 and 4.2 make its ABSENCE the wall between a SET and the ID and
access tokens an attacker would like to pass one off as - this builder takes that defence
as its own profile rule rather than leaving it to every caller.
SecurityEventTokenBuilder.WithEvent(string, JsonObject) Method
Adds an event statement to the "events" claim. At least one is required for the build to succeed; several express aspects of the same state transition (RFC 8417 Section 2), such as an extension accompanying a primary event.
public Abblix.SecurityEvents.SecurityEventTokenBuilder WithEvent(string eventType, System.Text.Json.Nodes.JsonObject? payload=null);Parameters
eventType System.String
The event identifier URI.
payload System.Text.Json.Nodes.JsonObject
The event's payload; null stands for an event with no payload claims and is written as the empty JSON object (RFC 8417 Section 2).
Returns
Exceptions
System.ArgumentException
A statement with the same event identifier was already added (RFC 8417 Section 2.2).
System.InvalidOperationException
A second statement was added while SingleEventStatement is set.
SecurityEventTokenBuilder.WithEvent<TPayload>(string, TPayload, JsonSerializerOptions) Method
Adds an event statement whose payload is a typed model, serialized here so the caller works in terms of the profiling specification's type rather than raw JSON.
public Abblix.SecurityEvents.SecurityEventTokenBuilder WithEvent<TPayload>(string eventType, TPayload payload, System.Text.Json.JsonSerializerOptions? serializerOptions=null)
where TPayload : Abblix.SecurityEvents.Events.IEventPayload;Type parameters
TPayload
The type modelling the event's payload.
Parameters
eventType System.String
The event identifier URI.
payload TPayload
The payload value.
serializerOptions System.Text.Json.JsonSerializerOptions
Options for payload serialization; null takes the serializer's defaults. A receiver reads the payload back with the options its EventTypeRegistry holds, so a transmitter and receiver sharing a dictionary package agree by construction.
Returns
Exceptions
System.ArgumentException
A statement with the same event identifier was already added, or the payload serialized
into something other than a JSON object, which RFC 8417 Section 2.2 requires the value to
be.
System.InvalidOperationException
A second statement was added while SingleEventStatement is set.
SecurityEventTokenBuilder.WithIssuedAt(DateTimeOffset) Method
Sets the "iat" claim explicitly instead of taking the clock's reading at build time.
public Abblix.SecurityEvents.SecurityEventTokenBuilder WithIssuedAt(System.DateTimeOffset issuedAt);Parameters
issuedAt System.DateTimeOffset
When the SET is issued.
Returns
SecurityEventTokenBuilder.WithIssuer(string) Method
Sets the "iss" claim: the service provider publishing the SET. REQUIRED (RFC 8417 Section 2.2).
public Abblix.SecurityEvents.SecurityEventTokenBuilder WithIssuer(string issuer);Parameters
issuer System.String
The issuer identifier.
Returns
SecurityEventTokenBuilder.WithJwtId(string) Method
Sets the "jti" claim: the SET's unique identifier within its event feed, by which a recipient tells a redelivery from a new event. REQUIRED (RFC 8417 Section 2.2).
public Abblix.SecurityEvents.SecurityEventTokenBuilder WithJwtId(string jwtId);Parameters
jwtId System.String
The token identifier.
Returns
SecurityEventTokenBuilder.WithSubject(string) Method
Sets the "sub" claim: the principal the SET is about. OPTIONAL (RFC 8417 Section 2.2), and many profiles identify the subject inside the event payload instead - Section 3 recommends against "sub" when the subject is not globally unique and has a different issuer than the SET.
public Abblix.SecurityEvents.SecurityEventTokenBuilder WithSubject(string subject);Parameters
subject System.String
The subject value, in whatever form the profile defines.
Returns
SecurityEventTokenBuilder.WithSubjectId(SubjectIdentifier) Method
Sets the "sub_id" claim: the Subject Identifier of the principal the SET is about (RFC 9493 Section 4.2).
public Abblix.SecurityEvents.SecurityEventTokenBuilder WithSubjectId(Abblix.SecurityEvents.Subjects.SubjectIdentifier subjectId);Parameters
subjectId SubjectIdentifier
The Subject Identifier, in any Identifier Format.
Returns
Remarks
Serialization happens at Build() under the identifier's runtime type, so a profile-specific subtype travels correctly without this builder knowing its format - the custom-formats registration matters only to the reader.
SecurityEventTokenBuilder.WithTimeOfEvent(DateTimeOffset) Method
Sets the "toe" claim: when the event itself occurred. OPTIONAL (RFC 8417 Section 2.2) - omitting it is the issuer's way of not sharing an event time.
public Abblix.SecurityEvents.SecurityEventTokenBuilder WithTimeOfEvent(System.DateTimeOffset timeOfEvent);Parameters
timeOfEvent System.DateTimeOffset
When the event occurred; a profile may allow it to be approximate.
Returns
SecurityEventTokenBuilder.WithTransactionId(string) Method
Sets the "txn" claim: a transaction identifier correlating this SET with other JWTs issued for the same transaction. OPTIONAL (RFC 8417 Section 2.2).
public Abblix.SecurityEvents.SecurityEventTokenBuilder WithTransactionId(string transactionId);Parameters
transactionId System.String
The transaction identifier.