BankID in Browser is an integration with the standard national electronic authentication methods in the Nordic with support for BankID in Sweden, Finland, Denmark and Norway 

The login workflow runs in a ZignSec controlled browser session.

Here you can find the Nordic eID provider’s public web portals.

API Calls

Set up: POST to https://env.zignsec.com/v2/eid/bankid_selector
Result: GET from https://env.zignsec.com/v2/eid/sessionid
where

env is API or test
bankid_selector is for example sbid-another, nemid, nbid_oidc, smartid/auth or smartid/sign, see the bankid_selector alternatives below
sessionid is the session identifier retrieved from the setup call, named id’in the response

v2 for sbid, fbid, nbid, nemid products; for others use v3

 Code examples for PHP and C# are located here: Code examples

Call Sequence

Step 1. Set up session

POST to https://env.zignsec.com/v2/eid/bankid_selector
where
env is API or test
bankid_selector is for example sbid-another, nbid_oidc or nemid, see the bankid_selector alternatives below.

Available Methods

This is the list of possible options for bankid_selector, i.e., the type of authentication.

[bankid_selector] in URLDescription
sbid-anotherSwedish BankID Authentication on any device, local or other. In this case a button Start BankID app will be shown on the waiting form. If pressed the locally installed BankID app will be shown if it is configured with the selected personal number
sbidSwedish BankID Authentication on same device. If a local BankID app is installed and it is configured for the entered personal number (either through API parameter or through the browser form), it will be automatically triggered to start in a few seconds. IMPORTANT: For autostart of the Swedish BankID app from an IFRAME the following script needs to loaded on the container page:
sbid-signSwedish BankID Signing. These two parameters are a requirement: PersonalNumber and UserVisibleData. UserNonVisibleData is optional.
fbidFinnish BankID authentication both via the mobile app and through banking.
nemidDanish NemID Authentication.
nbid_oidcNorwegian BankID web or mobile Authentication. See the request body parameter login_hint below for lots of configuration alternatives, such as limiting to mobile and a specific mobile number.
nbidNorwegian BankID web Authentication. Forwards to nbid_oidc with login_hint = BID
nbid_mobileNorwegian BankID web Authentication. Forwards to nbid_oidc with login_hint = BIM
nbid_pepNorwegian BankID web or mobile Authentication with PEP check
[cc][cc] is a two letter country code (ISO standard) to let the use select from a button list of available identification method(s) for that particular country.
swissidSwissId web Authentication

Headers

In order to send a message you need to authenticate yourself using the credentials given by ZignSec.

AuthorizationThis header parameter is the personal access token you received from ZignSec during the registration process. Example: Authorization: 00000000-e2a2-4968-b651-5352305c9fb0Required
Content-TypeSpecifies the media type of the request body data. Set to application/x-www-form-urlencoded. for post data and application/json if JSON object. Example: Content-Type: application/x-www-form-urlencodedRequired
HostUse test.zignsec.com for test environment and api.zignsec.com for production environment. Example: api.zignsec.comRequired

Request Parameters

ParameterDescriptionRequired
personalnumber

Set up of identity number. This optional parameter has somewhat different meanings for each country:

SE: Means that for Sweden only this specific person can be identified; No need to fill in PersonalNumber; The BankID app starts up for this person only.

DK: Danish Nemid does not return personal number (CPR), instead a technical substitute key called PID. However, if the PersonalNumber parameter is present then a background matchPidCpr call is run that verifies that given PersonalNumber matches the logged-in PID, Where after the PersonalNumber is set in response symbolizing the PersonalNumber is verified by a NemID login.

NO: If PersonalNumber is sent in only that person can login, because the first page for entering PersonalNumber is skipped entirely. This is a convenient way to verify a specific PersonalNumber. Another alternative is the field Additional_identity_info that lets you include the PersonalNumber in the results provided the BankID merchant certificate used is allowed for fetching extra info.

The PersonalNumber formats per country:

SE: personalNumber=195206040759 (YYYYMMDDCCCC)

DK: personalNumber=1210312133 (DDMMYYCCCC)

NO: personalNumber=01129955131 (DDMMYYXXXCC)

No
relaystate

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
configid

Here you can send in a GUID that represent a specific configuration. This is used to separate between multiple certificates, different layouts or to make different Webhook calls. If only one configuration it is used automatically.

Example: configid=d638a4ab-7382-4c5d-98e8-e90d3aa3e1be

No
target

If this parameter is supplied the browser session will finally be redirected to this URL-value. The URL-parameter value must be URL-encoded.

