Enables an application to support Swedish BankID's (svenskt BankIDs) authentication workflow in .NET.
Branch: master
Clone or download
ellinge and PeterOrneholm #84 Feature/add sign to bankid api (#85)
* Added sign endpoint to bankid client

* EnsureBase64

* Update src/ActiveLogin.Authentication.BankId.Api/Models/SignRequest.cs

Co-Authored-By: ellinge <magnus.ellinge@gmail.com>

* Update according to suggestions

* Missed using parameter

* Fix build error on windows (tuples)

* Review changes
Latest commit 9dc89aa Feb 19, 2019

README.md

ActiveLogin.Authentication

ActiveLogin.Authentication enables an application to support Swedish BankID's (svenskt BankIDs) authentication workflow in .NET. Built on NET Standard and packaged as NuGet-packages they are easy to install and use on multiple platforms.

Features

  • 🆔 Supports BankID both natively and through GrandID
  • 🐧 Cross platform: Targets .NET Standard 2.0 and .NET Framework 4.6.1
  • ✔️ Strong named
  • 🔒 GDPR Compliant
  • ☁️ Great support for Microsoft Azure
  • 🌎 Multi language support with English and Swedish out of the box
  • 🔧 Customizable UI

Continuous integration & Packages overview

Build status

Project Description NuGet
ActiveLogin.Authentication.BankId.Api API client for Swedish BankID's REST API. NuGet
ActiveLogin.Authentication.BankId.AspNetCore ASP.NET Core authentication module for Swedish BankID. NuGet
ActiveLogin.Authentication.BankId.AspNetCore.Azure Azure integrations for ActiveLogin.Authentication.BankId.AspNetCore. NuGet
ActiveLogin.Authentication.GrandId.Api API client for GrandID (Svensk E-identitet) REST API. NuGet
ActiveLogin.Authentication.GrandId.AspNetCore ASP.NET Core authentication module for GrandID (Svensk E-identitet). NuGet

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.

Screenshots on how the default UI for Native BankID looks.

Active Login Screenshots

1. 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

2. 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.

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.

3. 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
            .UseSimulatedEnvironment()
            .AddSameDevice()
            .AddOtherDevice();
    });

GrandID

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

4. 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:

Samples on how to use them in production are:

BankID

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

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();
    });

Browse tests and samples

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

FAQ

How do I run the samples?

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.

Can I try out a live demo of the samples?

Yes! They are available here. Please note that IdentityServer.ClientSample uses IdentityServer.ServerSample as the IdentityProvider, so the IdentityServer.ClientSample is a good place to start.

Can I prepopulate the personal identity number for the user?

Yes you can! If you provide an authentication property item named swedishPersonalIdentityNumber (available as constants BankIdAuthenticationConstants.AuthenticationPropertyItemSwedishPersonalIdentityNumber or GrandIdAuthenticationConstants.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},
            { BankIdAuthenticationConstants.AuthenticationPropertyItemSwedishPersonalIdentityNumber, personalIdentityNumber }
        }
    };

    return Challenge(props, provider);
}

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

No, it's optional :) 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. The look like this and are both well documented using XML-comments.

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) { ... }
}

Why are the names sometimes capitalized?

It seems that the name for some persons are returned in all capitalized letters (like ALICE SMITH), the data is probably stored that way at BankID. We have choosen not to normalize the capitalization of the names as it´s hard or impossible to do so in a general way.

Active Login

Integrating your systems with market leading authentication services.

Active Login is an Open Source project built on .NET Standard 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. You'll need a basic understanding of Git and GitHub to get started. The easiest way to contribute is to open an issue and start a discussion. If you make code changes, submit a pull request with the changes and a description. Don’t forget to always provide tests that cover the code changes.

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: