IBackChannelLongPollingService Interface

Provides signaling infrastructure for CIBA poll mode long-polling, allowing token endpoint requests to wait for authentication completion rather than immediately returning authorization_pending.

public interface IBackChannelLongPollingService

Derived
↳ InMemoryLongPollingService

Remarks

This interface supports the optional long-polling feature of CIBA poll mode. When long-polling is enabled, token endpoint requests for pending authentication requests are held open (up to a timeout) instead of immediately returning authorization_pending. When the user completes authentication, all waiting requests for that auth_req_id are notified and can immediately return the tokens.

Benefits of Long-Polling:

• Reduced latency: Tokens returned immediately when authentication completes (0-1 second vs 0-5 seconds)
• Reduced server load: Fewer HTTP requests (1-4 per minute vs 12 per minute with 5-second polling)
• Better user experience: Faster token delivery without constant polling overhead

Implementation Patterns:

• In-memory: Use events/TaskCompletionSource for single-server deployments
• Distributed: Use Redis Pub/Sub, SignalR, or message queue for multi-server deployments

Example Flow:

// 1. Client requests token (status = Pending)
// 2. Server holds connection and waits
var statusChange = await longPollingSignaler.WaitForStatusChangeAsync(authReqId, timeout, cancellationToken);

// 3. Meanwhile: User authenticates on device
// 4. The completion handler signals the change - approval and refusal alike, in poll and in ping.
//    Push writes through the same place and wakes nobody, because nothing hands push a notifier and
//    its clients are refused at the token endpoint, so none of them is ever waiting.
await longPollingSignaler.NotifyStatusChangeAsync(authReqId, BackChannelAuthenticationStatus.Authenticated);

// 5. Waiting request wakes up, checks storage, returns tokens

Methods

IBackChannelLongPollingService.NotifyStatusChangeAsync(string, BackChannelAuthenticationStatus) Method

Notifies all waiting requests that the authentication status has changed for the specified request. This immediately releases any long-polling token requests waiting for this auth_req_id.

System.Threading.Tasks.Task NotifyStatusChangeAsync(string authenticationRequestId, Abblix.Oidc.Server.Features.BackChannelAuthentication.BackChannelAuthenticationStatus newStatus);

Parameters

authenticationRequestId System.String

The unique identifier of the authentication request that changed.

newStatus BackChannelAuthenticationStatus

The new authentication status (for logging/diagnostics only).

Returns

System.Threading.Tasks.Task
A task that completes when all waiting requests have been notified.

Remarks

Call this whenever a request leaves the Pending state, and note which of those transitions are yours to signal rather than the library's.

• Authenticated and Denied through the completion handler are signalled by the handler itself, in poll and ping alike - a host that completes through IAuthenticationCompletionHandler needs nothing more. Ping is on that list because a ping client polls the token endpoint too, and the long-poll gate does not read the delivery mode; push is not, because its token endpoint refuses the client outright, so no push client is ever a waiter.
• A status the host writes to storage itself is the host's to signal. The denial pattern documented on IUserDeviceAuthenticationHandler is exactly this case: it updates the stored record directly, so nothing in the library sees the change and a waiter sleeps until its own window runs out.
• Expiry is signalled by nobody, and a waiter is NOT told about it: when its window runs out it is answered authorization_pending, and it learns the request expired on the poll after that, from the record being gone. The grant handler does compare the stored expiry against the clock and remove the record, so there is a place a signal could be sent from; nothing sends one today.

It's safe to call this even if no requests are waiting - it's a no-op in that case.

IBackChannelLongPollingService.WaitForStatusChangeAsync(string, TimeSpan, CancellationToken) Method

Waits for a status change notification for the specified authentication request. Returns immediately if a notification is received, or after timeout if no change occurs.

System.Threading.Tasks.Task<bool> WaitForStatusChangeAsync(string authenticationRequestId, System.TimeSpan timeout, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

authenticationRequestId System.String

The unique identifier of the authentication request to wait for.

timeout System.TimeSpan

Maximum time to wait for a status change.

cancellationToken System.Threading.CancellationToken

Cancellation token to abort the wait operation.

Returns

System.Threading.Tasks.Task<System.Boolean>
A task that completes when either: - A status change notification is received (returns true) - The timeout expires (returns false) - The cancellation token is triggered (throws OperationCanceledException)

Remarks

This method does NOT return the new status - it only signals that a change occurred. The caller must retrieve the updated status from storage.

Multiple callers can wait for the same auth_req_id simultaneously (e.g., if client retries). All waiters will be notified when status changes.