BankID (NO)

• ​Enable BankID in your services​
• Handling of SSN​
• User experience​
• Document types and sizes​
• BankID PAdES
• ​BankID multi-document signing​
• Authentication-based signing

​Enable BankID in your services

To get you started with BankID signing through E-Signing, Nets will need a merchant certificate and some configuration ​​setting information from you. The configuration settings are supplied in the setup dialogue with support.

More information about BankID:

• ​Ne​ts site​
• BankID Norge​​​

Merchant certificate​​​

​​Test ​​users

​​Test us​​ers are available here​.​​​​​​

To get notified about BankID issues in BankID preproduction environment, subscribe to updates at this page:

• https://bankidpreprod.statuspage.io/

Handling ​of SSN

The social security number (SSN) is included in the signed document SDO or native PAdES if the SSN was defined in the SignerID element in the sign order. The Sign​erID needs to be added when inserting the sign order or by using the ModifySigner call. If this has been included in the sign order, a validation request (VA) with SSN lookup will be performed towards BankID to verify that the defined SignerID matches the person trying to sign.

The SSN will also be included if the IncludeSSN element has been set to true in the sign order. The validation request towards BankID will this time also include a SSN lookup.

BankID will return the SSN as a part of the OCSP response and the OCSP will be added to the SDO or PAdES.

Read more about SignerID and IncludeSSN.

For SDOs:

If the SignerID wasn't set in the sign order, a GetSDODetails call with the ReturnSSN element can be used to retrieve the signer's SSN. A VA request to BankID will be performed if the SSN is not part of SDO.

Note: If you are not allowed to handle SSN or you will limit the usage of SSN, each BankID user has a unique ID called PID (personal ID). This is included in the BankID user certificate.

How to find the SSN?

GetSignature

The SSN of a signer can be fetched from E-Signing using the GetSignature call. This requires that the SignerID was set in the sign order. The SSN is returned in the SignerID / IDValue element of the response.

GetSDODetails

Use the GetSDODetails function​ to deduct the content of the SDO and return the SSN. Set the ReturnSSN element in the request to true, and the SSN will be deducted from the SDO or if missing, do a request to BankID requesting the SSN. Note: This is a VA-request with SSN lookup and it has a cost. Refer to the "BankID uthenting av fødselsnummer" price element for your BankID certificate.​

​User ​experience

BankID client 

Step 1 (read document):

Step 2 (optional - see below): 

​

Step 3 (enter OTP): 

Step 4 (enter password):

Step ​2  - how to​​​ skip the User ID page

​​​The step to enter "User ID" (social security number/"fødselsnummer") will be dropped if the signer's ID has been set in the ​​SignerID element when defining the AcceptedPKIs / BankID​ element.​​​ This page will also be dropped if the presetid parameter is appended to the SignURL.

Note: There is one difference in the usage of SignerID element vs the presetid parameter. When setting the SSN in the SignerID element, the signature is after signing validated against the SSN in the SignerID, and the signing is dismissed if there is a mismatch. There is no such validation when using the presetid parameter.

IFRAME siz​​es

It is adviced to test all document types used for signing for responsiveness with different mobile devices. The recommended and minimum IFRAME ​sizes from BankID are:

• ​​Large screen (Desktop/tablet): 396px (w) by 280px (h) (recommended) / 370px (w) by 204px (h) (minimum)
• Small screen (Smartphone) (only minimum sizes): 320px (w) by 350px (h) (portrait) / 480px (w) by 200px (h) (landscape)

Note: Customers using the signing deadline and/or signers table in E-Signing may need to use a slightly higher IFRAME size than the recommended sizes. ​​

Usage of framemode and docdisplaymode

​When using the framemode and the docdisplaymode parameters for BankID, be aware of the following:

• The combination framemode=window and docdisplay-mode=window is not recommended from BankID due to confusing user experience.

• The combination framemode=redirect and docdisplaymode is also not recommended while being redirected may lead to confusing user experience. 

• Framemode=window: Does not work with Internet Explorer or with WebViews (applies to iOS, Android and Win8) and it may be in conflict with pop-up blockers. Be aware that if the framemode=window is closed, the user may be on an empty window. This must be handled by the customer site.

• Framemode=redirect: Internet Explorer does not work when IE’s Trusted sites security levels are set to High and when set to Low IE displays a question to the user whether he wants to accept the redirect before the redirect takes place. The web client is also not reloaded when the language are changed.

• Docdisplaymode=window: Does not work from WebViews (applies to iOS, Android and Win8) and the parameter may be in conflict with pop-up blockers.

The following document formats are supported using BankID:

• ​PDF
• Text
• XML

PDF document

It is recommended from BankID to use PDF/A-2b format when creating the PDF documents. Also, to provide proper support for Univ​ersal Accessability, the document should conform to PDF/UA specification in addition to PDF/A-2b. 

BankID 2.1: Note that there are additional requirements for PDF documents when using BankID 2.1. In particular, XFA is not allowed and may cause signing to fail. We recommend that you test using a sample document in the customer test environment in order to validate your documents.​ 

See BankID recommendation for PDF documents.​ 

XML document​

BankID (NO) mandates that if an end user signs XML data then an XSL must be provided as well. The XSL is used to transform the XML to presentable HTML. So the customer must provide two documents when they want an XML-document to be signed.​

