ZignSec

eID: BankID without UI -se

Swedish BankID integration for the UI-less backend, suitable for server, mobile, desktop app or custom scenarios.

Note: Recently added parameters lookupPersonAddress

API Calls

Setup+start: POST to https://env.zignsec.com/v2/bankidse/method
Get Results: GET from https://env.zignsec.com/v2/bankidse//collect?orderref=orderref
where
env is api or test
method is Authenticate or Sign
orderref is BankID’s session identifier retrieved on the first call.

Some technical facts about the Swedish BankID

  • The auth/sign service initiation returns two main fields: orderRef and autostartToken. orderRef is the BankID’s session identifier used throughout the process.
  • AutoStartToken is necessary when starting the BankID app automatically via the custom BankID URL where the autostartToken also binds the BankID app instance with a specific initialized session.
  • You are normally allowed to start your BankID app on any device, without using the autostart url, in which case the PersonalNumber is working as the session binding element between the Bankid session and the app. In this scenario the PersonalNumber is a neccessary parameter in the initiation call.
  • To sum up – The merchant can initiate a bankID session either with or without setting the personal number parameter. If set – any BankID client registered with that personal number can immediately respond to the request. If PNr is not set – only the BankID app installed on the same device can respond and the app needs to be started with the autostart-token Url.
  • In production the merchant can set up their own merchant name to be displayed in the user’s BankID app without an extra fee.
  • In test you will see Zignsec as the merchant name
  • Any number of test users (with bankid app test certificates) can be created on a device/pc, in this case a list of users will appear in the BankID app (for unspecified logins on the same device).
  • Many devices/pc can use the same personal number.
  • The first BankID app to respond to a request becomes the “session owner/responder”.
  • In the BankID product every bank is responsible for issuing the actual end user certificate, there is no central controlling agency.
  • The same person can have multiple BankID accounts with the same personal number, but slightly different naming for example leaving out a middle name in one bank.
  • Normally the name fetched via the BankID app is not the full name set in the national population register.

Call Order

The first call is an initiation of the end user´s intended operation, either Authenticate or Sign. Initiation call will immediately activate the authenticate or sign process on the BankID backend and the BankID app will be notified at once to show either the authenticate or sign page. Consider having a web hook configured for “completed/error” to avoid polling.

  1. Step 1. Set up a login session and start BankID backend and app for the specified operation Authenticate or Sign. You will be returned a new BankID OrderRef token.
  2. Step 2. Call API to Retrieve the Final Results, ProgressStatus or Errors in either of these ways:
    1. Have the results automatically POST:ed to the customer’s web hooks for success and error, previously registered with ZignSec.
    2. Repeatedly poll for progress status, errors and finally get the results.

Authentication vs Signing

The use case for /authenticate or /sign are almost identical, but sign shows an extra text message in the BankID app, trough the two extra parameters UserVisibleData and UserNonVisibleData.

The BankID Relying Party Guidelines

Have a look at the BankID Relying Party Guidelines for details about the underlying BankID SOAP service, such as parameters, return values and error conditions.

REST vs SOAP Correspondence

Our API is REST based, whereas BankID web service is SOAP-based. Our methods mirror the native BankID API as closely as possible – with the same call flows, arguments and structures.

Exceptions

The calls to native BankID web service can throw a number of SOAP-Exceptions, where the exception Message string is set to a code that identifies the error situation for the calling party´s understanding, see also BankID Relying Party Guidelines:

  • USER_CANCEL means the user opened and then cancelled the dialog in the BankID app. Show message:
  • EXPIRED_TRANSACTION means a timeout due to inactivity has been reached – ie the user did not locate to his/her phone and start the BankID app within the 3 minutes timeout period.

As the ZignSec integration uses REST and not SOAP API technology, the native BankID API’s SOAP exception needs to be translated into an error code and a description to be stored in the errors array in the returned JSON.

Step 1. Startup a BankID login session (including BankID app activation)

Setup-request example 1 – Authenticate

            POST https://test.zignsec.com/v2/BankIDSE/Authenticate HTTP/1.1
