On another device

Configuration

Based on the BankID documentation found here:

https://www.bankid.com/utvecklare/guider/teknisk-integrationsguide

Note

Authenticator type: BidOnOtherDevice

Common Authenticator configuration can be found here.

Properties

Name	Description	Default value	Mandatory
internal_http_destination	ID of the internal http client used to talk with BankID backend.	"default"	true
mode	Three modes are possible: "production", "test" & "custom". Depending on the mode, the URL used to talk to BankID differs.	"production"	false
custom_url	Defines a custom BankID backend URL. Only works if mode is set to "custom".	N/A	false
custom_identifier	When logging events, the custom_identifier lets you tag the event.	N/A	false
requirement	Specifications on client requirements based on BankID relying-party documentation.	N/A	true
poll_frequency	How often should client poll for status updates. In seconds.	2	true
allowed_polling_for_minutes	How many minutes is client allowed to keep polling.	2	true
webroot_dir	See common authenticator configuration	web/authenticator/bankid/osd	false

Example

{
  "id": "bidood",
  "type": "BidOnOtherDevice",
  "config": {
    "base_path": "/test/authn",
    "internal_http_destination": "bid",
    "webroot_dir": "web/authenticator/bankid/osd",
    "overlay_dir": "authenticator/bankid/osd/overlay"
  }
}

Caution

Property base_path should not contain the full path when used in conjunction with the Selector, instead, the full URI will be handled by the selector. The full path will be base_path + / + id.

Logging

Apart from system logging, event logging is done when starting, completing, and failing a BankID transaction.

Event ids are:

• WEB_100001, BankID authentication started
  • IDENTIFIER (user trace id)
  • SOURCE_ADDRESS (ip address of device starting transaction)
  • SOURCE_USER_NAME (personal number)
  • CUSTOMER_IDENTIFIER (if configured)
  • AUTHENTICATOR_IDENTIFIER (id and display name)
• WEB_100002, BankID authentication completed
  • IDENTIFIER (user trace id)
  • SOURCE_ADDRESS (ip address of the BankID device used)
  • CUSTOMER_IDENTIFIER (if configured)
  • SOURCE_USER_NAME (personal number)
  • AUTHENTICATOR_IDENTIFIER (id and display name)
  • SURNAME
  • GIVENNAME
• WEB_100003, BankID authentication failed
  • IDENTIFIER (user trace id)
  • SOURCE_ADDRESS (ip address of the BankID device used)
  • MESSAGE (information)
  • AUTHENTICATOR_IDENTIFIER (id and display name)
• WEB_100004, BankID authentication canceled or expired
  • IDENTIFIER (user trace id)
  • SOURCE_ADDRESS (ip address of the BankID device used)
  • AUTHENTICATOR_IDENTIFIER (id and display name)

Data exposed to global state

After a user completes a transaction, the authenticator is marked as done. Data from the BankID authentication response is then put into the global state:

• givenName
• surname
• name
• personalNumber
• ipAddress
• ocsp
• signature

Note that it is not guaranteed that all parameters hold value.

API

When communicating with the backend this describes the

General requirements

Backend communications are made using AJAX and the HTTP PUT method. Every request need a Content-Type with the value of application/json.

Messages

Message	Purpose
state	Fetch the current status. Send it when the view loads and then poll with it.
start	Start a BankID transaction.
cancel	Cancel the transaction.

Getting state

Body must conform to the example below.

{
    "type": "state"
}

Starting an authentication

To start authentication send AJAX request containing the user's "personnummer" (12 digits).

{
    "type": "start",
    "data": {
        "pnr": "<user_data>"
    }
}

Cancel a request

A request can be canceled at any time. This is done by sending a cancel request.

{
    "type": "cancel"
}

Response from server

In general, you should expect a server response with http status code 200. Anything else is to be considered an error.

Response body will be in the form of a JSON object. Typically the response looks like:

{
    "bidstatus": "ABOUT_TO_START"
}

The property "bidstatus" will contain status.

Possible status messages

One of the following status codes is returned based on the current state.

• ABOUT_TO_START
• PENDING
• COMPLETE
• BID_ERROR
• ERROR
• OUTSTANDINGTRANSACTION,
• NOCLIENT
• STARTED
• USERSIGN
• EXPIREDTRANSACTION
• STARTFAILED
• CANCELLED
• USERCANCEL
• CERTIFICATEERR

Translation keys

Default translations provided:

English, assets/locales/en.json

