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({
            // 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.

Example calling doConnect
OIDC.doConnect( {
	config: {
		login_hint: '',
		scope: 'openid profile'
    },
} );

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 with additional parameters
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.

MethodDescription
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 (short-lived) authorisation code, is granted to redirect_uri which in turn can be used to fetch an ID Token and Access Token. The access token can in turn be used to access various Value Added services, e.g. the Userinfo service.

  1. code returned as parameter in response to redirect_uri like this example: https://example.com/callback?code=oMsCeLvIaQm6bTrgtp7
  2. Exchange code for access token and ID token by sending a HTTP POST request to the Token endpoint
  3. Access any Value Added Service, e.g. by sending a HTTP GET request to the TINFO Userinfo endpoint

Note that BankID OIDC Connect does not handle the client code for step 2 and 3 above. Moreover, 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 id_token and optinally an access_token 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({
    // 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 id_token can be delivered to redirect_uri.

  • No labels