ActiveLogin.Authentication

ActiveLogin.Authentication enables an application to support Swedish BankID (svenskt BankID) authentication in .NET. Built on NET Standard and packaged as NuGet-packages they are easy to install and use on multiple platforms. Used with Identity Server it can be configured as a provider for Azure AD B2C. Free to use, commercial support and training is available if you need assistance or a quick start.

Features

• 🆔 Supports BankID both natively and through GrandID
• 🐧 Cross platform: Targets .NET Standard 2.0 and .NET Core 3.1
• 5️⃣ Built on V5 (the latest) BankID JSON API released in February 2018
• 🔳 Supports BankID QR code and Cancel
• 🔒 GDPR: Security by design
• ☁️ Designed with Microsoft Azure in mind (KeyVault, Monitor, Application Insights, AD B2C etc.)
• 🌎 Multi language support with English and Swedish out of the box
• 🔧 Customizable UI
• 💠 Can be used as a Custom Identity Provider for Azure AD B2C

Screenshots

Screenshots on how the default UI for Native BankID looks on different devices.

Table of contents

Note: This Readme reflects the state of our master branch and the code documented here might not be released as packages on NuGet.org yet. For early access, see our CI builds.

• Project & Packages overview
  • ActiveLogin.Authentication.BankId.*
  • ActiveLogin.Authentication.GrandId.*
• Getting started
  • 1. Read the documentation
  • 2. Install the NuGet package
  • 3. Prepare your project
  • 4. Get started in development
  • 5. Use test or production environments
• Samples
  • Projects and live demos
  • Tests
• FAQ
  • What version of .NET is supported?
  • How do I build the solution locally?
  • How do I run the samples locally?
  • How do I override the default UI?
  • How do I use Active Login to get support for BankID or GrandID in Azure AD (Active Directory) B2C?
  • How do I prepopulate the personal identity number for the user?
  • Do I need to use your ASP.NET Core Auth provider, or can just use the API?
  • Do Active Login Issue any cookies?
  • What browsers do you support?
  • What dependencies do I need if I run Active Login on Linux or in a Linux Docker container?
  • Why are the names of the person sometimes capitalized?
  • Why use UAParserDeviceDetector for device and browser detection
• Active Login
  • Contribute
  • Stay updated and join the discussion
  • License & acknowledgements
  • Sponsors
  • Support & Training

Project & Packages overview

CI-builds from master of all packages are available in our Azure DevOps Artifacts feed.

ActiveLogin.Authentication.BankId.*

Packages for Swedish BankID.

Project	Description	NuGet	Downloads
BankId.Api	API client for the Swedish BankID REST API.
BankId.AspNetCore	ASP.NET Core authentication module for Swedish BankID.
BankId.AspNetCore.Azure	Azure KeyVault integrations for the AspNetCore package.
BankId.AspNetCore.AzureMonitor	Azure Monitor (Application Insights) integrations for the AspNetCore package.
BankId.AspNetCore.QRCoder	QR code generation using QRCoder the AspNetCore package.
BankId.AspNetCore.UAParser	Device and browser detection.

ActiveLogin.Authentication.GrandId.*

Packages for GrandID (Svensk E-identitet).

Project	Description	NuGet	Downloads
GrandId.Api	API client for the GrandID (Svensk E-identitet) REST API.
GrandId.AspNetCore	ASP.NET Core authentication module for GrandID (Svensk E-identitet).

Getting started

First of all, you need to decide if you want to use native BankID or BankID through GrandID (Svensk E-identitet).

• Native BankID gives you full flexibility, including custom UI but requires issuing a certificate through a bank and usually takes some time to sort out.
• GrandID (Svensk E-identitet) uses a predefined UI and does not support all functionalities of the BankID API, but is really easy to get started with and does not require any certificates.

1. Read the documentation

Active Login is designed to make it very easy to get started with BankID and GrandID (Svensk E-identitet), but in the end you are resonsible for making sure that you are complient with the technical guidelines and/or legal agreements. Therefore, before you start using Active Login, please read the documentation relevant to your needs. This will also make sure you understand the concepts better.

• BankID - Teknisk information (Swedish)
• Svensk E-identitet - BankID (English)

2. Install the NuGet package

ActiveLogin.Authentication is distributed as packages on NuGet, install using the tool of your choice, for example dotnet cli.

BankID

dotnet add package ActiveLogin.Authentication.BankId.AspNetCore

GrandID

dotnet add package ActiveLogin.Authentication.GrandId.AspNetCore

3. Prepare your project

