See the following sections for further information on front-end implementation of the JS Connector:

Load JS Connector

Load the JS Connector to create the global OIDC object. See a separate page for baseURLs for the JS Connector (connector-baseurl) in different environments

<script src="<connector-baseurl>/connector.bundle.min.js"></script>

You can also load the JS Connector asynchronously to avoid blocking page load, see the examples page on how to load the client library.

Initialise JS Connector with parameters

You need to provide an object containing key-value pairs of configuration data. See API Reference for doInit parameters.

<html>
 <head>
   <script src="<connector-baseurl>/connector.bundle.min.js"></script>
   <script>
    function init() {
        OIDC.doInit({
            // URL to OIDC service
            oauth_url: '<oidc-baseurl>/protocol/openid-connect/auth',
            // Merchant given client ID on the OIDC service
            // TODO: Replace this with your own!
            client_id: 'your_client_id',
            // Your callback URL that will receive the Authorization Grant response
            // TODO: Replace this with your own!
            redirect_uri: 'https://yourdomain.com/oidc/callback',
        });
    };
    init();
  
   </script>
  </head>
  <body>
  </body>
</html>

Start authentication via JS Connector

To start authentication call the window.OIDC.doConnect method. Typically, you do this when the user clicks a button, a link or even on loading of the page.

You need to provide parameters as an object containing key-value pairs. See API Reference for doConnect parameters.

You can provide a callback method that will be executed if you use method inline or window and follow this example on how to setup your redirect_uri callback page.

Example calling doConnect and logging accessToken

OIDC.doConnect( {
	config: {
		login_hint: '',
		scope: 'openid profile'
    },
	callback: function (err, data) {
		if ( err ) {
			console.error( err );
  		}
    	else {
       		console.log( data );
    	}
	}
} );

You need to make sure that the JS Connector has been initialised with doInit before calling doConnect. PS: doInit can be called several times.

Additional considerations

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 DOM element ID can be provided to OIDC.doConnect() to host an iframe which opens the OIDC session inline in your application.

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 (click), otherwise pop-up blockers might block the window.

redirect

The default way is for doConnect () to redirect the user away from your application to a separate web page for the entire OIDC login session before returning to the given redirect_uri.

Protocol flows for authentication

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

Implicit/hybrid mode may not be activated by default for your client_id.

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

Example parameters for a merchant application

OIDC.doInit({
    // URL to OIDC service
    oauth_url: '<oidc-baseurl>/protocol/openid-connect/auth',
    // Merchant given client ID on the OIDC service
    client_id: 'your_client_id',
    // Merchant callback URL to receive authentication response
    redirect_uri: 'https://yourdomain.com/oidc/callback',
    // Activate implicit flow mode by setting response type to id_token token
    response_type: 'id_token token',
    // Set response mode to form_post
    response_mode: 'form_post'
});

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.

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

Page tree

Front-end implementation