Skip to content

BankID Authentication

Target Audience: Users, Developers, Stakeholders

1
Release version: To be announced

Introduction

Info

Please note: The Bank ID integration is still in testing and exists only in the staging environment. To be able to test it you need to contact the Payway team to have your Payway environment configured.

Payway (PW) exposes a proxy, the Payway BankID Service (PBID), that can be used to let end users authenticate using their BankID or Mobile BankID instead of their username and password. This way to authenticate does NOT support SSO and has currently no support in the PCP.

Before you implement BankID authentication you need to read and understand the BankID Relying Party Guidelines, the BankID Trademark Guide and any other information found at the BankID Developer site.

PBID acts as a proxy for the /rp/v5/auth and /rp/v5/collect endpoints and will respond and act in the same way as those with the exception being on a successful login.

Abbreviations

Abbreviation Full name Description
PW Payway
PCP Payway Client Portal
PAP Payway Administration Portal
PBID Payway BankID Service The Payway service that acts like a BankID Proxy.

Requirements

  • Your BankID Certificate must be installed in Payway, this must be done by the Payway team. You must make sure that you have this certificate and that your agreement with your bank allows this certificate to be used in this way.
  • You must setup an API user, using the Payway Administration Portal (PAP). This API user must be configured for use in PBID by the Payway team. In this documentation we will call this API User: PBID API User. The API user must have the following scopes:
    • /external/account/w
    • /api/authorization/delegatedticket

Info

The BankID Test Certificate can be installed in the staging environment. This enabled the use of test ID:s. Please refer to the BankID developer site for information.

API Users

There are two PW API Users involved in a BankID Authentication.

API USers Image

(A) Your Backend Applications API User. This is most likely a user that you already have setup and currently use from your Backend Application to fetch access tokens for users and call the PW API with. In this documentation we'll refer to this as the Backend Application API User.

  • This API Users client_id is what must be used as targetClientId when calling the Auth endpoint. This API User is a shared secret between your Backend Application and PBID.

(B) A new PW API User that must be configured for use in PBID. In this documentation we will refer to this as the PBID API User . See Requirements for details on what scopes are needed.

  • This is the API User whose client_id and secret must be used to calculate the HMAC-SHA256 signature.
  • The Payway Team must configure this API User for use in PBID.

Authentication Process Overview

Term description
User Agent The client application, might be native app or web app
Application Backend The client application backend.
PBID The Payway BankID Service
BankID The actual BankID Service
PW Auth-Server This is the Payway Authorization Service
PW API The Payway API

Authentication Process Image

User Agent

The user agent is responsible for letting the enduser have the possibility to authenticate using BankID. To be able to use BankID's features, the enduser must install the BankID app in a mobile device or PC.

For basic use cases and recommended user messages, see BankID Relying Party Guidelines.

Application Backend

This is your applications backend, responsible for server to server calls between your application and PBID.

Auth

See BankID Relying Party Guidelines for information about the auth-endpoint. PBID is acting like a proxy between your application backend and BankID, with the exception of the targetClientId parameter and the HMAC-SHA256 signature.

Request

  • The Application Backend must sign requests with the PBID API User client secret using HMAC-SHA256.
  • The HTTP-Request must be using the POST-method

The following headers must be set:

1
2
Content-Type: application/json
Accept: application/json

The parameters must be supplied in the application/json format in the requests body:

Field name Example value Description
personalNumber 198212060274 The personal number of the user. 12 digits, century must be included.
endUserIp 92.92.92.92 The end user's ip-address
targetClientId 585a4468edee2c5e6f000001 The client_id of the Backend Application API User
signature gOcvsvUlppSStmrdpKWpDxb25TvEb6025fAwSkKwHpA= The HMAC-SHA256 signature.

Example curl:

1
2
3
4
5
6
7
8
9
curl --request POST \
  --url https://payway-bankid-stage.azurewebsites.net/bankid/your_organisation_id/auth \
  --header 'content-type: application/json' \
  --data '{
    "personalNumber":"198212060274",
    "endUserIp": "92.92.92.92",
    "targetClientId": "585a4468edee2c5e6f000001",
    "signature": "gOcvsvUlppSStmrdpKWpDxb25TvEb6025fAwSkKwHpA="
}'

Endpoints:

Environment URI
Stage https://payway-bankid-stage.azurewebsites.net/bankid/your_organisation_id/auth
Production https://TBA-payway.se/bankid/your_organisation_id/auth

Successful response

Example response from successful request:

1
2
3
4
5
HTTP 200 OK
{
    "orderRef": "e1d1760b-cb98-41c5-b595-1ae34c64ed6f",
    "autoStartToken": "a7877cf8-f7cf-46be-98fe-83c015f58aaa"
}

See BankID Relying Party Guidelines for more information about orderRef and autoStartToken.

Error response

400 Bad Request

See BankID Relying Party Guidelines for information about 400 Bad Request.

