BankID Authentication¶

Target Audience: Users, Developers, Stakeholders

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:

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:

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:

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:

{
  "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 collect-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:

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:

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:

HTTP 200 OK
{
  "status": "complete",
  "ticket": "f714e91e8b5a86878643a525d864e2fe95adc0ee881489942934e6b19739839f"
}

Successful BankID login, but no account in PW:

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:

{
  "errorCode": "invalidParameters",
  "details": "orderRef"
}

401 Unauthorized¶

The HMAC-SHA256 signature is not valid.

500 Internal Server Error¶

Unexpected server error.

Cancel¶

See BankID Relying Party Guidelines for information about the cancel-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 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:

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:

curl --request POST \
  --url https://payway-bankid-stage.azurewebsites.net/bankid/your_organisation_id/cancel \
  --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/cancel
Production	https://TBA-payway.se/bankid/your_organisation_id/cancel

Successful response¶

Successful cancellation

HTTP 200 OK
{}

Error response¶

400 Bad Request¶

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

Example response:

{
  "errorCode": "invalidParameters",
  "details": "No such order"
}

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:

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:

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:

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

Collect HMAC¶

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

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