#### [Abblix\.Oidc\.Server](https://www.abblix.com/en/docs/api/abblix-oidc-server 'index')
### [Abblix\.Oidc\.Server\.Features\.BackChannelAuthentication\.Interfaces](https://www.abblix.com/en/docs/api/abblix-oidc-server/Abblix.Oidc.Server.Features.BackChannelAuthentication.Interfaces 'Abblix\.Oidc\.Server\.Features\.BackChannelAuthentication\.Interfaces')

## IUserDeviceAuthenticationHandler Interface

Defines the contract for initiating user authentication on a device in the context of a backchannel authentication
flow\. This interface is responsible for handling the initiation of the authentication process for the end\-user
on their device, based on a validated backchannel authentication request\.

```csharp
public interface IUserDeviceAuthenticationHandler
```

### Remarks

<strong>Implementation Guide:</strong>

Implement this interface to integrate your authentication mechanism with CIBA. Your implementation should:
- Send authentication request to user's device (push notification, SMS, email, etc.)
- Display binding_message if present in the request
- Handle user approval/denial asynchronously
- Update authentication status when user responds

<strong>Example Implementation with Ping Mode Support:</strong>

```csharp
public class MyUserDeviceAuthenticationHandler : IUserDeviceAuthenticationHandler
{
    private readonly IBackChannelAuthenticationStorage _storage;
    private readonly IBackChannelDeliveryModeRouter _notifier;
    private readonly ISessionIdGenerator _sessionIdGenerator;
    private readonly IMyPushNotificationService _pushService;

    public async Task<Result<AuthSession, OidcError>> InitiateAuthenticationAsync(
        ValidBackChannelAuthenticationRequest request)
    {
        // Extract user hint and send authentication request to their device
        var userIdentifier = ExtractUserIdentifier(request);
        var bindingMessage = request.Model.BindingMessage;

        // Send push notification to user's device
        await _pushService.SendAuthRequestAsync(userIdentifier, bindingMessage);

        // Return pending - authentication completes asynchronously
        // User will approve/deny on their device
        return new OidcError(ErrorCodes.AuthorizationPending, "Waiting for user approval");
    }

    // Called when user approves on their device
    public async Task OnUserApprovedAsync(string authReqId, string userId)
    {
        // Retrieve the stored authentication request
        var storedRequest = await _storage.TryGetAsync(authReqId);
        if (storedRequest == null) return;

        // Create authenticated session
        var authSession = new AuthSession(
            userId,
            sessionId: _sessionIdGenerator.GenerateSessionId(),
            authenticationTime: DateTimeOffset.UtcNow,
            identityProvider: "local");

        // Update request with authenticated status
        storedRequest.Status = BackChannelAuthenticationStatus.Authenticated;
        storedRequest.AuthorizedGrant = new AuthorizedGrant(authSession, storedRequest.AuthorizedGrant.Context);

        // Notify completion - automatically selects and delegates to the appropriate
        // mode-specific notifier (PollModeNotifier, PingModeNotifier, or PushModeNotifier)
        await _notifier.NotifyAuthenticationCompleteAsync(
            authReqId,
            storedRequest,
            TimeSpan.FromMinutes(5));
    }

    // Called when user denies on their device
    public async Task OnUserDeniedAsync(string authReqId)
    {
        var storedRequest = await _storage.TryGetAsync(authReqId);
        if (storedRequest == null) return;

        storedRequest.Status = BackChannelAuthenticationStatus.Denied;
        await _storage.UpdateAsync(authReqId, storedRequest, TimeSpan.FromMinutes(5));
    }
}
```

<strong>Token Delivery Modes:</strong>