Example response:

1
2
3
4
{
  "errorCode": "invalidParameters",
  "details": "endUserIp is required"
}

401 Unauthorized

The HMAC-SHA256 signature is not valid.

500 Internal Server Error

Unexpected server error.

Collect

See BankID Relying Party Guidelines for information about the auth-endpoint. PBID is acting like a proxy between your application backend and BankID, with the exception of the signature parameter and a few new response options.

Request

The collect request should be made every 2 seconds to get status of an on-going BankID order.

  • The Application Backend must sign requests with the BankID API Users client secret using HMAC-SHA256.
  • The HTTP-Request must be using the POST-method.

The following headers must be set:

1
2
Content-Type: application/json
Accept: application/json

The parameters must be supplied in the application/json format in the requests body:

Field name Example value Description
orderRef e1d1760b-cb98-41c5-b595-1ae34c64ed6f The orderRef acquired in the auth call. Used as a reference to an on-going BankID login.
signature gOcvsvUlppSStmrdpKWpDxb25TvEb6025fAwSkKwHpA= The HMAC-SHA256 signature.

Example curl:

1
2
3
4
5
6
7
curl --request POST \
  --url https://payway-bankid-stage.azurewebsites.net/bankid/your_organisation_id/collect \
  --header 'content-type: application/json' \
  --data '{
    "orderRef": "e1d1760b-cb98-41c5-b595-1ae34c64ed6f",
    "signature": "gOcvsvUlppSStmrdpKWpDxb25TvEb6025fAwSkKwHpA="
}'

Endpoints:

Environment URI
Stage https://payway-bankid-stage.azurewebsites.net/bankid/your_organisation_id/collect
Production https://TBA-payway.se/bankid/your_organisation_id/collect

Successful response

Successful BankID login and account found in PW:

1
2
3
4
5
HTTP 200 OK
{
  "status": "complete",
  "ticket": "f714e91e8b5a86878643a525d864e2fe95adc0ee881489942934e6b19739839f"
}

Successful BankID login, but no account in PW:

1
2
3
4
5
HTTP 200 OK
{
  "status": "failed",
  "hintCode": "noAccount"
}

Error response

400 Bad Request

See BankID Relying Party Guidelines for information about 400 Bad Request.

Example response:

1
2
3
4
{
  "errorCode": "invalidParameters",
  "details": "orderRef"
}

401 Unauthorized

The HMAC-SHA256 signature is not valid.

500 Internal Server Error

Unexpected server error.

Authorization Ticket

The ticket received from the Collect request upon a successful authentication is exchanged for an access token tied to the identity of the user authenticating. The details on how to exchange this ticket for an access token is described in the Ticket Authentication documentation. Refer to this section on the Access Token Request.

  • The client_id of the API User requesting an access token must match the targetClientId used in the initial Auth-request.

HMAC-SHA256 Signature

As a way of authorizing requests sent to PBID you are required to attach a Hash-based Message Authentication Code (HMAC) in the json-body of each request, the "signature". This signature is constructed by appending the data in the request to a semi-colon separated string, prefixed by the BankID PBID API User client id, and then creating a HMAC using the SHA256 hash function with the BankID PBID API User client secret as the key. As a last step the HMAC is Base64 encoded and sent in the "signature" field of the json-body.

  • Note: the order in which you append the data is significant.
  • Note: The Base64-encoding need to be strict to not contain and CR or LF.

Example of Auth HMAC calculated in ruby:

1
2
3
4
5
6
7
8
require 'openssl'
require 'base64'

key = '58b97c0ffc5370756850acdbd6975e5d90d250df2a4e01eb445ac642b11764f2'
data = '5d5ea8b195cfeb73298f57ed;198212060274;92.92.92.92;585a4768edce2c5e6f200cd2'
digest = OpenSSL::Digest.new('sha256')
signature = OpenSSL::HMAC.digest(digest, key, data)
base64_encoded_signature = Base64.strict_encode64(signature)

Example of Auth HMAC calculated in Dotnet Core:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
using System;
using System.Text;

var key = "58b97c0ffc5370756850acdbd6975e5d90d250df2a4e01eb445ac642b11764f2";
var data = "5d5ea8b195cfeb73298f57ed;198212060274;92.92.92.92;585a4768edce2c5e6f200cd2";

var hmac = new System.Security.Cryptography.HMACSHA256();
hmac.Key = Encoding.UTF8.GetBytes(key);
var dataBytes = Encoding.UTF8.GetBytes(data);
var signature = hmac.ComputeHash(dataBytes);
var base64EncodedSignature = Convert.ToBase64String(signature);

Auth HMAC

This is the string you need to create the HMAC for the Auth-request:

1
"{__PBID API User__  client id};{personalNumber};{endUserIp};{targetClientId}"

Collect HMAC

This is the string you need to create the HMAC for the Collect-request:

1
"{__PBID API User__  client id};{orderRef}"