<BankIDXML>
	<XML>ANSGKFLSDSF==</XML>
	<XSL>ANSGKFLSDSF==</XSL>
</BankIDXML>

​​The BankIDXML structure is the document that the end user actually signs. When E-Signing sends this BankIDXML structure to the BankID client, it recognizes this structure and performs an XML transformation. The result of the XML transformation is a HTML which again is presented to the end user. The XML and XSL document bytes provided by the customer must be in ISO-8859-1. So when providing the XML and XSL bytes, get the ISO-8859-1 (ISO-LATIN-1) bytes. The ISO-8859-1 bytes must be Base64-encoded.

BankID PAdES

BankID offers PAdES as an output format when signing PDF documents and this is supported in the E-Signing service. The document may be signed by several signers. Each signature will be applied directly to the PDF document and it is visualised with a BankID seal including the signers name and the signature date. Here is how a document with two signatures look like:

As each signer's signature time is collected from the signer's computer time, Nets applies a timestamp to the document after all signers have signed the document. In the example below, you can see the signature details of two signers and a timestamp signature at the end.

Signatures at a PAdES document must be applied in sequence, and a two signers can't sign the document at the exact same time. The first signer will sign the original PDF document, while the second signer will sign the PDF document including the first signer's signature. The third signer will sign the PDF document including both the first and second signers' signatures and so on. If you inspect the signatures in for example Adobe Acrobat, you will see that the version of the document for the first signer is without any signatures, while the version for the second signer will include the first signer's signature.

Note: It will not be possible to get a SDO when BankID PAdES is used. In addition, the last page that is added when generating a PAdES from a SDO will not be added to the signed document.

Implementation

To use the functionality, the element OutputFormat in the sign order must be set to PAdES. This element is set as part of the ExecutionDetails. Below is an example of the ExecutionDetails element with two signers.

<ExecutionDetails>
	<OrderDeadline>2021-04-12T19:55:14+00:00</OrderDeadline>        
	<GenerateOneTimeURLs>false</GenerateOneTimeURLs>
	<Steps>
		<Step>
			<StepNumber>1</StepNumber>
			<SigningProcess>
				<LocalDocumentReference>doc1</LocalDocumentReference>
				<LocalSignerReference>user1</LocalSignerReference>
			</SigningProcess>
			<SigningProcess>
				<LocalDocumentReference>doc1</LocalDocumentReference>
				<LocalSignerReference>user2</LocalSignerReference>
			</SigningProcess>
		</Step>
	</Steps>
	<OutputFormat>PAdES</OutputFormat>
</ExecutionDetails>

In the example above, it is defined that the two signers may sign at the same time. However, it is not possible for two signers to sign at the same time. The signURL for the user1 and user2 will be ready at the same time. If both signers try to access the document simultaneous, the second signer will be shown an error message and asked to try again in a short while.

The PAdES may be retrieved when all signers have signed using the GetPAdES message.

​​Multi-docume​​nt signing​

The multi-document signing functionality in the BankID 2.1 client will give signers the possibility to sign multiple documents in the same BankID session. The signer will have to enter the OTP code only once per session while the password must be submitted for each document as it is today. 

​​To utilize the BankID 2.1 multi-document signing functionality the customers need to be in line with the following:

• ​All documents to be signed by one signer in one session must be in the same Step​ in the sign order. 
• If the your E-Signing configuration is set to BankID 2.1 (and the clientversion is not 2.0) or if the clientversion parameter is set to 2.1, the default will be to show all active sign processes for a signer in the BankID 2.1 multi-document view. This functionality can be overwritten by appending the multisign parameter set to false to the sign URL. Read more about the different sign URL parameters. 
• The document name shown in the list of documents in the client will be fetched from the Title​ element in the sign order. Note: This value will also be part of the SDO as the MerchantDescription. This is different from BankID 2.0 and BankID 2.1 with only one document where the Description​ element is used.

• A new notification message has been added to handle notifications including sign URLs more gracefully. This is the OnStepReady notification for end users. This notification have been added so that customers using the BankID 2.1 multi-document signing functionality will only receive one notification with one sign URL. Example: If a step includes three documents ready for signing by one signer the usage of OnSignProcessReady​ will result in three notifications with three sign URLs, one for each documents. If the OnStepReady notification is used instead, only one notification is distributed with one sign url pointing to all documents. Read more about notification here. Note: The sign URL in any of the OnSignProcessReady notifications will also point to all documents. The customer can choose to use the sign url in one of the notifications and ignored the rest. 

Some recommendation when starting to use BankID 2.1 multi-document:

• ​It is not recommended to set the TerminateOrderOnSignerRejection element in Steps / Step / SigningProcesses​ to false. BankID do not know the status of E-Signing signing processes and the user will be forced to sign all documents to complete a sign order.
• If using identification before signing​ (RequiresAuthentication​), this should either be enabled for all documents or disabled for all. As each of the sign URLs to all of the sign processes in one step can be used to access all documents in that step, the usages of identification before signing will vary dependent on the sign URL used, If a sign URL belonging to a document where identification before signing is enabled, the user will be prompted to identify himself. However, if accessing one without this setting enabled, the user will not be asked to identify himself. The user will in such cases be able to read all documents without user identification.​

Authentication-based signing

The E-Signing service offers the possibility to sign a document based on an authentication. To create a sign order with authentication-based signing, please have a look at the authentication-based signing page.

The BankID specific values are listed in the table below: