BankID (Swedish) Integration for Spring Boot and Angular Applications

What is BankID?

BankID is a citizen identification solution used in Sweden that allows companies, banks and government agencies to authenticate and conclude agreements with individuals over the internet. It is an electronic identity document comparable to passport, drivers’ license and other physical identity documents. This practice has become a standard in Sweden and now almost all applications have started using bankID authentication.

Preconditions

Almost every Swedish bank issues bankIDs to their account holders. The account holders then register to the bankID application using the given ID. Demo applications are provided to developers who do not have Swedish citizenship. If you are a developer, you need to install the bankID application to your mobile or desktop to start the implementation.

There are two types of applications;

Desktop Application

There are Mac and Windows desktop applications. You can install it based on your OS Preference (URL-https://install.bankid.com/). when you open the application it will ask for the BankID. Now we are ready to move on to the next step.

Mobile Application

Android: Go to https://www.bankid.com/rp/info, download and install the .apk file. When opened, the app will ask for the bankID.

iPhone: For iPhones you need to install bankID application from app store.

More info: https://demo.bankid.com/

Figure 1 — For more details about the application installations — Figure 1-For more details about the application installations

Configuration

Go to https://demo.bankid.com/ and locate the area shown in the image below.

Figure 2-Create demo bankID for testing — Figure 2-Create demo BankID for testing

Click on ‘Generate code’ button and it will redirect you to the registration screen.

Figure 3 — Bank ID request screen — Figure 3-Bank ID request screen

After filling-in the relevant details click ‘Order Code’. You will receive an email to the provided email address.

Now you can go and grab a coffee!

Figure 4 — Email with code. — Figure 4-Email with code

Email will be in Swedish, but don’t worry, you just need the code sent in the email and as in Figure 4, you can recognise the code - 41uyqmlo. Now copy it.

Go to https://demo.bankid.com/ and paste the code in the text box (refer Figure 2) and click login. Locate the area shown in the image below and click on the ‘Issue’ button.

Figure 5 — getting bank ID — Figure 5- Issuing the Bank ID

Then you will be redirected to the page shown in figure 6.

Figure 6 — Getting a bank ID with demo Social Security Number — Figure 6-Receiving a Bank ID with demo Social Security Number

The number format is ‘yyyymmdd’ followed by a four digit number. It is required to generate a Social Security Number (SSN), you can get it by clicking here and format it according to the above.

E.g. In the URL Social Security Number is given as “Personnummer: 660509–1898” So the Preferred SSN will be 196605091898.

Figure 7 — Step before final Stage. — Figure 7-Step before the final stage

As shown in figure 8, open the BankID, click on QR code button at the bottom of the screen and scan the QR Code. Then it will prompt the password screen, after entering the password and confirming it, you are DONE.

If you are using the desktop application, it will automatically open the application and register your bank.

As for the mobile application, the process is the same. Once you scan the QR code, password screen will be prompted. Enter and confirm the password and you are DONE.

Figure 9 — Asking to open Desktop Application — Figure 9-Seeking permission to open the Desktop Application

Figure 10 — Asking to open Desktop Application — Figure 10-Seeking permission to open the Desktop Application

Figure — 11 — Password and Confirmation — Figure 11-Password and Confirmation

Yippie... BankID is now ready. Now we can move on to the implementation part.

The Implementation process

Prerequisites

Before you begin, it is required to obtain an apikey and authenticateServiceKey provided by the bank. The bank will also provide the api URL to send requests.

ApiKey — wcge5b59c5n345bc41ba52ell16ef7

authenticateServiceKey — 34nc567h5455hj48kl8009htj8d8e567

URL — https://client.grandid.com/

Implementation

There are three steps to complete an authentication.

· Initiate the session

· Open BankID application

· Get the user details

Initiate session

The URLs can be different from bank to bank but the mechanism is the same. You basically need to call the remote URL by giving above keys. The million dollar tip is DO NOT do it in the front end. Why? The answer is simple. DO NOT expose your keys. This can be achieved by creating a controller and service in the back-end using Spring Boot to secure the APIs and the API keys.

URL — /json1.1/FederatedLogin?apiKey={apiKey}&authenticateServiceKey={authenticateServiceKey}

Method — [POST]

Controller

@GetMapping(“/register”)
public ResponseEntity<?> createAuthenticationToken() throws Exception {
log.info(“Incoming bank registration request.”);
String autoStartToken = externalService.registerBank();
log.info(“Bank registration request executed successfully.”);
return ResponseEntity.ok(new ExternalExecutionRequest(autoStartToken));
}

Simply put, create a controller and call the remote API through the back end.

Service

public BankAuthResponse executeRemoteGetService() {
final String uri = “https://client.grandid.com/json1.1/FederatedLogin?apiKey= wcge5b59c5n345bc41ba52ell16ef7&authenticateServiceKey= 34nc567h5455hj48kl8009htj8d8e567”;
List<HttpMessageConverter<?>> messageConverters = new ArrayList<>();
MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter();
converter.setSupportedMediaTypes(Collections.singletonList(MediaType.ALL));
messageConverters.add(converter);
restTemplate.setMessageConverters(messageConverters);
return restTemplate.getForObject(uri, BankAuthResponse.class);
}

Call the remote URL using the Rest Template and the response needs to be mapped to ‘BankAuthResponse’ class.

Model Class

public class BankAuthResponse {
private String sessionId;
private String autoStartToken;

public String getSessionId() {
return sessionId;
}

public void setSessionId(String sessionId) {
this.sessionId = sessionId;
}

public String getAutoStartToken() {
return autoStartToken;
}

public void setAutoStartToken(String autoStartToken) {
this.autoStartToken = autoStartToken;
}
}

You will get two main keys as the response.

1. SessionID — Unique key to initiate rest of the requests

2. AutoStartToken — Token use to open bankID Application. (Mobile/Desktop)

If you are calling the URL shown in ‘Figure 12’ with the AutoStartToken, the browser will ask to open the bankID application. If you are using the mobile bankID application, you can create a QR code using the URL and scan it using the bankID application.

For application, you need to integrate the bank ID authentication. You can generate a QR code in the login screen and users can scan it and login to the application you are creating.

URL to open — bankid:///?autoStartToken={autoStartToken}

Below is a sample implementation of the QR code.

Figure 12 — Sample Implementation of QR Code — Figure 12-Sample Implementation of the QR Code

Final stage - Data Retrieval

After getting the ‘sessionID’ and ‘autoStartToken’ you need to call another URL to get the user details. Append below URL to the API URL and call it using the ‘restTemplate’. Refer above services.

/json1.1/GetSession?apiKey={apiKey}&authenticateServiceKey=
{authenticateServiceKey}&sessionId={sessionId}

Then you need to call data retrieval URL and after a successful login, it will give you a response as shown below.

{
"sessionId": "{sessionId}",
"username": "{SSN}",
"userAttributes": {
"examplekey": "examplevalue",
"...": "...",
"...": "..."
}
}

You need to call the above URL as many times as required until the user completes the login to BankID application. It is recommended to call the API with a two second interval each time.

Some Tips

1. More security means more protection. You can cache the object using ‘autoStartToken’ as a key and you can hide your ‘sessionID’ also.

2. There are lot of QR code generators in the npm sphere. Check and use the best one.

3. You can use some other framework to call the remote API. The ‘restTemplate’ is the one provided with Spring Boot.