Page tree
Skip to end of metadata
Go to start of metadata

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:

AddressFunctionality
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.

NorwegianEnglish

  • No labels