{
  "bankid.ood.personal_identity_number": "Personal identity number",
  "bankid.ood.start_authentication": "Start authentication",
  "bankid.ood.open_bankid_app": "Open BankID app",
  "bankid.ood.bankid_app_opened": "BankID app opened",
  "bankid.ood.open_bankid_app_on_this_device": "Log in using BankID on this device",
  "bankid.ood.verify_authentication": "Verifify identification",
  "bankid.ood.authentication_verified": "Identification verified",
  "bankid.ood.redirecting": "Redirecting...",
  "bankid.ood.start_bankid_app": "Start your BankID app.",
  "bankid.ood.cancel": "Cancel",
  "bankid.ood.BID_ERROR": "Unknown error. Please try again.",
  "bankid.ood.ERROR": "Unknown error. Please try again.",
  "bankid.ood.NOCLIENT": "Starting the BankID application failed",
  "bankid.ood.EXPIREDTRANSACTION": "The BankID app is not responding. Please check that the program is started and that you have internet access. If you don’t have a valid BankID you can get one from your bank. Try again.",
  "bankid.ood.STARTFAILED": "The BankID app couldn’t be found on your computer or mobile device. Please install it and order a BankID from your internet bank. Install the app from your app store or https://install.bankid.com.",
  "bankid.ood.CANCELLED": "Action cancelled. Please try again.",
  "bankid.ood.USERCANCEL": "Action cancelled. Please try again.",
  "bankid.ood.CERTIFICATEERR": "The BankID you are trying to use is revoked or too old. Please use another BankID or order a new one from your internet bank.",
  "allow-cookies-body": "To save your language settings on this device you need to approve a language cookie.",
  "allow-cookies-button": "Approve language cookie",
  "authentication.help_text": "",
  "change_language": ""
}

Swedish, assets/locales/sv.json

{
  "bankid.ood.personal_identity_number": "Personnummer",
  "bankid.ood.start_authentication": "Starta verifiering",
  "bankid.ood.open_bankid_app": "Öppna BankID-appen",
  "bankid.ood.bankid_app_opened": "BankID-appen öppnad",
  "bankid.ood.open_bankid_app_on_this_device": "Logga in med BankID på den här enheten",
  "bankid.ood.verify_authentication": "Verifiera legitimering",
  "bankid.ood.authentication_verified": "Legitimeringen verifierad",
  "bankid.ood.redirecting": "Omdirigerar...",
  "bankid.ood.start_bankid_app": "Starta BankID-appen",
  "bankid.ood.cancel": "Avbryt",
  "bankid.ood.BID_ERROR": "Okänt fel. Försök igen.",
  "bankid.ood.ERROR": "Okänt fel. Försök igen.",
  "bankid.ood.NOCLIENT": "Start av BankID applikationen misslyckades",
  "bankid.ood.EXPIREDTRANSACTION": "BankID-appen svarar inte. Kontrollera att den är startad och att  du har internetanslutning. Om du inte har något giltigt BankID kan du hämta ett hos din Bank. Försök sedan igen",
  "bankid.ood.STARTFAILED": "BankID-appen verkar inte finnas i din dator eller telefon. Installera den och hämta ett BankID hos din internetbank. Installera appen från din appbutik eller https://install.bankid.com.",
  "bankid.ood.CANCELLED": "Åtgärden avbruten. Försök igen",
  "bankid.ood.USERCANCEL": "Åtgärden avbruten. Försök igen",
  "bankid.ood.CERTIFICATEERR": "Det BankID du försöker använda är för gammalt eller spärrat. Använd ett annat BankID eller hämta ett nytt hos din internetbank.",
  "allow-cookies-body": "Vill du spara dina språkinställningar på denna enhet behövs ett godkännande av  språk-cookie.",
  "allow-cookies-button": "Godkänn språk-cookie",
  "authentication.help_text": "",
  "change_language": ""
}

Exposed metric

Gauges

ffidAuthnHttp_pending.name.<authenticator_id>_collect - indicates how many collect requests hans been sent out and is awaiting response

ffidAuthnHttp_pending.name.<authenticator_id>_start - indicates how many start requests hans been sent out and is awaiting response

Meters

ffidAuthnHttp_failure.name.<authenticator_id>_collect - indicates number of failed status collects.

ffidAuthnHttp_failure.name.<authenticator_id>_start - indicates number of failed bank id start.

ffidAuthnHttp_success.name.<authenticator_id>_start - indicates number of successful bank id starts

ffidAuthnHttp_success.name.<authenticator_id>_collect - indicates number of successful bank id

collects

Timers

ffidAuthnHttp_request.name.<authenticator_id>_collect - Tracks the time of a collect round trip.

ffidAuthnHttp_request.name.<authenticator_id>_start - Tracks the time of a collect round trip.