It is expected that you have a basic understanding of how ASP.NET Core, ASP.NET Core MVC and ASP.NET Core Authentication works before getting started.

Also, you are expected to have read up on the latest information from BankID. Active Login will help you to implement BankID according to guidelines, but in the end, it's your responsiblity to follow the BankID agreement.

The authentication modules for BankID and GrandID are registered in ConfigureServices( ... ) in your Startup.cs. Depending on your setup, you will probably have to configure challenge and callbacks in AccountController.cs or similar.

4. Get started in development

Both BankID and GrandID requires you to receive either certificates or API-keys, but to get started and try it out the experience there is a simulated environment options available that uses an in-memory implementation. Great for development and testing.

BankID

services
    .AddAuthentication()
    .AddBankId(builder =>
    {
        builder
            .AddDebugEventListener();
            .UseSimulatedEnvironment()
            .AddSameDevice();
    });

GrandID

services
    .AddAuthentication()
    .AddGrandId(builder =>
    {
        builder
            .UseSimulatedEnvironment()
            .AddBankIdSameDevice(options => { })
            .AddBankIdOtherDevice(options => { });
    });

Routes

Also make sure that you map the controller route in ASP.NET Endpoint routing, like this:

app.UseEndpoints(endpoints =>
{
    endpoints.MapDefaultControllerRoute();
});

5. Use test or production environments

To authenticate using a real BankID you need to receive a certificate or API-keys, depending on what solution you choose. The details are described in these documents:

• Getting started with BankID in Test and Production
• Getting started with GrandID in Test and Production

Samples on how to use them in production are:

BankID

services
    .AddAuthentication()
    .AddBankId(builder =>
    {
        builder
            .AddApplicationInsightsEventListener(options =>
            {
                options.LogUserPersonalIdentityNumberHints = true;
                options.LogCertificateDates = true;
            })
            .UseProductionEnvironment()
            .UseClientCertificateFromAzureKeyVault(Configuration.GetSection("ActiveLogin:BankId:ClientCertificate"))
            .UseRootCaCertificate(Path.Combine(_environment.ContentRootPath, Configuration.GetValue<string>("ActiveLogin:BankId:CaCertificate:FilePath")))
            .AddSameDevice()
            .AddOtherDevice()
            .UseQrCoderQrCodeGenerator()
            .UseUaParserDeviceDetection();
    });

Note: .AddApplicationInsightsEventListener() requires the ActiveLogin.Authentication.BankId.AspNetCore.AzureMonitor package.

Note: .UseQrCoderQrCodeGenerator() requires the ActiveLogin.Authentication.BankId.AspNetCore.QRCoder package.

Note: .UseUaParserDeviceDetection() requires the ActiveLogin.Authentication.BankId.AspNetCore.UAParser package.

GrandID

services
    .AddAuthentication()
    .AddGrandId(builder =>
    {
        builder
            .UseProductionEnvironment(config => {
                config.ApiKey = Configuration.GetValue<string>("ActiveLogin:GrandId:ApiKey");
                config.BankIdServiceKey = Configuration.GetValue<string>("ActiveLogin:GrandId:BankIdServiceKey");
            })
            .AddBankIdSameDevice()
            .AddBankIdOtherDevice();
    });

Samples

For more use cases, samples and inspiration; feel free to browse our unit tests and samples.

Note: These are samples on how to use Active Login in different situations and might not represent optimal way of setting up ASP.NET MVC, Identity Server or other components. Please see this as inspiration.

Projects and live demos

Our samples are deployed with the latest version from master and available for you to try out:

Project	Live demo	Description
IdentityServer.ClientSample	https://al-samples-mvcclient.azurewebsites.net	ASP.NET MVC Core site using the IdentityServer.ServerSample as auth provider.
IdentityServer.ServerSample	https://al-samples-identityserver.azurewebsites.net	IdentityServer with Active Login as auth provider for BankID and GrandID.
Standalone.MvcSample	Not available	ASP.NET MVC Core with Active Login as auth provider for BankID and GrandID.
AzureProvisioningSample		ARM template with Azure KeyVault, Azure App Service, Azure Monitor / Application Insights etc.

Please note that IdentityServer.ClientSample uses IdentityServer.ServerSample as the IdentityProvider, so the IdentityServer.ClientSample is a good place to start.

Tests

• BankId.Api.Test
• BankId.AspNetCore.Test
• BankId.AspNetCore.Azure.Test
• GrandId.Api.Test
• GrandId.AspNetCore.Azure.Test

FAQ

Here is a summary of common technical questions. For commercial / business related questions, see the FAQ at ActiveLogin.net.

