ZignSec

eID: BankID in browser -se -dk -no

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. Runs the workflow in a browser.

See also: Some technical facts about the Swedish BankID

Note: Recently added parameters lookupPersonAddress and targetError

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.

Call Order

Web Portals for the National Identity Providers

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 url Description
sbid-another Swedish 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
sbid Swedish 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
sbid-sign Swedish BankID Signing. These two parameters are a requirement: PersonalNumber and UserVisibleData. UserNonVisibleData is optional.
nemid Danish NemID Authentication.
nbid_oidc Norwegian 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.
nbid Norwegian BankID web Authentication. Forwards to nbid_oidc with loginhint = BID
nbid_mobile Norwegian 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.

Authorization This header parameter is the personal access token you received from ZignSec during the registration process.
Example: Authorization: 00000000-e2a2-4968-b651-5352305c9fb0
Required
Content-Type Specifies 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-urlencoded
Required
Host Use test.zignsec.com for test enviroment and api.zignsec.com for production enviroment.
Example: api.zignsec.com
Required

Setup-request Description

Parameter Description Required
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 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
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 Webhooks 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 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
targetError targetError works as target except it is navigated on user cancel or error situations. No
layout If other html-layout is preferred ohter than the customer’s default setup. 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-insenitive. No
custom Any customer specific data. No
AskForCpr Only 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 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_info For 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_hint Only 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
userVisibleData Only 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)
userNonVisibleData Only 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. For a response example go here. No

Setup-response Description

id The session identifer, a guid (globally unique identifier) unique for the started workflow, used both in the redirect_url and the "get results url".
errors A 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_url The 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.

Example of Response Error Codes:

Code Description
INVALID_PERSONALNUMBER Invalid Personal number, for example missing
INVALID_APPID Invalid AppId
MISSING_CONFIG Your account has a missing config, contact ZignSec for help
INVALID_REQUEST Something 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

id The session identifier – the workflow’s unique identifier (guid) created created in the setup call.
errors A 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 : []
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.
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.

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

CountryCode Represents the ID providers country belonging. And consequentially the identified persons nationality.
FirstName Can be an extraction from a full name depending on the ID provider.
LastName Can be an extraction from a full name depending on the ID provider.
PersonalNumber Sweden: 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.
DateOfBirth Always present. All nordic eID (ie Sweden, Norway, Denmark) providers sends back the date of birth.
Age Normally computed from the DateOfBirth and the current date at the time of identification.
PhoneNumber Normally not set. May be set by Banking API authentications. From BankID on Mobile in Norway phone number will be set.
Email Normally not set. May be set by Banking API authentications.
IdProviderName ZignSec’s name for the Identity provider, for example BankIDSE, BankIDNO, NemId or BankingAPI.
IdentificationDate The time the identification was performed.
IdProviderRequestId Not always set. The identity provider’s unique id for the identification request. For easier tracking.
IdProviderPersonId Always 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.

CustomerPersonId The 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.
method The name of the method initiated, for

Examplesbid” or “sbid-another

BankIDSE This 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"
}