Example: target=http%3A%2F%2Flocalhost%3A8080%2Fzignsec%2Freturn will result in a browser redirect to for example http://localhost:8080/zignsec/return?relaystate=96a09f3f-b764-4ed0-b9e8-2b29d95dcf15&service=eIDBasic where relayState is ZignSec’s session token (RequestID) which can be used to retrieve the results from the login session.

No
targetErrortargetError works as target except it is navigated on user cancel or error situations.No
layoutIf this parameter is left out this is set to the current default layout, contact ZignSec for layouts and default selection.No
language

Decides web form user interface language.

The default language is taken from the merchants setting ‘DefaultLanguage’ or EN=English if none is set there. Language can be changed both on a request level here, or on setting level. For example, if a customer mainly uses the Swedish BankID ZignSec will change the ‘DefaultLanguage’ setting to SV for best user experience. The code format should be in this 2-letter ISO 639-1 language code, case-insensitive.

No
AskForCprOnly works with Danish NemID [who don’t return the Danish personal number (CPR)]. If this parameter is set to true, an input form for entry of CPR number is shown after then NemID login step. The entered CPR number is verified with current NemID PID with a call to the Match service at NemID, and the verified CPR is stored in the identity PersonalNumber response field.No
AskForCprCallback

Only works with Danish NemID [who don’t return the Danish personal number (CPR)]. This merchant callback allows for a slimmed login process, showing the CPR validation dialog only when necessary (such as on a customer’s first login to a site). If this callback is present the merchant can decide in runtime whether the CPR validation is needed or not. A callback URL parameter can be for example: AskForCprCallback=https://someone.com/AskCpr?pid=@IdProviderPersonId@.

Process details: a GET to the URL will be issued by ZignSec with the PID from NemID-login replaced at @IdProviderPersonId@. If the response json is {"askForCpr":true} this means we should next show the CPR entry dialog and run CPR validation step. The validated CPR will be stored as usual in the PersonalNumber field in the identity response. Observer that all other return values or errors will result in the dialog NOT be shown and the CPR validation can not be run.

Our recommendations: * Since the PID is always returned it can be stored together with a verified CPR after first NemID login, and then on the next visits you don’t need to show the CPR dialog since the PID can be used as the unique lookup key to find the known customer. * Also keep in mind that if the customer´s CPR is known in advance it can be sent in with the PersonalNumber parameter with the NemID initiation, and the CPR will be silently verified with a Match call and if correct be put in the PersonalNumber response field.

No
login_hint

Only works with Norwegian BankID and when method is set to nbid_oidc, see https://confluence.bankidnorge.no/confluence/pdoidclpp/technical-documentation/core-concepts/identity-providers.

For example BID restricts to web login, BIM restricts to mobile login, BID:07025312345 restricts to person with given national identity number and omits the first user dialog, BID:07025312345 performs the same person restriction but keeps the initial selection dialog for selecting between web and mobile login.

No
userVisibleDataOnly works with Swedish BankID Signing. The text message to be signed by an end user. Must be UTF-8 and Base64 encoded. Max 40’000 characters. CR/LF/CRLF means new line.Yes (at Signing)
userNonVisibleDataOnly works with Swedish BankID Signing. Optionally used for document or message hashes. Must be UTF-8 and Base64 encoded. Max 200’000 characters.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.

For a response example go here.

No
webhook

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 show the QR-code on the waiting form.

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
allowRetries

Optional, default is false. Allows for building long-running login workflows, ex sending the redirect_url with an email, and allow the user to make many attempts to login. The redirect_url link in the response also has a time-out period parameter set through merchant settings called RedirectUrl_ExpirationInMinutes_Test / RedirectUrl_ExpirationInMinutes_Prod.

Default expiration setting is 7 days.

Example:{ "allowRetries": true }

No
Scope

Only works with Norwegian BankID . Following scope values can be used as space separated string: nnin, address, phone, email– will prompt end user consent for sharing data; nnin_altsub – will not prompt end user consent for sharing data.

Note: nnin_altsub can’t be used for onboarding new customers if you don’t already process their national identity number. For onboarding purposes, nnin  must be used, which prompt end user consent for storing this data point.

Example:{ "Scope": "nnin address phone" }

Above example will prompt consent to provide national identity number, address and phone.

No
PEP_Check

Works with nbid_pep only. Configures Environment and DataSource (See Watchlist DataSource for more information) for PEP Check.

Example:

{
"PEP_Check": {
"DataSource":"GLOBAL",
"Environment":"Test"
}
}

No

Layouts

There are different layouts, that can be chosen dynamically or configured statically, for determining the BankID app triggering during the browser workflow in the Swedish BankID integration /sbid

It is always possible to start the BankID app by a button click.

Layout2

 DesktopAndroidiOS
Autostart BankID app (without user gesture/button-click)YesNoNo
Redirect after loginTo previous appTo previous appTo previous app (need to click back button in app)

