v5 - eID: BankID -SE - ZignSec Docs

BankID in Browser is an integration with the standard national electronic authentication methods with support for BankID in Sweden.

The login workflow runs in a ZignSec controlled browser session.

Swagger Links :

Test Swagger – Swagger UI (zignsec.com)

Prod Swagger – Swagger UI (zignsec.com)

Call Sequence

Step1 – Set up session .The returned redirect_url is used for starting the browser workflow, identified by sessionid.
Step2 – Run the login workflow. Simply navigate to the redirect_url in a web browser. The workflow’s user interactions include an external device like the Swedish mobile BankID.
Step 3 -Get status/results. Collect status and data about the logged in person, using the unique workflow sessionid code. Make this call during or after the workflow is completed. The workflow can signal the status pending, completed or error (exception, user abort, timeout) via a browser redirect to the target URL and/or via a configured webhook.

Step 1 - Set up session

1.1 Start session

POST to Zignsec URL:

Test Env : https://test-gateway.zignsec.com/core/api/sessions/identity_verification/bankid_se

Production : https://gateway.zignsec.com/core/api/sessions/identity_verification/bankid_se

1.2 Request example

{
  "locale": "En",
  "metadata": {},
  "redirect_failure": "https://my_failure_url.com",
  "redirect_success": "https://my_success_url.com",
  "relay_state": "my-unique-customer-id",
  "webhook": "https://my_webhook_url.com"
}

1.3 Description of request example

Parameter	Description	Required
`metadata`	See table below	Yes

Meta data parameters

Parameter	Description	Required
`locale`	Preferred language to use. Possible values Se (Swedish) \| En (English)	No
`redirect_success`	URL to redirect the end-user to on success	No
`redirect_failure`	URL to redirect the end-user to on failure	No
`relay_state`	Optional Custom Parameter to be included in webhook calls	No
`webhook`	A URL where success/error results will automatically be POST:ed	No
`personalnumber`	Set up of identity number. Only this specific person can be identified; No need to fill in PersonalNumber; The BankID app starts up for this person only.	No

1.4 Response example

{
  "data": {
    "id": "90bf10dd-0fab-407a-8b17-4bb9fa847e2e",
    "redirect_url": "https://test.zignsec.com/v2/Hosted/90bf10dd-0fab-407a-8b17-4bb9fa847e2e/sbid-another/",
    "status": "created"
  }
}

step 1: Authenticate BankID with Personal Number with redirect_url	step2 : BankID app to be opened in step 2. You can also cancel the session from UI.

1.5 Description of response model

Each request returns a response with status and details.

`id`	Session ID
`redirectUrl`	The URL that the user needs to be redirected to complete the session
`status`	Created, Pending, Finished, Failed, Declined

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

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 on the server (Sweden)

Contact ZignSec to setup custom CSS for Html IFRAME.

Step 3 - Get status/results

GET to

Test Env : https://test-gateway.zignsec.com/core/api/sessions/90bf10dd-0fab-407a-8b17-4bb9fa847e2e

Production : https://gateway.zignsec.com/core/api/sessions/90bf10dd-0fab-407a-8b17-4bb9fa847e2e

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.

3.1 Get response example

{
  "data": {
    "signedIdentity": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImE1ZTk3NTZmLTgxMzItNDdhYy1hZmY3LTE5Y2FjMjY0ZTQ0MCIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3ppZ25zZWMudGVzdC5taXRpZC5kay8iLCJpYXQiOjE2NTIzNDE0MDIsIm5iZiI6MTY1MjM0MTQwMiwiZXhwIjoxNjUyMzQ1MDAyLCJpZGVudGl0eSI6eyJhZ2UiOjUyLCJjb3VudHJ5Q29kZSI6IlNFIiwiY3ByTnVtYmVyTWF0Y2giOnRydWUsImN1c3RvbWVyUGVyc29uSWQiOiIiLCJkYXRlT2ZCaXJ0aCI6IjE5NzAtMDEtMTAiLCJmaXJzdE5hbWUiOiJMaW5kYSBNYXJpZSIsImZ1bGxOYW1lIjoiTGluZGEgTWFyaWUgSGFzc2FuIEFobWVkIiwiZ2VuZGVyIjoiRiIsImlkUHJvdmlkZXJOYW1lIjoiQmFua0lEU0UiLCJpZFByb3ZpZGVyUGVyc29uSWQiOiIiLCJpZFByb3ZpZGVyUmVxdWVzdElkIjoiIiwiaWRlbnRpZmljYXRpb25EYXRlIjoiMjAyMi0wNS0xMlQwNzo0MzoyMi4wMDkxMDcyWiIsImxhc3ROYW1lIjoiSGFzc2FuIEFobWVkIiwicGVyc29uYWxOdW1iZXIiOiIxOTcwMDExMDIyMjIifX0.jNXJYW7s5NDVi_QXyCApfWHBKE-bqEe__BHTAFx3qrESjel8swxcVrYi12qttODgHKPAJxVLVtsnrKBA43MvLwQXnI1UdY1u2o1xA67CbCTYVOv0MnalWPY-iIKXU9xxDYYvLQhd8S8tLe3NRqAeYOOrjdygFMwuWQ3TSxgGFr31jdJAsvJwlWH3ce1DLUjMPWCfZHuVFyKXqLQsn16fa6mE3LuD_eptIhpYeCCVSaHedbbFrGpytBqCIc4gUU4Dl7TASY-gkW78_e23ailKu-0NWQXGS_imc-hm2G7tSLu5B8rienzXJrT-2R6t_3cpy-ezxchwBgvUNZhvOWhMMA"
  }
}

signedIdentity Represents result with a signed identity in a JSON Web Token form, see JWT-signature.

3.2 Decoded Get Response

The signed identity can be decoded with JWT Web Token convertors, see JWT convertor tool.

{
  "iss": "https://zignsec.test.mitid.dk/",
  "iat": 1652341402,
  "nbf": 1652341402,
  "exp": 1652345002,
  "identity": {
    "age": 52,
    "countryCode": "SE",
    "cprNumberMatch": true,
    "customerPersonId": "",
    "dateOfBirth": "1970-01-10",
    "firstName": "Linda Marie",
    "fullName": "Linda Marie Hassan Ahmed",
    "gender": "F",
    "idProviderName": "BankIDSE",
    "idProviderPersonId": "",
    "idProviderRequestId": "",
    "identificationDate": "2022-05-12T07:43:22.0091072Z",
    "lastName": "Hassan Ahmed",
    "personalNumber": "197001102222"
  }
}

3.3 Response Body Description

`iss`	(issuer) claim identifies the principal that issued the JWT . Note : This endpoint response will be updated and can be ignoed at the moment.
`iat`	(issued at) claim identifies the time at which the JWT was issued
`nbf`	(not before) claim identifies the time before which the JWT MUST NOT be accepted for processing.
`exp`	(expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.
`Age`	Normally computed from the DateOfBirth and the current date at the time of identification.
`CountryCode`	Represents the ID providers country belonging. And consequentially the identified persons nationality.
`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.
`DateOfBirth`	Always present. sends back the date of birth.
`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.
`IdProviderName`	ZignSec’s name for the Identity provider, for example -BankIDSE
`IdProviderRequestID`	Not always set. The identity provider’s unique id for the identification request. For easier tracking.
`IdentificationDate`	The time the identification was performed.
`PersonalNumber`	Sweden: This is always returned for Swedish BankID. 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.

Our APIs

v5 – eID: BankID -SE