This section discusses the context and the environment in which the BankID components are to be used.

Implementation overview

When implementing BankID in a merchant application the developer needs to integrate the existing merchant application, the BankID client interface and the BankID server interface. The figure below illustrates how the merchant BankID implementation relates to each other.
The code needed for this integration is illustrated as the BankID integration implementation in the figure below and is described in subsequent chapters in this document. 

The use of BankID can be broken down into different steps. The next two chapters illustrate the different steps/tasks the merchant application needs to perform.

BankID on Mobile

Configuration and initialisation

Below is a list of the required tasks along with a reference to the applicable chapters that describe how to do the actual implementation. 

 

Step 1: Configure the BankID server
Please refer to:

• this document, 3.2.4.1 BankID server features
• [ICSRV], 4. Configuration of BankID C server
• [IJSRV], 3.1 Configuration of BankID J server

Step 2: Initialise the BankID server
Please refer to:

• [ICSRV], 5.1 Application start-up code
• [IJSRV], 4.1 Application start-up code

Authentication and Signing

Figure 12 below shows the tasks with a reference to the applicable chapters that describes how to do the actual implementation.

The end-user triggers a BankID on Mobile authentication or signing operation on the merchant web-page. The end-user is asked to enter mobile phone number and birthdate. The required GUI for a web-based sign operation is shown below. 
NOTE: The GUI referred to below is only applicable to web-based services. For SMS-based services special rules apply. Please see "BankAxess; Regler for brukerdialoger", requirement M3.

A BankAxess operation is a variant of the sign operation and have similar dialogs. The operation identifier when invoking requestMobileAction is 'netPay'.

 In case of authentication, two random words must be generated using the BankID server. These words are shown to the end-user as shown below.

 The BankID server is used to start the transaction towards the end-users mobile phone via the BankID COI Mobile Gateway. The merchant may choose between synchronous and asynchronous operation. For details on the different modes of operation, see 3.4.4 Asynchronous communication and 3.2.3 Error handling.

The Mobile GW sends an initAuth or initSign message depending on the operation, to the merchant as shown below.

 

The merchant application needs to perform the following actions:

• Read the request parameters from the request object.
• Create a session object.

 Due to limitations in SIM Toolkit on mobile phones BankID Server has to filter and prepare the "text to sign" before sending it to the mobile phone. The following ASCII input characters are accepted;

