Swedish BankID integration for the UI-less backend, suitable for server, mobile, desktop app or custom scenarios.
API Calls
Setup: POST to https://env
.zignsec.com/v2/bankidse/
Result:method
Cancel: GET from https://
env
.zignsec.com/v2/bankidse/collect?orderref=orderRef
POST to https://
env
.zignsec.com/v2/bankidse/cancel
whereenv
is API or test method
is Authenticate or SignorderRef
is BankID’s session identifier retrieved on the first call.
Call Sequence
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.
- 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.
- Step 2. Start the login workflow in a BankID app.
- Step 3. Call API to Retrieve the Final Results, ProgressStatus or Errors in either of these ways:
- Have the results automatically POST:ed to the customer’s web hooks for success and error, previously registered with ZignSec.
- 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 service, such as parameters, return values and error conditions.
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. Shows message:EXPIRED_TRANSACTION
means a timeout due to inactivity has been reached – i.e., 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.
Request Parameters
Parameter | Description | Required |
---|---|---|
PersonalNumber | The ID number of the user trying to be authenticated. If the ID number is omitted the user must use the same device and the client must be started with the autoStartToken returned in orderResponse. | No |
endUserInfo | List of EndUserInfoType: {
"type": "",
"value": ""
} Used to provide information related to the user and the user’s computer/device to the BankID-server. | No |
userVisibleData | Only forSign method. The text to be displayed and signed. Must be UTF-8 encoded. The value must be base 64-encoded. 1-40 000 characters (after base 64-encoding). The text can be formatted using CR = new line, LF = new line and CRLF = new line | Yes, on Sign |
userNonVisibleData | Just for Sign method. Data not displayed to the user. The value must be base 64-encoded. 0 – 200 000 characters (after base 64-encoding). | No |
lookupPersonAddress | Currently works for Swedish BankID and Swedish Banking API. If set to true will automatically do a Swedish person address lookup from the verified personalNumber using LookupPerson API and the official population register. The call is charged separately, which means that additional charges will be incurred. | No |
relayState | Added by ZignSec. This semi-optional parameter will be returned to you at the redirect back to your server. Use it to link an unique ID of your choice that you can parse. If not relayState is specified, ZignSec will automatically set the ZignSec’s unique session identifier, the RequestID token here. Example: relaystate=zignsec_eid_1234 | No |
webhook | Added by ZignSec. A URL where success/error results will automatically be POST:ed. It can be set either here or on the merchant’s setting, see setting eid_webhook at merchant settings page or this general page web hooks for success and error During test you try https://webhook.site/ for free web hook urls. | No |
requirement | NOTE: Include setting AutoStartTokenRequired=Yes to require that login must be performed scanning a QR code. Adding this setting will also include a image URL to the QR Code in the setup Response body. Used by RP to set requirements how the authentication or sign operation must be performed. Default rules are applied if omitted. Example: “AutoStartTokenRequired”: "Yes" } | No |
endUserIp | The user IP address as seen by RP. String. IPv4 and IPv6 is allowed. NOTE: the importance of using the correct IP address. It must be the IP address representing the user agent (the end user device) as seen by the RP. If there is a proxy for inbound traffic, special considerations may need to be taken to get the correct address. In some use cases the IP address is not available, for instance for voice based services. In this case, the internal representation of those systems IP address is ok to use. | Yes |
Examples of setting up a BankID login session
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"}
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}
Example 3 – Sign
Note that both userVisibleData and userNonVisibleData must be base64-encoded, and that userNonVisibleData is optional and can be left out as 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"}
Response example 1-3
{ "id": "d9e7994f-6f1b-43e1-ab46-ec6833ea2202", "errors": [], "orderRef": "527312bb-8c14-4cea-95a0-d50218ae1d8a", "autoStartToken": "09b3822c-2436-40a7-bc50-bdaa82dfae01" }
Example 4 – Authenticate with AutoStartTokenRequired=Yes
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", "requirement": {"AutoStartTokenRequired": "Yes"} }
Response example 4
{ "id": "d9e7994f-6f1b-43e1-ab46-ec6833ea2202", "errors": [], "orderRef": "527312bb-8c14-4cea-95a0-d50218ae1d8a", "autoStartToken": "09b3822c-2436-40a7-bc50-bdaa82dfae01", "qrCodeLink": "https://test.zignsec.com/v2/qrcode?text=bankid:///?autostarttoken=09b3822c-2436-40a7-bc50-bdaa82dfae01" }
Step 2. Start the login workflow in a BankID app.
There are two approaches to start BankID app:
- To start the BankID app manually, only if
PersonalNumber
is set - To start the BankID app with autostart URL, required when
PersonalNumber
is NOT set
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.
Parameter | Description | Required |
autoStartToken | Holds the autoStartToken that was returned from the web service call. If the user personal number was not included in the web service call the autoStartToken must be provided. We strongly recommend to always use the autoStartToken when the URL is used to start the client. If it is not included and the user reloads the page or if the page erroneously repeats the start command, the user may get an error claiming that the BankID is missing. The likelihood of this to happen is reduced if autoStartToken is used. Note that the parameter names must be lower case. | |
redirect | The BankID app uses the parameter redirect to launch the RP web app after completed (including cancelled) auth or sign. The redirect URL must be UTF-8 and URL encoded and should match the web address the user is visiting when RP web app launches the BankID app. It may include parameters to be passed to the browser. For iOS the redirect must have a value. For all other platforms it may be empty (“redirect=”), or set to “null” (“redirect=null”). If it is empty or null the BankID app will terminate without launching any URL and the calling application will be in focus. The general recommendation is to use redirect=null when it is possible. Note for Windows and macOS If redirect has a value the redirect parameter must be used together with autoStartToken. If autoStartToken is excluded, the content of redirect will be ignored and the behavior will be as if redirect=null. Note for Android If the user has several browsers installed on an Android device the user is sometimes presented with a question asking what browser to use. BankID recommends that redirect=null is used on Android. This ensures the user will return to the browser previously used. | Required |
Step 3. Get status/results
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.Alt 2: Call API to retrieve final results, progressStatus or errors
GET from https://env
.zignsec.com/v2/bankidse//collect?orderref=orderRef
where env
is API or test 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 behavior and allow only one call for final result, whether finished with error or finished with successprogressStatus=COMPLETE
. The final result cannot be collected twice and the second call will receive an error
with code=INVALID_PARAMETERS
.Get Results – 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
Example response
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. ipAddress
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" }, "relayState": "abcdefg123456" }
Example response where 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" }, "relayState": "abcdefg123456" }
ProgressStatus values (from official 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 |
Recommended user messages (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 | CANCELLED |
RFA4 | An identification or signing for this personal number is already started. Please try again | En identifiering eller underskrift för det här personnumret är redan påbörjad. Försök igen. | ALREADY IN PROGRESS |
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 |
Deprecated RFA12 | Deprecated Internal error. Update your BankID app and try again. | Deprecated 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 AutoStartToken required). 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 AutoStartToken required). 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. |
RFA22 | Unknown error. Please try again. | Okänt fel. Försök igen. | An error occurred. The errorCode is unknown to ZignSec. |
Error codes for Auth/Sign (from official 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 BankID error. |
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 RFA4 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 BankID error. |
Error codes for Collect
Relates to BankID official guidelines
NOTE: With ZignSec it is allowed to collect the same order twice within a configurable time span. In underlying BankID implementation multiple collects are not allowed, and you will receive a INVALID_PARAMETERS error after the first collect that was status COMPLETE.
Error 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 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. |
Cancel a BankID login session
Cancel – Request example
POST https://test.zignsec.com/v2/BankIDSE/cancel HTTP/1.1 Content-Length: 27 Content-Type: application/json; charset=UTF-8 Authorization: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx9fb0 { "orderRef": "527312bb-8c14-4cea-95a0-d50218ae1d8a" }
Cancel – Response example
{ "id": "76f2cc59-5e01-40e4-88f5-02eaae62b835", "errors": [] }