Layout3 (default layout)

 DesktopAndroidiOS
Autostart BankID app (without user gesture/button-click)YesNoYes
Redirect after loginTo previous appTo previous appTo previous or default browser (new tab will be created)
Need https://zignsec-cdn.azureedge.net/scripts/zignsecautostart.js on websiteYes

Layout4

    • Use click on button without redirect to another page, just load iframe on the same page
 DesktopAndroidiOS
Autostart BankID app (without user gesture/button-click)YesYesYes
Redirect after loginTo previous appTo previous appTo previous or default browser (new tab will be created)
Need https://zignsec-cdn.azureedge.net/scripts/zignsecautostart.js on websiteYes

Response

idA unique session identifier generated for each workflow instance.
errorsA JSON array of error conditions, see error handling FAQ
redirect_urlThe URL that the user needs to be redirected to complete the data via the web interface. It is possible to load the URL in an iframe. Timelife of url can be managed over the settings RedirectUrl_ExpirationInMinutes_PROD / RedirectUrl_ExpirationInMinutes_TEST.

Error Codes

CodeDescription
INVALID_PERSONALNUMBERInvalid Personal number, for example missing
INVALID_APPIDInvalid AppId
MISSING_CONFIGYour account has a missing config, contact ZignSec for help
INVALID_REQUESTSomething unexpected has gone wrong, contact ZignSec for help

Note: For Swedish BankID integrations google for and read the BankID Relying Party Guidelines which describes all API calling details such as parameters, return values and error conditions.

Setup-request Example:  (sbid-another=app on any device)

POST https://test.zignsec.com/v2/eid/sbid-another HTTP/1.1
Authorization: 00000000-e2a2-4968-b651-5352305c9fb0
Content-Type: application/x-www-form-urlencoded
Host: test.zignsec.co

target=http%3A%2F%2Flocalhost%3A8080%2Fzignsec%2Freturn

Setup-response example

{
  "id":"ebe756c4-24db-4eb7-8b54-874434f212ec",
  "errors":[],
  "redirect_url":"https://test.zignsec.com/v2/Hosted/ebe756c4-24db-4eb7-8b54-874434f212ec/sbid-another/"
}

Setup-request SwissID Example

POST https://test.zignsec.com/v3/eid/swissid HTTP/1.1
Authorization: 00000000-e2a2-4968-b651-5352305c9fb0
Content-Type: application/json

{
	"scopes": "openid profile email phone",
	"webhook": "https://my.site/webhook",
	"target": "https://my.site/logged-in",
	"targetError": "https://my.site/error",
	"relayState": "my-session-id",
	"environment": "Test",
	"language": "en",
	"acrValues": "qoa1"
}

Step 2. Run the login workflow

Simply navigate to the redirect_urlto start the login workflow in a browser. It may be convenient to load the URL into an HTML IFrame element to get a windowed login integration in an existing web site. In parallel, a separate eID session is handshaked in the background either on the server (Sweden) or in the client with Javascript (Denmark and Norway).

Contact ZignSec to setup custom CSS for Html IFRAME.

Step 3. Get status/results

GET from https://env.zignsec.com/v2/eid/sessionid
where 
env is API or test
sessionid is retrieved in the setup call, named id in the response.

How to get notified of Workflow Finished

There is both active and passive notification for when the workflow is finished:

  • Callback: Set Target URL parameter in step 1 and when the target URL is navigated you can do the above collect-GET.
  • Webhook. To set up a webhook URL for callback, contact ZignSec. Results will be posted to the URL, see this example.
  • Polling: Repeatedly call the above collect-GET until the results contain a final result.

Response

idA unique session identifier generated for each workflow instance.
errorsA JSON array of error conditions, see error handling.
result

Note: This node is missing (deemed unnecessary) if the authentication is successful, ie when a identity node is present.

An object that describes the main result of the service call. It contains the following parameters:

Identity
The results for the Identity service are collected under this identity sub-item

state
Indicates whether the verification of the customer is completed or not. Possible values are PENDING, FINISHED, ERROR.
PENDING is a temporary state indicating that the user is involved in the process
FINISHED is a final state showing that the customer has completed the entire process and the call has a final result.
ERROR is a final state showing that the customer has completed with error, like timeout, aborted, exception.

Identity

This is a verified identity of the customer. The following parameters can be found in this object.

