Easily authenticate users with Xtra and allow them to navigate to the Xtra toolkit.
It's important to note that this package is only to be used (and compatible) with any of the Business Operation Units (BOU) that reside within Colruyt Group.
This package is purely a frontend component and requires a Backend For Frontend (BFF) to work. As third-party cookies are no longer a viable option, this BFF will have to be built by the BOU integrating the Xtra toolkit.
As was mentioned in the previous paragraph, the BFF has to be built by the BOU. As such, the technologies used to build the BFF are not important. However, as the BFF's primary purpose is to authenticate users, it is important that the BFF is able to communicate with Azure B2C. In this section, we will explain what API endpoints are required for this to work.
❗ The authentication component is thus only responsible for redirecting the user to the BFF.
As depicted in the image above, the authentication flow consists of these steps:
- The user clicks on the login button on the website of the BOU and is redirected to the login route of the BFF.
- The BFF makes use of the MSAL library to instantiate a confidential client application and makes use of the client credentials flow to redirect the user to the Azure B2C login page.
- The user logs in and is redirected to the redirect URI of the BFF. The BFF then uses the authorization code to request an access token from Azure B2C. This access token is stored in a distributed token cache (e.g. Redis) and a first party, server only session cookie is set in the user's browser.
- The BFF redirects the user back to the page they were on when they clicked on the login button.
In order for the authentication component to fetch the profile of the user and ensure the user has accepted the latest terms and conditions. The BFF has to provide a proxy endpoint that will forward the requests to the API Gateway and adds the authorization header with the access token if it is present.
Examples of some endpoints that will be called by components:
In order to ensure the authentication web component is rendered correctly, you can import the package in two ways.
<!doctype html>
<html>
<head>
<script type="module">
import registerAuthentication from 'https://unpkg.com/@myxtra/authentication-green';
await registerAuthentication({ apiUrl: 'http://localhost:3000', environment: 'syst' });
</script>
</head>
<body>
<header>
<xtra-authentication flyoutPlacement="bottom-end"></xtra-authentication>
</header>
</body>
</html>First install the package using your preferred package manager.
npm install @myxtra/authentication-green
yarn add @myxtra/authentication-green
pnpm add @myxtra/authentication-greenThen import the package in your application.
import registerAuthentication from '@myxtra/authentication-green';
await registerAuthentication({ apiUrl: 'http://localhost:3000', environment: 'syst' });The authentication package has the following configuration properties which are passed to the
registerAuthentication function:
type Config = {
// The environment on which the authentication component is running on
environment: 'dev' | 'test' | 'syst' | 'prod';
// The URL of the BFF the authentication component will do fetch requests to
apiUrl: string;
// The URL of the BFF the authentication component will perform login, logout and redirect calls to
// ! Only necessary when different then apiUrl, because it defaults to the provided apiUrl.
authUrl?: string;
// The redirect url the BFF should redirect to after the user has logged in. Defaults to window.location.href
redirectUrl?: string;
// The ID of the commerce/BOU for which the component will show the icon when the Terms & Condition dialog is shown.
// Defaults to 'xtra'
commerceId?:
| 'bioplanet'
| 'collectgo'
| 'collibri'
| 'colruyt'
| 'colruytacademy'
| 'colruytgroup'
| 'dats24'
| 'dreambaby'
| 'dreamland'
| 'okay'
| 'spar'
| 'xtra';
// Add links to custom pages on the menu (only visible to authenticated users)
bouMenuItems?: Array<{
label: string; // Text to display for the link
url: string; // URL of the custom page
icon: string; // Icon to show in front of the text (see disclaimer below)
}>;
country?: 'BE' | 'FR'; // Show options from specific country. Defaults to 'BE'
};❗ You can find a list of available BOU menu item icons here.
To change the direction in which the menu of the authentication component will open, you can pass a flyoutPlacement value to the component.
<xtra-authentication flyoutPlacement="bottom-start></xtra-authentication>
Possible values are:
- top-start
- top-end
- bottom-start
- bottom-end (default)
The authentication component will emit events and add properties to the window object. For backwards compatibility with the orange toolkit, the window properties are the same.
Everything is available under the window.xtra object. If the user is authenticated, the component
will also add the following properties to the window object:
type XTRA = {
user: {
firstName: () => string;
lastName: () => string;
dob: () => number;
mob: () => number;
yob: () => number;
gender: () => 'M' | 'F';
phone: () => string;
streetName: () => string;
houseNr: () => string;
box: () => string;
zip: () => string;
city: () => string;
country: () => string;
email: () => string;
cbh: () => string;
state: () => 'Authenticated';
};
};The authenticated event is sent through window.postMessage, below you can find an example of how to listen for the event:
type XtraAuthenticationMessageEventData = {
source: 'xtra-authentication';
isAuthenticated?: boolean;
address?: Address;
};
const onMessage = (message: MessageEvent<XtraAuthenticationMessageEventData>) => {
// Ensure the event wasn't sent from another domain
if (event.origin !== new URL(window.location.href).origin) {
return;
}
// Ensure the event wasn't sent from another source
if (!event.data.source === 'xtra-authenticaiton') {
return;
}
if (!event.data.isAuthenticated) {
// TO DO: add logic in case the user is not authenticated
return;
}
// TO DO: add logic when the user is authenticated (window.xtra is set here)
};
window.addEventListener('message', onMessage);