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.

Example loading the Connect library

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

Example of bid-connect-loaded handler

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:

Parameter	Description	Default
client_id	A string specifying the client ID given when registering to the OIDC central service.	(required)
redirect_uri	Absolute URL to the HTTP(S) endpoint receiving the authentication response from OIDC. Read more about how the Connector can help with window/inline management.	(required)
oauth_url	Absolute URL to the OIDC OAUTH endpoint. Ex. https://oidc-preprod.bankidapis.no/oauth	(required)
scope	A string of resource types (dataset) belonging to the user to request access to. Each scope / resource type must be separated by space.	`'openid'`
method	Specify the desired frame method, as explained here. How will the login dialogs be presented to the user?	`'redirect'`
response_type	The chosen authentication response type, explained here. Ex. `'code'` or `'token'`	`'code'`
response_mode	Set the format used when returning parameters from the Authorization Endpoint via `redirect_uri`	'query'
login_hint	Set user info such as NNIN or phone number / birthdate if required for step-up to the BankID IDP .	''
state	Increase security towards cross-site request forgery by verifying this value in the requests and responses	'untouched'
nonce	Provide a nonce value for securing the integrity of the `id_token`	''

The full parameter list is found in the API Description.

For increased security in a production environment, it is highly encouraged to use nonce and state parameters when interacting with the OIDC service.

Experimental features

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

Parameter	Description	Default
token_endpoint	Absolute URL to HTTP(S) endpoint on merchant server-side to retrieve access/ID token in exchange for authorization code (if using `code` response_type).	''
userinfo_endpoint	Absolute URL to HTTP(S) endpoint on merchant server-side to retrieve user information using access token.	''

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.

Method Description

inline

A popular implementation choice of BankID is inline (iframe). A DOM element ID can be provided to BID.doConnect() to host an iframe which opens the OIDC session inline in your application.

There is also a special integration which will display a dialog modal overlaying your application. This method is useful when triggering BankID OIDC Connect upon loading the application to avoid pop-up blockers.

window A common implementation choice is window. When BankID OIDC Connect is triggered it will open the OIDC session in a new window (pop-up). Note that this method should only be triggered when the user does an action, as otherwise pop-up blockers might block the window.

redirect

The default way is for BankID OIDC Connect to redirect the user away from your application to a separate web page for the entire OIDC login session before returning to a given callback URL.

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.

code returned as parameter in response to redirect_uri: https://example.com/callback?code=oMsCeLvIaQm6bTrgtp7
Exchange code for access token and ID token by sending a HTTP POST request to the OIDC IDP token endpoint as explained here
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.

If you use the implicit flow, there may be no need for any server side implementation.

Example

Example parameters for a merchant application

// 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

Example calling doConnect and logging accessToken

// 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 );
    }
});