@equinor/fusion-framework-module-msal 4.0.8-next.0 → 4.0.9
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/CHANGELOG.md +27 -4
- package/README.md +136 -49
- package/dist/esm/static.js +1 -1
- package/dist/esm/static.js.map +1 -1
- package/dist/esm/version.js +1 -1
- package/dist/esm/version.js.map +1 -1
- package/dist/tsconfig.tsbuildinfo +1 -1
- package/dist/types/static.d.ts +1 -1
- package/dist/types/version.d.ts +1 -1
- package/package.json +4 -4
- package/src/version.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,13 +1,36 @@
|
|
|
1
1
|
# Change Log
|
|
2
2
|
|
|
3
|
-
## 4.0.
|
|
3
|
+
## 4.0.9
|
|
4
4
|
|
|
5
5
|
### Patch Changes
|
|
6
6
|
|
|
7
|
-
- [#
|
|
7
|
+
- [#3343](https://github.com/equinor/fusion-framework/pull/3343) [`68dc22f`](https://github.com/equinor/fusion-framework/commit/68dc22f582bb68fbc94f29ad053122f81c049405) Thanks [@odinr](https://github.com/odinr)! - Enhanced documentation with comprehensive guides and improved developer experience.
|
|
8
8
|
|
|
9
|
-
-
|
|
10
|
-
-
|
|
9
|
+
- **Complete documentation rewrite** with better structure and organization
|
|
10
|
+
- **Added comprehensive API reference** with detailed interface documentation
|
|
11
|
+
- **Enhanced configuration guide** with clear required/optional settings tables
|
|
12
|
+
- **Added migration guide** for v4 breaking changes and module hoisting
|
|
13
|
+
- **Improved troubleshooting section** with common issues and solutions
|
|
14
|
+
- **Added quick start examples** with practical usage patterns
|
|
15
|
+
- **Enhanced module hoisting documentation** explaining shared authentication state
|
|
16
|
+
- **Added package description** for better npm package visibility
|
|
17
|
+
|
|
18
|
+
**Key Improvements:**
|
|
19
|
+
|
|
20
|
+
- Clear separation between required and optional configuration
|
|
21
|
+
- Comprehensive API reference with TypeScript interfaces
|
|
22
|
+
- Migration guidance for v4 breaking changes
|
|
23
|
+
- Better developer onboarding with quick start examples
|
|
24
|
+
- Enhanced troubleshooting with platform-specific solutions
|
|
25
|
+
|
|
26
|
+
## 4.0.8
|
|
27
|
+
|
|
28
|
+
### Patch Changes
|
|
29
|
+
|
|
30
|
+
- [#3075](https://github.com/equinor/fusion-framework/pull/3075) [`8fffbfb`](https://github.com/equinor/fusion-framework/commit/8fffbfb12daa9748bf5290e5084cd4d409aed253) Thanks [@odinr](https://github.com/odinr)! - Upgrade zod dependency to ^3.25.76 in all affected packages.
|
|
31
|
+
|
|
32
|
+
- Updated dependencies [[`8fffbfb`](https://github.com/equinor/fusion-framework/commit/8fffbfb12daa9748bf5290e5084cd4d409aed253), [`8fffbfb`](https://github.com/equinor/fusion-framework/commit/8fffbfb12daa9748bf5290e5084cd4d409aed253)]:
|
|
33
|
+
- @equinor/fusion-framework-module@5.0.0
|
|
11
34
|
|
|
12
35
|
## 4.0.7
|
|
13
36
|
|
package/README.md
CHANGED
|
@@ -1,74 +1,161 @@
|
|
|
1
|
-
## MSAL mod
|
|
2
1
|
|
|
3
|
-
|
|
2
|
+
`@equinor/fusion-framework-module-msal` provides secure Azure AD authentication for browser applications using Microsoft's MSAL (Microsoft Authentication Library). Perfect for web applications, SPAs, and React apps that need to authenticate with Microsoft services.
|
|
4
3
|
|
|
5
|
-
##
|
|
4
|
+
## Features
|
|
6
5
|
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
- **Single Sign-On (SSO)** support for Microsoft Azure AD and Azure AD B2C
|
|
7
|
+
- **Token Management** with automatic refresh and secure caching
|
|
8
|
+
- **Module Hoisting** for shared authentication state across application scopes
|
|
9
|
+
- **Silent Authentication** for seamless user experience
|
|
10
|
+
- **Popup & Redirect Flows** for different authentication scenarios
|
|
11
|
+
- **Zero Configuration** with sensible defaults and optional customization
|
|
9
12
|
|
|
10
|
-
|
|
11
|
-
// enable the module
|
|
12
|
-
import { enableMsal } from '@equinor/fusion-framework-module-msal';
|
|
13
|
+
## Quick Start
|
|
13
14
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
};
|
|
15
|
+
```bash
|
|
16
|
+
pnpm add @equinor/fusion-framework-module-msal
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
19
|
+
```typescript
|
|
20
|
+
import { enableMSAL } from '@equinor/fusion-framework-module-msal';
|
|
21
|
+
import { ModulesConfigurator } from '@equinor/fusion-framework-module';
|
|
22
|
+
|
|
23
|
+
const configurator = new ModulesConfigurator();
|
|
24
|
+
|
|
25
|
+
enableMSAL(configurator, (builder) => {
|
|
26
|
+
builder.setClientConfig({
|
|
27
|
+
tenantId: 'your-tenant-id',
|
|
28
|
+
clientId: 'your-client-id',
|
|
29
|
+
redirectUri: 'https://your-app.com/callback'
|
|
30
|
+
});
|
|
31
|
+
builder.setRequiresAuth(true);
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
const framework = await initialize();
|
|
35
|
+
const token = await framework.auth.acquireAccessToken({
|
|
36
|
+
scopes: ['https://graph.microsoft.com/.default']
|
|
37
|
+
});
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
> [!IMPORTANT]
|
|
41
|
+
> The `@equinor/fusion-framework-app` enables this package by default, so applications using the app package do not need to enable this module manually.
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
## Configuration
|
|
45
|
+
|
|
46
|
+
### Required Settings
|
|
47
|
+
|
|
48
|
+
| Setting | Description | Required |
|
|
49
|
+
|---------|-------------|----------|
|
|
50
|
+
| `clientId` | Azure AD application client ID | ✅ |
|
|
51
|
+
| `tenantId` | Azure AD tenant ID | ✅ |
|
|
52
|
+
| `redirectUri` | Authentication callback URL | Optional |
|
|
22
53
|
|
|
23
|
-
|
|
54
|
+
### Optional Settings
|
|
24
55
|
|
|
25
|
-
|
|
56
|
+
| Setting | Description | Default |
|
|
57
|
+
|---------|-------------|---------|
|
|
58
|
+
| `requiresAuth` | Auto-authenticate on initialization | `false` |
|
|
59
|
+
| `version` | Force specific MSAL version | `Latest` |
|
|
26
60
|
|
|
27
|
-
|
|
28
|
-
tenantId: 'your-tenant',
|
|
29
|
-
clientId: 'your-client'
|
|
30
|
-
callbackUrl: 'your-callback-url'
|
|
31
|
-
};
|
|
61
|
+
### Environment Variables
|
|
32
62
|
|
|
33
|
-
|
|
34
|
-
|
|
63
|
+
```bash
|
|
64
|
+
# Required
|
|
65
|
+
AZURE_CLIENT_ID=your-client-id
|
|
66
|
+
AZURE_TENANT_ID=your-tenant-id
|
|
35
67
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
configurator.setClientConfig(msalConfig);
|
|
40
|
-
}));
|
|
68
|
+
# Optional
|
|
69
|
+
AZURE_REDIRECT_URI=https://your-app.com/callback
|
|
70
|
+
```
|
|
41
71
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
72
|
+
## API Reference
|
|
73
|
+
|
|
74
|
+
### `enableMSAL(configurator, configure)`
|
|
75
|
+
|
|
76
|
+
Enables the MSAL module in your Fusion Framework application.
|
|
77
|
+
|
|
78
|
+
**Parameters:**
|
|
79
|
+
- `configurator`: `ModulesConfigurator` - The modules configurator instance
|
|
80
|
+
- `configure`: `(builder: IAuthConfigurator) => void` - Configuration function
|
|
81
|
+
|
|
82
|
+
### `IAuthProvider`
|
|
83
|
+
|
|
84
|
+
The authentication provider interface available at `framework.auth`:
|
|
85
|
+
|
|
86
|
+
```typescript
|
|
87
|
+
interface IAuthProvider {
|
|
88
|
+
// Current user account information
|
|
89
|
+
readonly defaultAccount: AccountInfo | undefined;
|
|
90
|
+
|
|
91
|
+
// Acquire an access token for the specified scopes
|
|
92
|
+
acquireAccessToken(options: { scopes: string[] }): Promise<string | undefined>;
|
|
93
|
+
|
|
94
|
+
// Acquire full authentication result
|
|
95
|
+
acquireToken(options: { scopes: string[] }): Promise<AuthenticationResult | void>;
|
|
96
|
+
|
|
97
|
+
// Login user
|
|
98
|
+
login(): Promise<void>;
|
|
99
|
+
|
|
100
|
+
// Logout user
|
|
101
|
+
logout(options?: { redirectUri?: string }): Promise<void>;
|
|
102
|
+
|
|
103
|
+
// Handle authentication redirect
|
|
104
|
+
handleRedirect(): Promise<void | null>;
|
|
47
105
|
}
|
|
48
106
|
```
|
|
49
107
|
|
|
50
|
-
### Interoperability with MSAL versions
|
|
51
108
|
|
|
52
|
-
|
|
109
|
+
## Module Hoisting
|
|
53
110
|
|
|
54
|
-
|
|
55
|
-
> this should not be necessary in most cases and only done by understanding the inner workings of the module, but can be done in a transition phase._
|
|
111
|
+
The module implements a hoisting pattern where the authentication provider is created once at the root level and shared across all sub-modules. This ensures consistent authentication state throughout your application while maintaining security and performance.
|
|
56
112
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
113
|
+
> [!IMPORTANT]
|
|
114
|
+
> **Configure the auth module only in the root Fusion Framework instance** - Sub-instances will automatically inherit the authentication configuration from the parent.
|
|
115
|
+
|
|
116
|
+
## Migration Guide
|
|
117
|
+
|
|
118
|
+
### Version 4 Breaking Changes
|
|
119
|
+
|
|
120
|
+
**Module Hoisting**: The module now uses module hoisting, meaning sub-module instances proxy the parent module instance. This creates a shared authentication state across all module instances.
|
|
121
|
+
|
|
122
|
+
**Removed Multi-Client Support**: This version no longer supports multiple MSAL clients (multi-tenant, multi-authority) in the same scoped instance due to how `@azure/msal-browser` uses a shared cache.
|
|
123
|
+
|
|
124
|
+
**Benefits of V4**:
|
|
125
|
+
- Shared authentication state across application scopes
|
|
126
|
+
- Improved performance and memory usage
|
|
127
|
+
- Simplified configuration management
|
|
128
|
+
- Better integration with Fusion Framework architecture
|
|
129
|
+
|
|
130
|
+
#### Migration Steps
|
|
131
|
+
|
|
132
|
+
1. **Update Configuration**: Ensure only the root module configures MSAL
|
|
133
|
+
2. **Remove Duplicate Configurations**: Remove MSAL configuration from child modules
|
|
134
|
+
3. **Update Authentication Logic**: Rely on shared authentication state
|
|
135
|
+
4. **Test Multi-Scope Applications**: Verify authentication works across different application scopes
|
|
136
|
+
|
|
137
|
+
## Troubleshooting
|
|
138
|
+
|
|
139
|
+
### Common Issues
|
|
140
|
+
|
|
141
|
+
| Issue | Solution |
|
|
142
|
+
|-------|----------|
|
|
143
|
+
| **Authentication Loop** | Ensure redirect URIs match your application's routing |
|
|
144
|
+
| **Token Acquisition Fails** | Check that required scopes are properly configured |
|
|
145
|
+
| **Module Not Found** | Ensure the module is properly configured and framework is initialized |
|
|
146
|
+
| **Multiple MSAL Instances** | Remove duplicate configurations from child modules |
|
|
147
|
+
|
|
148
|
+
### Getting Help
|
|
64
149
|
|
|
65
|
-
|
|
150
|
+
- 📖 [MSAL Cookbook](https://github.com/equinor/fusion-framework/tree/main/cookbooks/app-react-msal) - Complete working examples
|
|
151
|
+
- 🐛 [Report Issues](https://github.com/equinor/fusion/issues) - Bug reports and feature requests
|
|
66
152
|
|
|
67
|
-
|
|
153
|
+
## Additional Resources
|
|
68
154
|
|
|
69
|
-
|
|
155
|
+
- [Microsoft Graph API Documentation](https://docs.microsoft.com/en-us/graph/)
|
|
156
|
+
- [Azure AD App Registration Guide](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
|
|
157
|
+
- [MSAL Browser Documentation](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-browser)
|
|
158
|
+
- [Fusion Framework Documentation](https://github.com/equinor/fusion-framework)
|
|
70
159
|
|
|
71
|
-
This is a __breaking change__ since this module used to support multiple MSAL clients _(multi tenant, multi authority)_ in the same scoped instance. This is no longer supported, due to the way `@azure/msal-browser` uses a shared cache.
|
|
72
160
|
|
|
73
|
-
This version still uses `@azure/msal-browser@^2`, but enables
|
|
74
161
|
|
package/dist/esm/static.js
CHANGED
|
@@ -3,6 +3,6 @@ export const ModuleName = 'msal';
|
|
|
3
3
|
export var MsalModuleVersion;
|
|
4
4
|
(function (MsalModuleVersion) {
|
|
5
5
|
MsalModuleVersion["V2"] = "v2";
|
|
6
|
-
MsalModuleVersion["Latest"] = "4.0.
|
|
6
|
+
MsalModuleVersion["Latest"] = "4.0.9";
|
|
7
7
|
})(MsalModuleVersion || (MsalModuleVersion = {}));
|
|
8
8
|
//# sourceMappingURL=static.js.map
|
package/dist/esm/static.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"static.js","sourceRoot":"","sources":["../../src/static.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,CAAC,MAAM,UAAU,GAAG,MAAe,CAAC;AAE1C,MAAM,CAAN,IAAY,iBAGX;AAHD,WAAY,iBAAiB;IAC3B,8BAAS,CAAA;IACT,
|
|
1
|
+
{"version":3,"file":"static.js","sourceRoot":"","sources":["../../src/static.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,CAAC,MAAM,UAAU,GAAG,MAAe,CAAC;AAE1C,MAAM,CAAN,IAAY,iBAGX;AAHD,WAAY,iBAAiB;IAC3B,8BAAS,CAAA;IACT,qCAAgB,CAAA;AAClB,CAAC,EAHW,iBAAiB,KAAjB,iBAAiB,QAG5B"}
|
package/dist/esm/version.js
CHANGED
package/dist/esm/version.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,MAAM,CAAC,MAAM,OAAO,GAAG,
|
|
1
|
+
{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}
|