User-Agent: Fiddler
Content-Length: 27
Content-Type: application/json; charset=UTF-8
Authorization: xxxxxxxx-e2a2-4968-b651-5352305c9fb0

{"PersonalNumber":"191212121212"}
        

Setup-request example 2 – Authenticate with lookuppersonaddress=true

            POST https://test.zignsec.com/v2/BankIDSE/Authenticate HTTP/1.1
User-Agent: Fiddler
Content-Length: 27
Content-Type: application/json; charset=UTF-8
Authorization: xxxxxxxx-e2a2-4968-b651-5352305c9fb0

{"PersonalNumber":"191212121212","LookupPersonAddress":true}
        

Setup-request example 3 – Sign

Note that both userVisibleData and userNonVisibleData must be base64-encoded and that userNonVisibleData is optional and can be left out as is the case in this example.

            POST https://test.zignsec.com/v2/BankIDSE/Sign HTTP/1.1
User-Agent: Fiddler
Content-Length: 27
Content-Type: application/json; charset=UTF-8
Authorization: xxxxxxxx-e2a2-4968-b651-5352305c9fb0

{"PersonalNumber":"191212121212", "userVisibleData":"VGVzdGFy"}
        

Reponse example

            {
	"id": "d9e7994f-6f1b-43e1-ab46-ec6833ea2202",
	"errors": [],
	"orderRef": "527312bb-8c14-4cea-95a0-d50218ae1d8a",
	"autoStartToken": "09b3822c-2436-40a7-bc50-bdaa82dfae01"
}
        

The field autoStartToken is used to construct a schema url registered on the operating system on the form bankid:///?autostarttoken=[TOKEN]&redirect=[RETURNURL]. The autoStartToken Url can be used to automatically start up the BankID app from another app or from the browser. Of course the BankID app needs to be installed on the active device, running Android, IOS or Window.
The fields orderRef and autoStartToken originate from the BankID response object (which is of type OrderResponseType), whereas the fields id and and errors are set by ZignSec.

Step 2. alt 1: Let a webhook receive results, progressStatus or errors

To set up a webhook URL for callback, contact Zignsec. Results will be POST:ed to the URL, see this example.

Step 2. alt 2: Call API to retrieve final results, progressStatus or errors

API Endpoint

GET from https://env.zignsec.com/v2/bankidse//collect?orderref=orderref
   where env is api or test and orderref is BankID’s orderref in the response from step 1.

Polling Interval

The guidelines recommend polling for results every 2 seconds.

Fetching Final Result Multiple Times

We follow the BankID backend behaviour and allow only one call for final rusult, wether finished with error or finished with success progressStatus=COMPLETE. The final result cannot be collected twice and the second call will receive an error with code= INVALID_PARAMETERS.

Get Resuls-request example

orderRef was taken from the response of a previous Authenticate or Sign initiation call.

            GET https://test.zignsec.com/v2/BankIDSE/Collect?orderRef=8e4dd041-e38f-463b-b286-a6c5e35d462d HTTP/1.1
User-Agent: Fiddler
Host: test.zignsec.com 
Authorization: xxxxxxxx-e2a2-4968-b651-5352305c

        

Get Resuls-response example 1

The final success response from calling Collect (after having completed a signing process in the BankID app). personalNumber, givenName, surname and name are the person-identity data items.
signature is a base64-encoded xmldsig-document that can be used to verify the operation’s PKI signature in retrospect and ocspResponse is used to describe and verify the validity of the certificate used in the operation.

ipAdress is the internet address of the BankID app client as the BankID server discovers it.

            {
  "id":"6e8020b9-2458-44e3-b5ac-8dbf41f55bab",
  "errors":[],
  "progressStatus":"COMPLETE",
  "signature":"...   ...",
  "ocspResponse":"...  ...",
  "userInfo":{
    "personalNumber":"191212121212",
    "givenName":"LARS",
    "surname":"SVENSON",
    "name":"LARS SVENSON",
    "notBefore":"2015-11-30T00:00:00+01:00",
    "notAfter":"2017-11-29T23:59:59+01:00",
    "ipAddress":"233.243.246.194"}}

        