CountryCodeRepresents the ID providers country belonging. And consequentially the identified persons nationality.
FirstNameCan be an extraction from a full name depending on the ID provider.
LastNameCan be an extraction from a full name depending on the ID provider.
PersonalNumberSweden: This is always returned for Swedish BankID. BankID in Norway only returns personalNumber if that is configured on the BankID certificate with the Bank for an extra call charge. Denmark: does not per default give back the personal number, but needs extra set ups to do this. General Rule: If a non-empty PersonalNumber is returned from an identification you can always be sure that it is has been validated on the backend.
DateOfBirthAlways present. All Nordic eID (ie Sweden, Norway, Denmark) providers sends back the date of birth.
AgeNormally computed from the DateOfBirth and the current date at the time of identification.
PhoneNumberNormally not set. May be set by Banking API authentications. From BankID on Mobile in Norway phone number will be set.
EmailNormally not set. May be set by Banking API authentications.
IdProviderNameZignSec’s name for the Identity provider, for example BankIDSE, BankIDNO, NemID or BankingAPI.
IdentificationDateThe time the identification was performed.
IdProviderRequestIDNot always set. The identity provider’s unique id for the identification request. For easier tracking.
IdProviderPersonIDAlways set in NemID, BankIDNO and BankingAPI responses, but not in Swedish BankID. A persistent value, a technical key that uniquely identifies the person authenticated taken from the BankID id-provider. It is over time a as uniquely identifying of the person as the public personal number, so it is a non-public substitute for the personalNumber, and can be stored away for later comparison for next bankID logins – this is useful when the identity provider does not deliver the personalNumber in the response per default, such as the case with Danish NemID and Norwegian BankID. For NemID and Norway´s BankID the certificate serial number is stored here. The serial number is guaranteed to be the same, no matter the device and method being use for login/authentication, for example the same key is used in Norway for both BankID for mobile and BankID for web. In Norwegian BankID this key has this format (an example): 9578-5997-4-3154736.
CustomerPersonIDThe eID product has the possibility to save a customer specific reference for the person, to enable simplified login processes. If such a number was sent in, it will be shown here for completeness sake.
methodThe name of the method initiated, for Examplesbid” or “sbid-another
BankIDSEThis sub item contains certificate validation data only relevant to the Swedish BankID. signature This is for tracking and source verification of the total result returned from the Swedish BankID, both for the Authenticate and the Sign processes. The content is long a base64-encoded xmldsig document – the IETF-standard for signing of Xml . It contains for example the signed object in parsable format, and the result in element after signing with the merchant’s X509-certificate. Validity can be checked with standard methods available for example in .Net framework. ocspResponse This is for tracking and source verification of the customer certificate used in the Swedish BankID, both for the Authenticate and the Sign processes.

Example response

{
      "identity": {
            "CountryCode": "SE",
            "FirstName": "RAGNAR PER",
            "LastName": "GREN",
            "FullName": "RAGNAR PER GREN",
            "PersonalNumber": "198711260070",
            "DateOfBirth": "1987-11-26",
            "Age": 30,
            "IdProviderName": "BankIDSE",
            "IdentificationDate": "2018-09-19T11:53:46.4726217+02:00",
            "IdProviderRequestId": "",
            "IdProviderPersonId": "",
            "CustomerPersonId": ""
      },
      "BankIDSE": {
            "signature": "base64 too long to display ...",
            "ocspResponse": "base64 too long to display ..."
      },
      "method": "sbid-another"
}; 

Example response when LookupPersonAddress=true

{
      "identity": {
            "CountryCode": "SE",
            "FirstName": "RAGNAR PER",
            "LastName": "GREN",
            "FullName": "RAGNAR PER GREN",
            "PersonalNumber": "198711260070",
            "DateOfBirth": "1987-11-26",
            "Age": 30,
            "IdProviderName": "BankIDSE",
            "IdentificationDate": "2018-10-26T11:38:39.7515839+02:00",
            "IdProviderRequestId": "",
            "IdProviderPersonId": "",
            "CustomerPersonId": ""
      },
      "BankIDSE": {
            "signature": "base64 too long to display ...",
            "ocspResponse": "base64 too long to display ..."
      },
      "LookupPersonAddress": {
            "PersonStatus": "",
            "FirstName": "Ragnar Per",
            "LastName": "Gren",
            "MainFirstName": "Ragnar",
            "Address": "Tranvägen 4",
            "Address2": null,
            "PostalCode": "18452",
            "Location": null,
            "City": "Sollentuna",
            "Province": null,
            "CountryCode": "se",
            "Phone": null,
            "PhoneNumbers": [
                  "08-51234567",
                  "073-1234567"
            ],
            "Email": null,
            "DateOfBirth": "19871126",
            "BirthYear": 1987,
            "BirthMonth": 11,
            "BirthDayOfMonth": 26,
            "Age": 30,
            "PersonalNumber": "198711260070",
            "_DataSource": "DP05"
      },
      "method": "sbid-another"
}