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

         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

ParameterDescriptionRequired
metadataSee table belowYes
ParameterDescriptionRequired
localePreferred Language to Use
redirect_successURL to redirect the end-user to on successNo
redirect_failureURL to redirect the end-user to on failureNo
relay_stateOptional Custom Parameter to be included in webhook calls
webhookA URL where success/error results will automatically be POST:edNo
personalnumberSet 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.

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_urlstep2 : 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.

idSession ID
redirectUrlThe URL that the user needs to be redirected to complete the session
stateStatus of the Session

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

 

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"
  }
}
signedIdentityRepresents 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.
AgeNormally computed from the DateOfBirth and the current date at the time of identification.
CountryCodeRepresents the ID providers country belonging. And consequentially the identified persons nationality.
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.
DateOfBirthAlways present.  sends back the date of birth.
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.
IdProviderNameZignSec’s name for the Identity provider, for example -BankIDSE
IdProviderRequestIDNot always set. The identity provider’s unique id for the identification request. For easier tracking.
IdentificationDateThe time the identification was performed.
PersonalNumberSweden: 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.