What version of .NET is supported?

The API-wrappers (*.Api) target .NET Standard 2.0, so they can be used from .NET Core >= 2.0 and .NET Framework >= 4.6.1, see full reference here. The packages that target .NET Standard are strong named as they can be used from .NET Framework where strong naming can be relevant.

The authentication modules (*.AspNetCore), and related packages, depend on ASP.NET Core MVC 3.1 and therefore require .NET Core 3.1.

Our samples target .NET Core 3.1.

How do I build the solution locally?

Active Login is built using .NET Core, make sure you have the relevant version of the SDK and runtime installed.

Run the following command in the root to build all projects:

dotnet build

How do I run the samples locally?

The samples are configured to run in simulated mode (no BankID certificates or GrandID keys required) by default. The IdentityServer.ClientSample is using the IdentityServer.ServerSample as its identity provider. So to run the IdentityServer.ClientSample, the IdentityServer.ServerSample needs to be running first.

The easiest way to try the sample out is to:

1. Configure the solution to use Multiple startup projects, and set it to start both IdentityServer.ServerSample and IdentityServer.ClientSample
2. Press F5

There is also a standalone sample called Standalone.MvcSample which uses only AspNetCore MVC with minimum of code.

How do I override the default UI?

Active Login comes with predefined views that you can use, but maybe you'd rather use your own views to customize layout or behavior.

In your web project, create the following folder: Areas/BankIdAuthentication/Views/BankId

In this folder, you can then create any of the partials and MVC will then discover your partials and use any of them before ours. It's still possible to call our partials if you still want to use them.

• _Login.cshtml
• _LoginForm.cshtml
• _LoginScript.cshtml
• _LoginStatus.cshtml
• _LoginStyle.cshtml

See the MVC sample to see this in action, as demonstrated here.

How do I use Active Login to get support for BankID or GrandID in Azure AD (Active Directory) B2C?

Azure AD B2C supports using custom identity providers that supports Open ID Connect. If you deploy Active Login as part of Identity Server (see our samples) you can configure your Azure AD B2C to federate to that instance and by doing so get BankID and/or GrandID support.

Please reach out if you need assistance in setting this up.

How do I prepopulate the personal identity number for the user?

For legacy reasons, we do support this. But note that the recomendation from BankID is to notuse personal identity numbers, but rather launch the BankID app on the same device or use QR-codes. This is the default behaviour for Active Login.

If you have a usecase for this, you provide an authentication property item named swedishPersonalIdentityNumber (available as constants BankIdConstants.AuthenticationPropertyItemSwedishPersonalIdentityNumber or GrandIdConstants.AuthenticationPropertyItemSwedishPersonalIdentityNumber) that value will be used and sent to BankID/GrandID.

Example usage:

public IActionResult ExternalLogin(string provider, string returnUrl, string personalIdentityNumber)
{
    var props = new AuthenticationProperties
    {
        RedirectUri = Url.Action(nameof(ExternalLoginCallback)),
        Items =
        {
            { "returnUrl", returnUrl },
            { "scheme", provider },
            { BankIdConstants.AuthenticationPropertyItemSwedishPersonalIdentityNumber, personalIdentityNumber }
        }
    };

    return Challenge(props, provider);
}

Do I need to use your ASP.NET Core Auth provider, or can just use the API?

We have seperated the API-wrappers for both BankID and GrandID into two separate packages so that you can use them in other scenarios we have not covered. They look like this and are both well documented using XML-comments.

The constructor for these ApiClients takes an HttpClient and you need to configure that HttpClient with a BaseAddress, Tls12, client certificates etc. depending on your needs.

ActiveLogin.Authentication.BankId.Api

public class BankIdApiClient : IBankIdApiClient
{
    public Task<AuthResponse> AuthAsync(AuthRequest request) { ... }
    public Task<SignResponse> SignAsync(SignRequest request) { ... }
    public Task<CollectResponse> CollectAsync(CollectRequest request) { ... }
    public Task<CancelResponse> CancelAsync(CancelRequest request) { ... }
}

ActiveLogin.Authentication.GrandId.Api

public class GrandIdApiClient : IGrandIdApiClient
{
    public async Task<BankIdFederatedLoginResponse> BankIdFederatedLoginAsync(BankIdFederatedLoginRequest request) { ... }
    public async Task<BankIdGetSessionResponse> BankIdGetSessionAsync(BankIdGetSessionRequest request) { ... }
    public async Task<LogoutResponse> LogoutAsync(LogoutRequest request) { ... }
}

Do Active Login Issue any cookies?