[0-9] [a-z] [æ] [ø] [å] [A-Z] [Æ] [Ø] [Å] [CR] [LF] [#] [$] [%-&][(-?] [@] 
[¡] [£] [¤] [¥] [§] [¿] [Ä] [Ç] [É] [Ñ] [Ö] [Ü] [ß] [à] [ä] [è] [é] [ì] [ñ] [ò] [ö] [ù]

To make the text compliant with GSM 03.38 characters outside the accepted ones will be deleted from the "text to sign" before it is sent to the mobile phone.

The theoretical limit for text to be signed in a SMS is 160 characters. Experiences at Telenor show that the recommended length is 120 characters. Two characters are reserved for the telecom operators, so in reality the maximum length of the text to be signed is 118 characters. The merchant name is limited in the RA interface to a maximum of 80 characters which leaves 38 characters to general text and random challenge value. Any characters beyond this limit will be trimmed by BankID Server. Note that the only supported MIME-type is text/plain.

The signed data bytes can be retrieved from the session object.

To complete the sequence the merchant must

• Call the BankID server function InitTransaction, passing the session object as a parameter.
• Store the session object returned by the function call.
• Send the response from InitTransaction to the Mobile GW.

 

The mobile GW contacts the correct MNO and the enduser is requested to enter a PIN code to sign the text shown on the display. 

The resulting client signature is returned to the merchant application in a request object along with, in case of a signing operation, a merchant certificate status instance (OCSP response).

The merchant application then needs to:

• Read the request parameters from the request object.
• Retrieve the stored session object.
• Call the BankID server function VerifyTransactionRequest, passing the sessionObject as a parameter.

The merchant application then needs to continue with the following actions to authenticate the client:

• Merchant application specific business logic to update internal state as needed.
• Merchant application specific business logic updates e.g. associate the end-user with the customer database.

Finally the merchant application must:

• Call the function VerifyTransactionResponse, passing the session object as a parameter.
• Perform business logic updates.
• Return the data from VerifyTransactionResponse back to the BankID Client.

 

In case of a successful sign operation the merchant must show a confirmation dialog to the end-user as shown below. 

For further details regarding authentication, please refer to:

• [ICSRV], 5.4 Authentication process
• [IJSRV], 4.2.1 Authentication process

Error handling

Should an error occur on the Mobile GW, the resulting error handling will depend on whether the merchant has invoked the operation synchronously or asynchronously. In the case of synchronous operations, the invocation of requestMobileAction will be terminated, and an error code will be returned to be handled by the merchant's BankID server implementation.

If, on the other hand, requestMobileAction was invoked asynchronously, the error reporting mechanisms are a little more complex. Errors caught during invocation validation are handled the same way as a synchronous invocation. If an error occurs during the subsequent processing, the Mobile GW will send a handleError operation to the merchant. The encrypted content transmitted to the server component is 'operation=handleError&errCode=<errorCode>'. The handleError operation is handled through the use of the BankID server mechanisms verifyTransactionRequest and verifyTransactionResponse, and the resulting response (which will contain the error code) should be returned to the Mobile GW as a confirmation. The web application may then want to redirect the end-user to another web page displaying relevant information, as the processing of the asynchronous requestMobileAction invocation is terminated.

BankID Server will encrypt the reply to the Mobile GW when processing a handleError request. If decryption fails for any reason, the merchant should reply with an unencrypted error message.

If the Mobile GW is unable to initiate communication with the merchant endpoint URL, merchants using asynchronous operation will not receive error notifications. It is therefore strongly suggested that merchants use synchronous operation until successful operation and communication has been verified.

Should an error occur on the merchant side, the BankID server must return errCode=<errorCode> in its response to the Mobile GW.

An error may occur at any time during Mobile GW to server callback communication. This message will therefore also apply to the previous sequence diagrams. 

Features

This chapter describes the features available to the merchant.

BankID server features

BankID control and filtering 

A merchant application may specify the types of BankIDs that it accepts. A company specific application may only accept Employee certificates and a public government site may only accept Person certificate. This is done using the concept of Policy OIDs. The merchant can achieve this control and filtering by specifying a single or a list of Policy OIDs that are compatible with the application using features in the BankID server.

Note that the certType parameters used in requestMobileAction is configured in BankID server.

For further details please refer to:

• this document, 1.1.1 Mobile parameters and values
• [ICSRV], 4. Configuration of BankID C server
• [IJSRV], 3.1 Configuration of BankID J server

Associating the end-user with the customer database

Each BankID end-user has a unique identifier in the certificates. This identifier is unique within BankID and uniquely identifies a physical person. Each person may however have more than one unique identifier, depending on whether it is a Personal BankID or Employee BankID.

The unique identifier can not be transferred once associated to a person. The unique identifier (UniqueID) can be extracted from the end-user certificate using available BankID server functionality.

Merchants that are authorized to retrieve SSN as additional information from the VA, may do so.

Only the SSN or the UniqueID shall be used to identify the end-user.

For further details please refer to:

• [ICSRV], 6.1.15 BID_GetInfoItem (for retrieving the uniqueID from certificate)5.9 Retrieving additional information from VA (for retrieving SSN from VA)
• [IJSRV], 5.2.12 getCertificateInfo (for retrieving the uniqueID from certificate)4.2.5Retrieve additional information from VA

BankID Client parameters and values

Merchant application

The communication with the client is through java servlets, ASP pages or similar. 

Encoding

The information passed to and from the client are URL encoded A method for converting a string into a MIME type called "x-www-form-urlencoded". key/value pairs separated with the character "&". The URL- encoding and decoding must be performed by the merchant web application, and is not part of the BankID API. The character encoding used is "ISO-8859-1".

The bulk of the data transmitted between the client and the server is encrypted. The parameters appears as encKey, encData and encAuth in packets originating from the client, and encData and encAuth in responses to the client.

The following example shows the information that is sent to and from the client during the initial phase of authentication:

Client sends:

operation=initAuth&encKey=<base64encoded string>&encData=<base64encoded string>&
encAuth=<base64encoded string>(&sid=<sid>)

The response will be:

encData=<base64encoded string>&encAuth=<base64encoded string>

or

errCode=<the error code>

Communication Parameters

The following tables describes the keys that are defined. 
Note that all values must be URLencoded.

Set by merchant per transaction 

Generated by BankID server or client 

Communication between Mobile GW and merchant

The Mobile GW communicates with the merchant application using the HTTPS communication protocol. The Mobile GW functions very similarly to the Banklagret client, and will post information to a defined URL retrieved from the supplied URL parameter.

Mobile parameters and values

The following items are mandatory when using BID_RequestMobileAction/requestMobileAction (from this point onward jointly referred to as RequestMobileAction). The values are configured using Infoitems (C server) or MobileInfo (Java server)

The following are optional, using the default value if not set:

Remaining configuration parameters controlling use of BankID on Mobile are derived from the BankID server configuration (e.g. certificate types allowed).

PushSMS

This BankID server operation can be used for for sending an SMS to the end user after a successful transaction.

HandleError

BankID on Mobile specific callback operation for use when an error is detected at the Merchant GW during asynchronous processing.

Asynchronous communication

The default behaviour when calling RequestMobileAction() is to be synchronous, i.e. it returns after the whole mobile and BankID communication has finished, indicating whether the operation was successful or not. By setting the parameter for synchronous communication to false before calling RequestMobileAction(), the function will be asynchronous.

When operating in asynchronous mode, RequestMobileAction() will return after an initial check in BankID COI, returning a transaction reference and a status code indicating whether the check was successful. If the status code indicates success the mobile gateway will initiate normal BankID communication.

Determining the success of the BankID and mobile communication, which is performed in another thread on the web server, must be done by some form of polling. The RequestMobileStatus() call is not currently implemented on the mobile gateway, so the web application must poll its own system to determine if the mobile BankID process was successful and complete and then proceed with the business logic of the application.

If using asynchronous communication, take care to block users whose RequestMobileAction invocation is already being processed from initiating further simultaneous invocations until the one being processed has finished.