ActiveLogin.Authentication

The BankID authentication implementation follows the standard ASP.NET authentication provider pattern. It is treated as a RemoteAuthenticationProvider because the flow requires redirecting the user to a UI and waiting for completion. During the flow, state is protected and stored via query strings and cookies.

Key Components

• AuthenticationBuilderBankIdAuthExtensions.AddBankIdAuth(): The entry point for adding BankID authentication. It adds default IoC implementations, configures ASP.NET Core authentication, and executes the IBankIdAuthBuilder pipeline.
• BankIdAuthBuilderExtensions.Add*: Used to add specific schemes with configuration for 'Same' or 'Other' device scenarios.
• BankIdAuthHandler: A RemoteAuthenticationHandler that implements IAuthenticationHandler.
• BankIdUiAuthController: An MVC controller that handles the authentication UI.
• BankIdUiAuthApiController: An API controller that handles backend calls from the UI (e.g., init, status, cancel).

Signing follows a simplified version of the authentication concepts. It uses a dedicated service to initiate the flow and handle callbacks.

Key Components

• ServiceCollectionBankIdSignExtensions.AddBankIdSign(): The entry point for adding BankID signing. It adds default IoC implementations, configures ASP.NET Core, and executes the IBankIdSignBuilder pipeline.
• BankIdSignBuilder.AddConfig: Registers configuration in the IBankIdSignConfigurationProvider. Unlike authentication schemes, this does not register a callback URL; instead, the callback URL is specified during the call to BankIdSignService.InitiateSign.
• IBankIdSignConfigurationProvider: Maintains the list of registered BankIdSignConfiguration objects.
• BankIdSignService: The primary service for consumers. It allows initiating the sign flow, redirecting the user, handling the callback, and retrieving state from cookies to return to the consumer's specified URL.
• BankIdUiSignController: An MVC controller handling the signing UI.
• BankIdUiSignApiController: An API controller handling backend calls from the UI (e.g., initialize, qrCode, status, cancel).

You can control the sequence of states the simulated environment transitions through. This is useful for testing UI handling of different success codes or for speeding up automated tests.

• BankIdSimulatedAppApiClient.FastCollectStates: A sequence containing only the states needed to reach a successful result (faster for tests).
• BankIdSimulatedAppApiClient.AllSuccessfulCollectStates: A sequence used to verify UI handling of various successful collect hint codes and text lengths. It does not include failed terminal states.
• Custom Sequence: You can provide a custom List<BankIdSimulatedAppApiClient.CollectState>. The final state in your list must have CollectStatus.Complete for the authentication to finish successfully.

// Using FastCollectStates for automated tests
services.AddBankId(bankId =>
{
    bankId.UseSimulatedEnvironment(options =>
    {
        options.CollectStates = BankIdSimulatedAppApiClient.FastCollectStates;
    });
});

// Using a custom state sequence
services.AddBankId(bankId =>
{
    bankId.UseSimulatedEnvironment(options =>
    {
        options.CollectStates = new List<BankIdSimulatedAppApiClient.CollectState>
        {
            new(CollectStatus.Pending, CollectHintCode.Started),
            new(CollectStatus.Complete, CollectHintCode.UserSign)
        };
    });
});

A typical BankID payment flow involves initiating the payment and then handling the callback to resolve the result.

1. Initiate Payment

Create a BankIdPaymentProperties object containing the transaction details (amount, currency, recipient, etc.). Use the BankIdInitiatePayment helper to redirect the user to the provider.

2. Resolve Result

In your callback endpoint, use IBankIdPaymentService.GetPaymentResultAsync(provider) to retrieve the outcome. Check result.Succeeded and access result.BankIdCompletionData to get user information (Personal Identity Number, Name) and device data (IP Address).

// Inside a Controller
[HttpPost("Payment")]
public IActionResult Payment([FromQuery] string provider, [FromForm] PaymentRequestModel model)
{
    var props = new BankIdPaymentProperties(TransactionType.card, "Demo Merchant Name")
    {
        Money = new("100,00", "SEK"),
        UserVisibleData = "Demo of Payment with Active Login.",
        Items = {
            {"scheme", provider},
            {"transactionType", nameof(TransactionType.card)},
            {"recipientName", "Demo Merchant Name"},
            {"amount", "100,00"},
            {"currency", "SEK"}
        },
    };

    var returnPath = $"{Url.Action(nameof(Callback))}?provider={provider}";
    return this.BankIdInitiatePayment(props, returnPath, provider);
}

[HttpPost]
public async Task<IActionResult> Callback(string provider)
{
    var result = await _bankIdPaymentService.GetPaymentResultAsync(provider);
    if (result?.Succeeded != true || result.BankIdCompletionData == null)
    {
        throw new Exception("Payment error");
    }
    // Process result.BankIdCompletionData...
}