Yes, the *.AspNetCore packages will issue cookies to make the auth flow work.

The cookies are called:

• BankId: __ActiveLogin.BankIdState
• GrandId: __ActiveLogin.GrandIdState

The cookies are there to store state during the auth process, as the user will/might be redirected during the flow. The cookies are session based only and will be deleted once the auth process is finished and/or when the user closes the browser.

Because they are strictly related to temp storage during auth, you should not have to inform the user about these specific cookies (according to the EU "cookie law").

With the current implementaiton (following the convention from Microsoft ASP.NET Core) the usage of cookies is not optional.

A more technical deep dive of the cookies can be found in this issue.

What browsers do you support?

We aim at supporting the latest version of all major browsers both on desktop and on mobile.

All browsers on mobile are supported, but the redirect flow have been tested and verified on these:

• iOS
  • Safari
  • Chrome
  • Edge
  • Firefox
  • Opera Touch
• Android
  • Chrome
  • Firefox
  • Edge
  • Samsung Internet
  • Opera Mini

Note: Brave on iOS/Android is not supported at the moment. It identifies as Safari or Chrome for privacy reasons and will get wrong configuration.

Note: If you aim to support IE11 a polyfill for some JavaScript features we are using is needed.

• Fetch: https://github.com/github/fetch

What dependencies do I need if I run Active Login on Linux or in a Linux Docker container?

The ActiveLogin.Authentication.BankId.AspNetCore.QRCoder package has a dependency on package libgdiplus on Linux.

If you are using Active Login with BankID QR-Codes on either WSL (Windows Subsystem for Linux) or in a Linux Docker Container your OS must have this package installed.

Add libgdiplus to your Dockerfile using apt-get.

FROM mcr.microsoft.com/dotnet/core/aspnet:3.1 AS base
RUN apt-get update && apt-get -y install libgdiplus libc6-dev
...

Why are the names of the person sometimes capitalized?

The names comes from the bank that the end user has, and some banks (due to legacy) stores all of the names in all caps (like ALICE SMITH).

We have choosen not to normalize the capitalization of the names as it´s hard or impossible to do so in a general way.

Why use UAParserDeviceDetector for device and browser detection?

In Active Login device and browser detection is required for example to determine which URL to use to launch the BankID app, according to the BankID Relaying party Guidelines. This logic is primarily encapsulated into IBankIdSupportedDeviceDetector.

The default implementation provided in ActiveLogin.Authentication.BankId.AspNetCore is limited to supports the ~top 5 most common browsers on both iOS and Android. But since an incorrect browser detection can lead to an incorrect launch URL and result in a broken user flow, UAParserDeviceDetector in the ActiveLogin.Authentication.BankId.AspNetCore.UAParser package should be used to support additional browsers. It has a dependency on package uap-csharp for improved user agent parsing.

Active Login

Integrating your systems with market leading authentication services.

Active Login is an Open Source project built on .NET Core that makes it easy to integrate with leading Swedish authentication services like BankID.

It also provide examples of how to use it with the popular OpenID Connect & OAuth 2.0 Framework IdentityServer and provides a template for hosting the solution in Microsoft Azure.

In addition, Active Login also contain convenient modules that help you work with and handle validation of Swedish Personal Identity Number (svenskt personnummer).

Contribute

We are very open to community contributions to Active Login. Please see our contribution guidelines before getting started.

Stay updated and join the discussion

The three primary ways to interact and stay updated with Active Login are:

• Watch our GitHub repo
• Slack
• Twitter

License & acknowledgements

Active Login is licensed under the very permissive MIT license for you to be able to use it in commercial or non-commercial applications without many restrictions.

Active Login is built on or uses the following great open source products:

• .NET Core
• ASP.NET Core
• IdentityServer
• XUnit
• QRCoder
• Bootstrap
• Loading.io

Sponsors

Active Solution is the main sponsor of Active Login. Active Solution is located in Stockholm (Sweden) and provides IT consulting with focus on web, cloud and AI.

We deliver tomorrow's cloud solutions, today. Our costumers choose us because we are engaged, flexible and efficient. We attract the brightest talent and are one of Microsoft's most valued partners.

https://www.activesolution.se/

Support & Training

If you need help with implementing Active Login, there are commercial support & training options available.

We can help you out with:

• Education and training on:
  • Active Login
  • Identity Server
  • Azure AD B2C
  • Authentication on the .NET platform in general
• Hands on implementing BankID using Active Login
• Implement BankID as a custom Identity Provider for Azure AD B2C
• Continuous support for Active Login

See ActiveLogin.net for more details on how to get in touch with us.