The [CompleteAsync\(string, BackChannelAuthenticationRequest, TimeSpan\)](https://www.abblix.com/en/docs/api/abblix-oidc-server/Abblix.Oidc.Server.Features.BackChannelAuthentication.Interfaces.IAuthenticationCompletionHandler#Abblix.Oidc.Server.Features.BackChannelAuthentication.Interfaces.IAuthenticationCompletionHandler.CompleteAsync(string,Abblix.Oidc.Server.Features.BackChannelAuthentication.BackChannelAuthenticationRequest,System.TimeSpan) 'Abblix\.Oidc\.Server\.Features\.BackChannelAuthentication\.Interfaces\.IAuthenticationCompletionHandler\.CompleteAsync\(string, Abblix\.Oidc\.Server\.Features\.BackChannelAuthentication\.BackChannelAuthenticationRequest, System\.TimeSpan\)') method automatically handles
mode-specific behavior based on the client's registered `backchannel_token_delivery_mode`:
- <strong>Poll Mode:</strong> Stores tokens in [IBackChannelRequestStorage](https://www.abblix.com/en/docs/api/abblix-oidc-server/Abblix.Oidc.Server.Features.BackChannelAuthentication.Interfaces.IBackChannelRequestStorage 'Abblix\.Oidc\.Server\.Features\.BackChannelAuthentication\.Interfaces\.IBackChannelRequestStorage').
                   Client polls the token endpoint with `auth_req_id` until tokens are ready.
- <strong>Ping Mode:</strong> Stores tokens and sends HTTP POST notification via
                   [INotificationDeliveryService](https://www.abblix.com/en/docs/api/abblix-oidc-server/Abblix.Oidc.Server.Features.BackChannelAuthentication.Interfaces.INotificationDeliveryService 'Abblix\.Oidc\.Server\.Features\.BackChannelAuthentication\.Interfaces\.INotificationDeliveryService') to the client's `client_notification_endpoint`
                   with the `auth_req_id`. Client then retrieves tokens from the token endpoint.
- <strong>Push Mode:</strong> Generates tokens via [ITokenRequestProcessor](https://www.abblix.com/en/docs/api/abblix-oidc-server/Abblix.Oidc.Server.Endpoints.Token.Interfaces.ITokenRequestProcessor 'Abblix\.Oidc\.Server\.Endpoints\.Token\.Interfaces\.ITokenRequestProcessor') and delivers
                   them directly via [INotificationDeliveryService](https://www.abblix.com/en/docs/api/abblix-oidc-server/Abblix.Oidc.Server.Features.BackChannelAuthentication.Interfaces.INotificationDeliveryService 'Abblix\.Oidc\.Server\.Features\.BackChannelAuthentication\.Interfaces\.INotificationDeliveryService') to the client's
                   `client_notification_endpoint`. Tokens are removed from storage after successful delivery
                   per CIBA specification section 10.3.1.

<strong>Additional Key Points:</strong>
- <strong>Binding Message:</strong> Display request.Model.BindingMessage to user for transaction confirmation
- <strong>User Code:</strong> If request.Model.UserCode is present, require user to confirm it
- <strong>Authentication:</strong> All notifications use Bearer token from `client_notification_token`

<strong>Security contract — user_code verification (CIBA Core 1.0 §7.1):</strong>

The library validates only the <em>presence</em> of `user_code` when the provider and client
require it (see [UserCodeValidator](https://www.abblix.com/en/docs/api/abblix-oidc-server/Abblix.Oidc.Server.Endpoints.BackChannelAuthentication.Validation.UserCodeValidator 'Abblix\.Oidc\.Server\.Endpoints\.BackChannelAuthentication\.Validation\.UserCodeValidator')); it
deliberately does not — and cannot — verify the code's <em>value</em>, because the secret is known
only to the end-user and the user's authentication device, which this handler owns. Your
implementation therefore <strong>MUST</strong> verify `request.Model.UserCode` against the
user's actual code as part of the device interaction, and <strong>MUST NOT</strong> return a
successful [AuthSession](https://www.abblix.com/en/docs/api/abblix-oidc-server/Abblix.Oidc.Server.Features.UserAuthentication.AuthSession 'Abblix\.Oidc\.Server\.Features\.UserAuthentication\.AuthSession') unless that check passed. A wrong or absent code MUST resolve
to a failed [Abblix\.Utils\.Result&lt;&gt;](https://learn.microsoft.com/en-us/dotnet/api/abblix.utils.result-2 'Abblix\.Utils\.Result\`2') (typically `access_denied`).
Treating presence-validation as sufficient leaves the code unenforced and defeats its purpose.
### Methods

## IUserDeviceAuthenticationHandler\.InitiateAuthenticationAsync\(ValidBackChannelAuthenticationRequest\) Method {#Abblix.Oidc.Server.Features.BackChannelAuthentication.Interfaces.IUserDeviceAuthenticationHandler.InitiateAuthenticationAsync(Abblix.Oidc.Server.Endpoints.BackChannelAuthentication.Interfaces.ValidBackChannelAuthenticationRequest)}

Initiates the authentication process for the user on their device, based on a validated backchannel
authentication request\.
This may involve sending a notification to the user's device, starting an out\-of\-band
authentication process, or performing other steps required to authenticate the user asynchronously\.

```csharp
System.Threading.Tasks.Task<Abblix.Utils.Result<Abblix.Oidc.Server.Features.UserAuthentication.AuthSession,Abblix.Oidc.Server.Common.OidcError>> InitiateAuthenticationAsync(Abblix.Oidc.Server.Endpoints.BackChannelAuthentication.Interfaces.ValidBackChannelAuthenticationRequest request);
```
#### Parameters

###### `request` [ValidBackChannelAuthenticationRequest](https://www.abblix.com/en/docs/api/abblix-oidc-server/Abblix.Oidc.Server.Endpoints.BackChannelAuthentication.Interfaces.ValidBackChannelAuthenticationRequest 'Abblix\.Oidc\.Server\.Endpoints\.BackChannelAuthentication\.Interfaces\.ValidBackChannelAuthenticationRequest') {#Abblix.Oidc.Server.Features.BackChannelAuthentication.Interfaces.IUserDeviceAuthenticationHandler.InitiateAuthenticationAsync(Abblix.Oidc.Server.Endpoints.BackChannelAuthentication.Interfaces.ValidBackChannelAuthenticationRequest).request}

The validated backchannel authentication request containing user and client information
            required to initiate the authentication process\.

#### Returns
[System\.Threading\.Tasks\.Task&lt;](https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.task-1 'System\.Threading\.Tasks\.Task\`1')[Abblix\.Utils\.Result&lt;](https://learn.microsoft.com/en-us/dotnet/api/abblix.utils.result-2 'Abblix\.Utils\.Result\`2')[AuthSession](https://www.abblix.com/en/docs/api/abblix-oidc-server/Abblix.Oidc.Server.Features.UserAuthentication.AuthSession 'Abblix\.Oidc\.Server\.Features\.UserAuthentication\.AuthSession')[,](https://learn.microsoft.com/en-us/dotnet/api/abblix.utils.result-2 'Abblix\.Utils\.Result\`2')[OidcError](https://www.abblix.com/en/docs/api/abblix-oidc-server/Abblix.Oidc.Server.Common.OidcError 'Abblix\.Oidc\.Server\.Common\.OidcError')[&gt;](https://learn.microsoft.com/en-us/dotnet/api/abblix.utils.result-2 'Abblix\.Utils\.Result\`2')[&gt;](https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.task-1 'System\.Threading\.Tasks\.Task\`1')  
A [System\.Threading\.Tasks\.Task](https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.task 'System\.Threading\.Tasks\.Task') representing the asynchronous operation to initiate the authentication process\.