Customizing the GUI experience

Work in progress

This page is under re-construction

The default GUI experience of the BankID OIDC Service can be overridded and replaced by a customized implementation as described in the following.

Please see source code on GitHub for an example on how to implement such a GUI customization. (TODO: Publish such an example)

GUI customization demands that OIDC Client is configured with a specific "presentationURL" paramter with the OIDC Service overriding the URL of the landing page for the default GUI.

Any GUI implementation (called "BidViewer" in the below diagramme) will interoperate with the BankID OIDC Service (the "BINAS Realm") as following:

The authentication alternatives are

BIM: BankID på Mobil and
BID: Netcentric BankID.

The initial request to BidView will contain two parameters:

sid - a session ID which must be used in all communication with BankID OIDC.
oidcAuthenticationUrl - base address of the BankID OIDC API. The GUI implementation must use REST-services exposed by this API.

Here is a list of REST endpoints to be used by BidView (GUI) whith explanations:

Address	Functionality
bimfinished	This is a polling function to be notified when a BankID på Mobil authentication has ended (hopefully with success). Http status code 200 is used to indicate that BankID OIDC has got the terminating "verifyAuth" or "handleError" notifications. Http status code 204 is returned while the authentication is still in process.
queryGUI	When the BidView (GUI) is called, with sid (session ID) as parameter, it can send a queryGUI request to get session based info in return: applicationName - application name of the client to be used in dialogues. merchantName - merchant name for this BankID session to be used in dialogues. ui_locales - list of language options to use for dialogues bankidLocale - the language option to use for BankID dialogues ('nb' or 'en') cancelUrl - a redirect address if user hits the cancel button clientType - BIM or BID (BankID mobile or netcentric) phoneNo - If specified to be used for BIM authentication birthday - If specified to be used for BIM authentication nnin - If specified to be used for BID authentication.
startBID	Start the merchant back end session for Banklagret BankID. Input parameters: sid - session ID nnin - (optional) 11 digit Norwegian national ID/fødselsnummer bankidLocale (optional) BankID language setting ('nb' or 'en'). Returned parameters: returnUrl - where to redirect when authentication is finished. bidHelperUri - address of the BankID startscript (with Init() method). cid - the backend session ID errorCode and errorMsg if call failed.
startBIM	Initiate a BankID på Mobile authentication Input: sid - session ID phoneNo - Mobile phone number (8 digits) birthday - DDMMYY bankidLocale - (optional) Language setting (currently only Norwegian is offered). Returned: returnUrl - address where to return after authentication is finished mobilePollerUrl - where to require if BIM authentication is finished (see "bimfinished" above). merchantReference - the words to display for the user to verify on phone message. errorCode and errorMsg - (optional) if call failed.
consents	When the GUI shall build the consent screen this REST-call is needed to retrieve information. Input: sid -session ID Returned: replyHref - an incomplete address to use the consent. It is made complete by appending "allow" or "deny" depending upon user's choice. application - application name to be displayed in dialog. merchantName - name of the BankID merchant personName - name of the user scopes - a space separated list of scope names we need concent on. bankidLocale - language of the dialog. errCode and errMsg - (optional) if error occurs.
cancel	This is used for handling the user canceling out of BankID authentication or concent screen notifying BankID OIDC backend. Input is sid - session ID.

To be able to display a concent screen like the one below, some extra information needs to be stored connected to each scope used by the OIDC Client. BankID OIDC will only give a list of scope names/IDs that requires user's consent. A description for each of those needs to be provided in the appropriate locale.

Norwegian	English