BankID in Browser is an integration with the standard national electronic authentication methods in the Nordic with support for BankID in Sweden, NemID in Denmark and BankID in Norway, where the login workflow runs in a zignsec controlled browser session. Here you can find the three nordic eID provider’s public web portals.

Some technical facts about the Swedish BankID

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 and bankid_selector is for example sbid_another, nbid_oidc or nemid, see the bankid_selector alternatives below. and sessionid is the worklow’s identifier retrieved from the setup call.

Recent changes: * (sbid) For autostart of the Swedish BankID app from an IFRAME the following script needs to loaded on the container page: script src=”https://zignsec-cdn.azureedge.net/scripts/zignsecautostart.js” * Added parameters lookupPersonAddress and targetError

Call Order

Step 1. Call our API entry point to set up a login workflow

API Entry Point

POST to https://env.zignsec.com/v2/eid/bankid_selector where env is api or test and 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], ie 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: script src=”https://zignsec-cdn.azureedge.net/scripts/zignsecautostart.js”
sbid-signSwedish BankID Signing. These two parameters are a requirement: PersonalNumber and UserVisibleData. UserNonVisibleData is optional.
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 loginhint = BID
nbid_mobileNorwegian BankID web Authentication. Forwards to nbid_oidc with loginhint = BIM
[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.

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 enviroment and api.zignsec.com for production enviroment. Example: api.zignsec.comRequired

Setup-request Description

ParameterDescriptionRequired
personalnumberSet 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 personal number; 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, wherafter 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
relaystateThis 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_1234No
configidHere 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 Webhooks calls. If only one configuration it is used automatically. Example: configid=d638a4ab-7382-4c5d-98e8-e90d3aa3e1beNo
targetIf this parameter is supplied the browser session will finally be redirected to this URL-value. The URL-parameter value must 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 reslaystate is ZignSec’s session token (RequestId) which can be used to 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
languageDecides 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-insenitive.No
customAny customer specific data.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
AskForCprCallbackOnly 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 wether 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 inititiation, and the CPR will be silently verified with a Match call and if correct be put in the PersonalNumber response field.No
Additional_identity_infoFor future configuration use in Norwegian BankID. (TBD: If this parameter is set to true, and the merchant certificate is configured for TINFO (extra info), then an extra TINFO call is going to be made on the backend, to get extra fields such as address, phone number and email in the response (this feature will be made availalble in June 2018 by BankID Norway))No
login_hintOnly works with Norwegian BankID and when method is set to nbid_oidc, see https://confluence.bankidnorge.no/confluence/pdoidclpp/technical-documentation/identity-providers/bankid/login-hint. 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, :07025312345 performs the same person restriction but keeps the inital 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
lookupPersonAddressCurrently 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
requirementNOTE: 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
allowRetriesOptional, 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

Setup-response Description

idThe session identifer, a guid (globally unique identifier) unique for the started workflow, used both in the redirect_url and the "get results url".
errorsA JSON object that contains information on error conditions that might have resulted from the request, in an array of property-value pairs. If multiple errors occur, a pair of parameters is returned for each error. code Code for the error. List of codes is in table below. description A string that describes the type of error that occurred.If no errors occur, then this object is empty. errors : []
redirect_urlThe URL that the user need 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.

Example of Response 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.com
Content-Length: 46

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/"
}

Step 2. Start the login workflow in a web browser

Simply navigate to the redirect_url, this will start the login workflow in a browser. You can run the workflow in an Html IFRAME to naturally have the login appear in a window in the 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).

Step 3. Get status/results: Call our API to retrieve status/error or collected user identity data

API Endpoint

GET from https://env.zignsec.com/v2/eid/sessionid where env is api or test and sessionid is the workflow identifier retrieved in call 1 (named ‘id’ in the response).

Triggering

You can be signalled about when to retrieve the results in many ways. * Callback: Set Target url and when navigatet to do the Collect results call. * Webhook. To set up a webhook URL for callback, contact Zignsec. Results will be POST:ed to the URL, see this example. * Polling: Do a GET repeatedly until results are in the response.

Identity Response Description

idThe session identifier – the workflow’s unique identifier (guid) created created in the setup call.
errorsA JSON object that contains information on error conditions that might have resulted from the request, in an array of property-value pairs. If multiple errors occur, a pair of parameters is returned for each error. code Code for the error. List of codes is in table in the response section. description A string that describes the type of error that occurred.If no errors occur, then this object is empty. errors : []
resultNote: 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. PENDING is a temporary state indicating that the user is involved in the process FINISHED is a permanent state showing that the customer has completed the entire process and the call has a final result.
IdentityThis 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 substitue 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/authenticatuion, for example the same key is used in Norway for both BankID for mobile och 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 <Signature> 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.

Get Results – Request example

GET https://test.zignsec.com/v2/eid/bc539499-4953-4b54-8743-b1adb8d4de78/ HTTP/1.1
Authorization: 00000000-e2a2-4968-b651-5352305c9fb0
Content-Type: application/x-www-form-urlencoded
Host: test.zignsec.com

Get results – Response example 1

{
      "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"
}; 

Get results – Response example 2 (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"
}