The JS Connector for xID is hereafter referred to as xID Connect. It is a Javascript helper library that offers simple integration of the xID service for OIDC Clients. xID Connect supports several combinations of integration methods and message flows, each with different user experiences and considerations. The chosen integration method may cause a window, redirect, iframe or inline dialog to appear showing any dialogs relevant for the xID session. Depending on the chosen flow, HTTP endpoints at the back-end of the OIDC Client must be implemented to perform appropriate Token and Userinfo (TINFO) requests to retrieve data about the authenticated user.

The documentation of xID Connect is divided in the following sections. See also full source code examles on GitHub for the use of xID Connect.

Front-end implementation

1. Load xID Connect

Add the following HTML snippet to your OIDC Client front-end :

<script async defer src="https://bankidapis.no/js/bid-xid_connect.bundle.min.js"></script>

This will make available an object XID attached to the global window object: window.XID

2. Initialise xID Connect with parameters

In your OIDC Client front-end, listen for the xid-loaded event, and call the initialisation API. Parameters are discussed below.

function onXIDLoaded() {
    // Initialise xID with required parameters
	window.XID.doInit ({
    	// Merchant given client ID on the xID service
		client_id: 'myApplication',
		// The resource scopes merchant want to gain access to for the user
		scope: 'openid address',
    	// Implementation method, open the session in a new window
		method: 'window',
    	// Merchant backend endpoints for performing token/userinfo calls.
		token_endpoint: 'https://example.com/oauth2/token',
		userinfo_endpoint: 'https://example.com/oauth2/userinfo',
	});
}
 
document.body.addEventListener( 'xid-loaded', onXIDLoaded, false );

Parameters

The most important parameters are as follows, some of which are identical to parameters to the Authorize endpoint of the REST API. 

Depending on response_type the following parameters may be important:

'/oauth/token'

'/oauth/userinfo'

Other relevant, but optional, parameters include the following, some of which are identical to parameters to the Authorize endpoint of the REST API. 

(xIDs internal callback handler)

'query'

false

''

The full list of parameter list is found in the JS API Reference.

Integration methods

There are several ways to integrate xID in your application, each with different user experiences and considerations. However, the xID functionality and appearance remain the same regardless of the integration method.

Message flows (response_type)

xID Connect supports each of thefmessage flows supported by the OIDC Provider as governed by the response_type parameter 

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

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

1. code is returned as parameter in response to redirect_uri:  https://example.com/callback?code=oMsCeLvIaQm6bTrgtp7
2. The code is exchanged for Access Token and ID Token by sending a HTTP POST request to the xID IDP token endpoint as explained here
3. Consented user information is retrieved by sending a HTTP GET request to the xID IDP userinfo endpoint as explained here

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

Never embed or send the client_secret to the client application.

Implicit flow

response_type: 'token'

This flow returns an Access Token directly in the response to redirect_uri, bypassing the client_secret/code exchange from the Authorisation code flow, allowing the request userinfo directly. Meant for OIDC Clients without backend.

Hybrid flow

response_type: 'hybrid'

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

3. Start xID login

To start the xID login process call the window.XID.doConnect() function 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.

// Start xID login providing a callback
window.XID.doConnect( function (err, accessToken) {
	if ( err ) {
    	// handle xID connect error
    }
    else {
        // client is now connected, store ‘accessToken’ if needed
        doGetXidUserInfo();
    }
});

4. Get user info

A common callback action is to fetch user information as the access token stored in the current xID Connect session.

xID Connect provides the API function window.XID.doGetUserInfo() for this task.

function doGetUserInfo() {
	window.XID.doGetUserInfo( function (err, user) {
		if ( err ){
			// handle error
		}
		else {
			// handle user
		}
	});
}

Back-end implementation

When using authorisation code flow or hybrid flow with xID Connect the library expects the OIDC Client to implement  back-end functions to handle OAUTH requests to receive tokens and user info from xID IDP. The OIDC Client back-end  is needed in order to safely store the required parameter client_secret away from front-end components of the OIDC Client. xID Connect will by default automatically call these HTTP endpoints in this mode.

Token endpoint

When a code is received, xID Connect will call the token endpoint to receive an access_token

xID Connect will store this token in the current client session. For increased security, you may avoid sending this token back to xID Connect request.

{

    access_token: "654fe6f11ad61ceb1697d643b5fc59", 

    token_type: "Bearer", 

    expires_in: 3600, 

    scope: "openid phone address", 

    id_token: "...."  // JWT

}

For documentation on the corresponding response to xID IDP see Token

Userinfo endpoint

Using the access token (which also could be stored on the server) to access user information xID IDP.

{
 "sub": "9578-6000-4-127698",
 "iss": "https://preprod.bankidapis.no",
 "iat": 1485866449,
 "exp": 1485870048,
 "preferred_username": "Testesen, Test",
 "name": "Testesen, Test",
 "given_name": "Test",
 "family_name": "Testesen",
 "birthdate": "1980-03-09",
 "nnin": "09038000010"
}

For documentation on the corresponding response to xID IDP see Userinfo (TINFO)

'openid'

'window'

'code'

'query'

'/oauth/token'

'/oauth/userinfo'

(default OAUTH endpoint for the xID service)

'XID'

false

false

false

''

'untouched'

'authorization_code'

{}

null 

null 

false

null

null

null

'code'