@myxtra/authentication-green 1.14.4 → 1.14.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +120 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# Xtra authentication
|
|
2
|
+
|
|
3
|
+
Easily authenticate users with Xtra and allow them to navigate to the Xtra toolkit.
|
|
4
|
+
|
|
5
|
+
## Demo
|
|
6
|
+
|
|
7
|
+
## Prerequisites
|
|
8
|
+
|
|
9
|
+
It's important to note that this package is only to be used (and compatible) with any of the
|
|
10
|
+
Business Operation Units (BOU) that reside within Colruyt Group.
|
|
11
|
+
|
|
12
|
+
This package is purely a frontend component and requires a Backend For Frontend (BFF) to work. As
|
|
13
|
+
third-party cookies are no longer a viable option, this BFF will have to be built by the BOU
|
|
14
|
+
integrating the Xtra toolkit.
|
|
15
|
+
|
|
16
|
+
### 1. Request access to Azure B2C
|
|
17
|
+
|
|
18
|
+
### 2. Set up the Backend For Frontend (BFF)
|
|
19
|
+
|
|
20
|
+
As was mentioned in the previous paragraph, the BFF has to be built by the BOU. As such, the
|
|
21
|
+
technologies used to build the BFF are not important. However, as the BFF's primary purpose is to
|
|
22
|
+
authenticate users, it is important that the BFF is able to communicate with Azure B2C. In this
|
|
23
|
+
section, we will explain what API endpoints are required for this to work.
|
|
24
|
+
|
|
25
|
+
> ❗ The authentication component is thus only responsible for **redirecting** the user to the BFF.
|
|
26
|
+
|
|
27
|
+
#### Authentication
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
As depicted in the image above, the authentication flow consists of these steps:
|
|
32
|
+
|
|
33
|
+
1. The user clicks on the login button on the website of the BOU and is redirected to the login
|
|
34
|
+
route of the BFF.
|
|
35
|
+
2. The BFF makes use of the
|
|
36
|
+
[MSAL library](https://learn.microsoft.com/en-us/entra/identity-platform/msal-overview) to
|
|
37
|
+
instantiate a confidential client application and makes use of the client credentials flow to
|
|
38
|
+
redirect the user to the Azure B2C login page.
|
|
39
|
+
3. The user logs in and is redirected to the redirect URI of the BFF. The BFF then uses the
|
|
40
|
+
authorization code to request an access token from Azure B2C. This access token is stored in a
|
|
41
|
+
distributed token cache (e.g. Redis) and a first party, server only session cookie is set in the
|
|
42
|
+
user's browser.
|
|
43
|
+
4. The BFF redirects the user back to the page they were on when they clicked on the login button.
|
|
44
|
+
|
|
45
|
+
#### Proxy
|
|
46
|
+
|
|
47
|
+
In order for the authentication component to fetch the profile of the user and ensure the user has
|
|
48
|
+
accepted the latest terms and conditions. The BFF has to provide a proxy endpoint that will forward
|
|
49
|
+
the requests to the [API Gateway](https://api.myxtra.be) and **adds the authorization header** with
|
|
50
|
+
the access token if it is present.
|
|
51
|
+
|
|
52
|
+
Examples of some endpoints that will be called by components:
|
|
53
|
+
|
|
54
|
+
| BFF URL | API Gateway URL |
|
|
55
|
+
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
|
56
|
+
| https://bff.syst.mijnxtra.be/xtra/newsletter/v1/newsletters | https://api.syst.myxtra.be/newsletter/v1/newsletters |
|
|
57
|
+
| https://bff.syst.mijnxtra.be/xtra/newsletter/v1/newsletters?partnerClientId=123456 | https://api.syst.myxtra.be/newsletter/v1/newsletters?partnerClientId=123456 |
|
|
58
|
+
|
|
59
|
+
## Installation
|
|
60
|
+
|
|
61
|
+
In order to ensure the authentication web componenent is rendered correctly, you can import the
|
|
62
|
+
package in two ways.
|
|
63
|
+
|
|
64
|
+
### CDN
|
|
65
|
+
|
|
66
|
+
```html
|
|
67
|
+
<!doctype html>
|
|
68
|
+
<html>
|
|
69
|
+
<head>
|
|
70
|
+
<script type="module">
|
|
71
|
+
import registerAuthentication from 'https://unpkg.com/@myxtra/authentication-green';
|
|
72
|
+
|
|
73
|
+
await registerAuthentication({ apiUrl: 'http://localhost:3000', environment: 'syst' });
|
|
74
|
+
</script>
|
|
75
|
+
</head>
|
|
76
|
+
<body>
|
|
77
|
+
<header>
|
|
78
|
+
<xtra-authentication></xtra-authentication>
|
|
79
|
+
</header>
|
|
80
|
+
</body>
|
|
81
|
+
</html>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### Package manager
|
|
85
|
+
|
|
86
|
+
First install the package using your preferred package manager.
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
npm install @myxtra/authentication-green
|
|
90
|
+
|
|
91
|
+
yarn add @myxtra/authentication-green
|
|
92
|
+
|
|
93
|
+
pnpm add @myxtra/authentication-green
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Then import the package in your application.
|
|
97
|
+
|
|
98
|
+
```js
|
|
99
|
+
import registerAuthentication from '@myxtra/authentication-green';
|
|
100
|
+
|
|
101
|
+
await registerAuthentication({ apiUrl: 'http://localhost:3000', environment: 'syst' });
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### Configuration
|
|
105
|
+
|
|
106
|
+
The authentication package has the following configuration properties which are passed to the
|
|
107
|
+
`registerAuthentication` function:
|
|
108
|
+
|
|
109
|
+
```ts
|
|
110
|
+
type Config = {
|
|
111
|
+
// The URL of the BFF the authentication component will redirect and do fetch request to
|
|
112
|
+
apiUrl: string;
|
|
113
|
+
// The environment on which the authentication component is running on
|
|
114
|
+
environment: 'dev' | 'test' | 'syst' | 'prod';
|
|
115
|
+
// The redirect url the BFF should redirect to after the user has logged in. Defaults to window.location.href
|
|
116
|
+
redirectUrl?: string;
|
|
117
|
+
// The position of the flyout menu, defaults to 'right'
|
|
118
|
+
position?: 'left' | 'right';
|
|
119
|
+
};
|
|
120
|
+
```
|