Front-end implementation of the JS Connector consists of 3 steps as described below:

Load JS Connector

Add the following snippet to your front-end application HTML page. This example is for PRE-PROD. Omit "-preprod" from the URL for PROD.

<script async defer src="https://oidc-preprod.bankidapis.no/js-connect/js/connector.bundle.min.js"></script>

This will make the JS Connector API available via a module called BID attached to the global window object: window.BID

Initialise JS Connector with parameters

In your front-end application, listen for the bid-connector-loaded event, and call the initialisation method of the API. Parameters are presented below.

function onBIDLoaded() {
    // Initialise JS Connector with required parameters
	window.BID.doInit({..});
}
 
document.body.addEventListener( 'bid-connector-loaded', onBIDLoaded, false );

Parameters

The most important parameters are:

(required)

(required)

(required)

'query'

''

'untouched'

''

The full parameter list is found in the API Description.

Experimental features

Some additional JS Connector endpoints can be defined to let the Connector perform automatic token exchange and userinfo collection:

''

''

Integration methods

There are several ways to integrate the JS Connector in your application, each with different user experiences and considerations. However, the design is responsive and the functionality remain the same regardless of the integration method.

Protocol flows for authentication

OIDC supports the different protocol flows defined for the Open ID Connect standard, as explained here. 

Authorisation code flow

response_type: 'code'

This is the most secure and recommended method as the client_secret is not leaked into the client application. It is also the default method used with BankID OIDC Connect.

A time limited one-time code, authorisation code, is granted to redirect_uri which in turn can be used to fetch a long living access token. The access token can then be used to fetch user information.

1. code returned as parameter in response to redirect_uri:  https://example.com/callback?code=oMsCeLvIaQm6bTrgtp7
2. Exchange code for access token and ID token by sending a HTTP POST request to the OIDC IDP token endpoint as explained here
3. Retrieve consented user information by sending a HTTP GET request to the OIDC IDP userinfo endpoint as explained here

BankID OIDC Connect automatically handles the client code for the token exchange and provides API for getting user information for the current session via window.????.doGetUserInfo  

Never embed or send the client_secret to the client application.

Implicit flow

response_type: 'token', response_type: 'token id_token' 

This flow returns an access_token and/or an id_token directly in the response to redirect_uri, bypassing the client_secret/code exchange from the Authorisation code flow.

Hybrid flow

response_type: 'code id_token', response_type: 'code token', response_type: 'code token id_token'

Combination of code grant and implicit flow. Authorisation code and tokens can be delivered to redirect_uri.

Example

// Initialise JS Connector with required parameters
window.BID.doInit({
    // Merchant given client ID on the OIDC Provider
	client_id: 'myApplicationID',
	// Merchant callback URL to receive authentication response
	redirect_uri: 'http://myApplication.com/callback',
	// Implementation method, open the session in a new window
	method: 'window',
	// Receive a code in the authentication response to redirect_uri (authorization code flow)
	response_type: 'code',
	// Receive the code in query parameters in the authentication response to redirect_uri
	response_mode: 'query'
});

Start authentication via JS Connector

To start authentication with the OIDC Provider call the window.BID.doConnect() method giving a callback function.

The callback function is provided with the returning accessToken and any error messages if something has gone wrong. For example, by user cancellation.

Example

// Start authetication via JS Connector providing a callback
window.BID.doConnect( function (err, data) {
	if ( err ) {
    	// handle error from the OIDC Provider
		console.error( err );
    }
    else {
        // client is now connected, store ‘accessToken’ if needed
        console.log( data );
    }
});