Get Resuls-response example 2 – (lookupPersonAddress=true)

            {
  "id": "737361a9-044a-4688-877f-c7d599266976",
  "errors": [
    
  ],
  "progressStatus": "COMPLETE",
  "userInfo": {
    "personalNumber": "198710260070",
    "givenName": "JAN ERIK GREN",
    "surname": "GREN",
    "name": "JAN ERIK",
    "notBefore": "2018-10-04T00:00:00+02:00",
    "notAfter": "2020-10-03T23:59:59+02:00",
    "ipAddress": "185.176.146.178"
  },
  "signature": "too long to display",
  "ocspResponse": "too long to display...",
  "LookupPersonAddress": {
    "PersonStatus": "",
    "FirstName": "Jan Erik",
    "LastName": "Gren",
    "MainFirstName": "Jan",
    "Address": "Tranebergv 3",
    "Address2": null,
    "PostalCode": "12345",
    "Location": null,
    "City": "Solna",
    "Province": null,
    "CountryCode": "se",
    "Phone": null,
    "PhoneNumbers": [
      "08-51234567",
      "073-41234567"
    ],
    "Email": null,
    "DateOfBirth": "19871126",
    "BirthYear": 1987,
    "BirthMonth": 11,
    "BirthDayOfMonth": 26,
    "Age": 30,
    "PersonalNumber": "198711260070",
    "_DataSource": "DP05"
  }
}
        

Recommended user messages (taken from official guidelines)

Short Name English Text Swedish Text Event or API Code Mapping
RFA1 Start your BankID app Starta BankID-appen OUTSTANDING_ TRANSACTION, NO_CLIENT
RFA2 The BankID app is not installed. Please contact your internet bank. Du har inte BankID-appen installerad. Kontakta din internetbank. The BankID app is not installed in the mobile device.
RFA3 Action cancelled. Please try again. Åtgärden avbruten. Försök igen ALREADY_IN_PROGRESS, CANCELLED
RFA5 Internal error. Please try again. Internt tekniskt fel. Försök igen RETRY, INTERNAL_ERROR
RFA6 Action cancelled.  Åtgärden avbruten. USER_CANCEL
RFA8 The BankID app is not responding. Please check that the program is started and that you have internet access. If you don’t have a valid BankID you can get one from your bank. Try again. BankID-appen svarar inte. Kontrollera att den är startad och att du har internetanslutning. Om du inte har något giltigt BankID kan du hämta ett hos din Bank. Försök sedan igen. EXPIRED_TRANSACTION
RFA9 Enter your security code in the BankID app and select Identify or Sign. Skriv in din säkerhetskod i BankIDappen och välj Legitimera eller Skriv under. USER_SIGN
RFA12 Internal error. Update your BankID app and try again. Internt tekniskt fel. Uppdatera BankID-appen och försök igen. CLIENT_ERR
RFA13 Trying to start your BankID app. Försöker starta BankID-appen. OUTSTANDING_ TRANSACTION
RFA14 (A) Searching for BankID:s, it may take a little while… If a few seconds have passed and still no BankID has been found, you probably don’t have a BankID which can be used for this login/signature on this computer. If you have a BankID card, please insert it into your card reader. If you don’t have a BankID you can order one from your internet bank. If you have a BankID on another device you can start the BankID app on that device. Söker efter BankID, det kan ta en liten stund… Om det har gått några sekunder och inget BankID har hittats har du sannolikt inget BankID som går att använda för den aktuella inloggningen/underskriften i den här datorn. Om du har ett BankIDkort, sätt in det i kortläsaren. Om du inte har något BankID kan du hämta ett hos din internetbank. Om du har ett BankID på en annan enhet kan du starta din BankID-app där. STARTED – The RP provided the ID number in the web service call (without using AutoStartTokenRe quired). The user accesses the service using a personal computer
RFA14 (B) Searching for BankID:s, it may take a little while… If a few seconds have passed and still no BankID has been found, you probably don’t have a BankID which can be used for this login/signature on this device. If you don’t have a BankID you can order one from your internet bank. If you have a BankID on another device you can start the BankID app on that device. Söker efter BankID, det kan ta en liten stund… Om det har gått några sekunder och inget BankID har hittats har du sannolikt inget BankID som går att använda för den aktuella inloggningen/underskriften i den här enheten. Om du inte har något BankID kan du hämta ett hos din internetbank. Om du har ett BankID på en annan enhet kan du starta din BankID-app där. STARTED – The RP provided the ID number in the web service call (without using AutoStartTokenRe quired). The user accesses the service using a mobile device.
RFA15 (A) Searching for BankID:s, it may take a little while… If a few seconds have passed and still no BankID has been found, you probably don’t have a BankID which can be used for this login/signature on this computer. If you have a BankID card, please insert it into your card reader. If you don’t have a BankID you can order one from your internet bank. Söker efter BankID, det kan ta en liten stund… Om det har gått några sekunder och inget BankID har hittats har du sannolikt inget BankID som går att använda för den aktuella inloggningen/underskriften i den här datorn. Om du har ett BankIDkort, sätt in det i kortläsaren. Om du inte har något BankID kan du hämta ett hos din internetbank. STARTED – The RP did not provide the ID number in the web service call. The user accesses the service using a personal computer.
RFA15 (B) Searching for BankID:s, it may take a little while… If a few seconds have passed and still no BankID has been found, you probably don’t have a BankID which can be used for this login/signature on this device. If you don’t have a BankID you can order one from your internet bank Söker efter BankID, det kan ta en liten stund… Om det har gått några sekunder och inget BankID har hittats har du sannolikt inget BankID som går att använda för den aktuella inloggningen/underskriften i den här enheten. Om du inte har något BankID kan du hämta ett hos din internetbank. STARTED – The RP did not provide the ID number in the web service call. The user accesses the service using a mobile device.
RFA16 The BankID you are trying to use is revoked or too old. Please use another BankID or order a new one from your internet bank. Det BankID du försöker använda är för gammalt eller spärrat. Använd ett annat BankID eller hämta ett nytt hos din internetbank. CERTIFICATE_E RR
RFA17 The BankID app couldn’t be found on your computer or mobile device. Please install it and order a BankID from your internet bank. Install the app from install.bankid.com. BankID-appen verkar inte finnas i din dator eller telefon. Installera den och hämta ett BankID hos din internetbank. Installera appen från install.bankid.com. START_FAILED
RFA18 Start the BankID app Starta BankID-appen The name of link or button used to start the BankID App
RFA19 Would you like to login or sign with a BankID on this computer or with a Mobile BankID? Vill du logga in eller skriva under med BankID på den här datorn eller med ett Mobilt BankID? The user access the service using a browser on a personal computer.
RFA20 Would you like to login or sign with a BankID on this device or with a BankID on another device? Vill du logga in eller skriva under med ett BankID på den här enheten eller med ett BankID på en annan enhet? The user access the service using a browser on a mobile device.

Error codes for Auth/Sign (taken from off. guidelines)

Code Reason Action by RP
INVALID_PARAMETERS Invalid parameter. Invalid use of method RP must not try the same request again. This is an internal error within RP’s system and must not be communicated to the user as a BankIDerror.
ALREADY_IN_PROGRESS An order for this user is already in progress. The order is aborted. No order is created RP must inform the user that a login or signing operation is already initiated for this user. Message RFA3 should be used.
INTERNAL_ERROR Internal technical error in the BankID system. RP must not automatically try again. RP must inform the user that a technical error has occurred. Message RFA5 should be used.
RETRY Internal technical error in the BankID system. RP must not automatically try again. RP must inform the user that a technical error has occurred. Message RFA5 should be used.
ACCESS_DENIED_RP RP does not have access to the service or requested operation. RP must not try the same request again. This is an internal error within RP’s system and must not be communicated to the user as a BankIDerror.

ProgressStatus values (taken from off. guidelines)

Status Reason Action by RP
OUTSTANDING_TRANSACTION The order is being processed. The client has not yet received the order. The status will later change to NO_CLIENT, STARTED or USER_SIGN. If RP tried to start the client automatically, the RP should inform the user that the app is starting. Message RFA13 should be used.

If RP did not try to start the client automatically, the RP should inform the user that she needs to start the app. Message RFA1 should be used.

NO_CLIENT  The order is being processed. The client has not yet received the order. If the user did not provide her ID number the error START_FAILED will be returned in this situation. If RP tried to start the client automatically: This status indicates that the start failed or the users BankID was not available in the started client. RP should inform the user. Message RFA1 should be used.

If RP did not try to start the client automatically: This status indicates that the user not yet has started her client. RP should inform the user. Message RFA1 should be used.

STARTED A client has been started with the autostarttoken but a usable ID has not yet been found in the started client. When the client starts there may be a short delay until all ID:s are registered. The user may not have any usable ID:s at all, or has not yet inserted their smart card. If RP does not require the autoStartToken to be used and the user provided her ID number the RP should inform the user of possible solutions. Message RFA14 should be used.

If RP require the autostarttoken to be used or the user did not provide her ID number the RP should inform the user of possible solutions. Message RFA15 should be used. Note: STARTED is not an error, RP should keep on polling using collect.

USER_SIGN The client has received the order. The RP should inform the user. Message RFA9 should be used.
USER_REQ Not used
COMPLETE The user has provided the security code and completed the order. Collect response includes the signature, user information and the ocsp response. RP should control the user information returned in userInfo and continue their process

Error codes for Collect (taken from off. guidelines)

Important note regarding multiple collects: If the user pressed cancel in the BankID app, errors[] will contain USER_CANCEL, but for the subsequent calls error[] will just contain INVALID_PARAMETERS which is the general error message for “order cannot be collected twice”.

Error code Reason Action by RP
INVALID_PARAMETERS Invalid parameter. Invalid use of method. Using an orderRef that previously resulted in COMPLETE. The order cannot be collected twice. RP must not try the same request again. This is an internal error within RP’s system and must not be communicated to the user as a BankID-error.
REQ_PRECOND Not used.
REQ_ERROR Not used.
REQ_BLOCKED Not used.
INTERNAL_ERROR Internal technical error in the BankID system. RP must not automatically try again. RP must inform the user. Message RFA5.
RETRY Internal technical error in the BankID system. RP must not automatically try again. RP must inform the user. Message RFA5.
ACCESS_DENIED_RP RP does not have access to the service, requested operation or the orderRef. RP must not try the same request again. This is an internal error within RP’s system and must not be communicated to the user as a BankID-error.
CLIENT_ERR Internal technical error. It was not possible to create or verify the transaction. RP must not automatically try again. RP must inform the user. Message RFA12.
EXPIRED_TRANSACTION The order has expired. The BankID security app/program did not start, the user did not finalize the signing or the RP called collect too late. RP must inform the user. Message RFA8.
CERTIFICATE_ERR This error is returned if:
1) The user has entered wrong security code too many times in her mobile device. The Mobile BankID cannot be used.
2) The users BankID is revoked.
3) The users BankID is invalid.
RP must inform the user. Message RFA16.
USER_CANCEL The user decided to cancel the order. RP must inform the user. Message RFA6
CANCELLED The order was cancelled. The system received a new order for the user. RP must inform the user. Message RFA3.
START_FAILED The user did not provide her ID, or the RP requires autostarttoken to be used, but the client did not start within a certain time limit.
The reason may be::
1) RP did not use autoStartToken when starting BankID security program/app.
2) The client software was not installed or other problem with the user’s computer.
1) The RP must use autoStartToken when starting the client.
2) The RP must inform the user. Message RFA17.
ALREADY_COLLECTED Not used.