JsonWebKeyExtensions Class

Provides extensions for asynchronous operations on a sequence of JsonWebKey objects.

public static class JsonWebKeyExtensions

Inheritance System.Object → JsonWebKeyExtensions

Methods

JsonWebKeyExtensions.FirstByAlgorithmAsync(this IAsyncEnumerable<JsonWebKey>, string) Method

Asynchronously retrieves the first JsonWebKey able to perform the specified algorithm.

public static System.Threading.Tasks.Task<Abblix.Jwt.JsonWebKey?> FirstByAlgorithmAsync(this System.Collections.Generic.IAsyncEnumerable<Abblix.Jwt.JsonWebKey> credentials, string? algorithm);

Parameters

credentials System.Collections.Generic.IAsyncEnumerable<JsonWebKey>

The asynchronous sequence of JsonWebKey objects.

algorithm System.String

The algorithm to match. Returns null if None is provided.

Returns

System.Threading.Tasks.Task<JsonWebKey>
The first JsonWebKey able to perform the algorithm.

Remarks

A key qualifies by declaring the algorithm, or - when it declares none, which RFC 7517 section 4.4 permits and a certificate-imported key always does - by its material being able to perform it, per SupportsAlgorithm(this JsonWebKey, string).

Order is left to the caller, deliberately. Ranking a declared alg above an undeclared one would override the order the provider handed down, and that order is load-bearing: a key ring returns the active key first, so reordering here would pick a key the ring deliberately kept behind - during a rollover, the newcomer instead of the key clients still expect. Whether a key names its algorithm says nothing about which key should produce.

JsonWebKeyExtensions.FirstByAlgorithmAsync(this IAsyncEnumerable<JsonWebKey>, string, string) Method

Asynchronously retrieves the first JsonWebKey matching an optional algorithm and an optional key id. This is the key-id-aware sibling of FirstByAlgorithmAsync(this IAsyncEnumerable<JsonWebKey>, string): signing passes the token's alg and pinned kid; encryption passes a null algorithm (the key-management alg is derived from the chosen key afterwards) and only the pinned kid.

public static System.Threading.Tasks.Task<Abblix.Jwt.JsonWebKey?> FirstByAlgorithmAsync(this System.Collections.Generic.IAsyncEnumerable<Abblix.Jwt.JsonWebKey> credentials, string? algorithm, string? keyId);

Parameters

credentials System.Collections.Generic.IAsyncEnumerable<JsonWebKey>

The asynchronous sequence of JsonWebKey objects.

algorithm System.String

The algorithm to match, or null to not filter by algorithm. A key qualifies by declaring it or, declaring none, by being able to perform it. Returns null for None.

keyId System.String

The kid to match, or null to not filter by key id.

Returns

System.Threading.Tasks.Task<JsonWebKey>
The first matching key, or null when the sequence yields none and neither filter was applied. Throws when a filter was applied but nothing matched, so a pinned key id or a required algorithm that resolves to no key fails loudly rather than silently downgrading.