@equinor/fusion-framework-module-msal-node provides secure Azure AD authentication for Node.js applications using Microsoft's MSAL (Microsoft Authentication Library). Perfect for CLI tools, background services, and automated processes that need to authenticate with Microsoft services.

Features

- Multiple Authentication Modes: Choose the right auth flow for your use case
- Secure Token Storage: Encrypted credential storage using platform keychains
- Easy Integration: Simple API that works seamlessly with Fusion Framework
- Token Management: Automatic token refresh and caching
- Cross-Platform: Works on Windows, macOS, and Linux
- Zero Configuration: Sensible defaults with optional customization

Quick Start

``bash
pnpm add @equinor/fusion-framework-module-msal-node
`

`typescript
import { enableAuthModule } from '@equinor/fusion-framework-module-msal-node';
import { ModulesConfigurator } from '@equinor/fusion-framework-module';

const configurator = new ModulesConfigurator();

enableAuthModule(configurator, (builder) => {
builder.setMode('interactive');
builder.setClientId('your-client-id');
builder.setTenantId('your-tenant-id');
});

const framework = await initialize();
const token = await framework.auth.acquireAccessToken({
scopes: ['https://graph.microsoft.com/.default']
});
`

Authentication Modes

Choose the authentication mode that best fits your application's needs:

| Mode | Description | Best For | User Interaction |
|------|-------------|----------|------------------|
| token_only | Uses a pre-provided access token | CI/CD pipelines, serverless functions | None |
| silent | Uses cached credentials for background auth | Background services, scheduled tasks | None |
| interactive | Browser-based login with local server | CLI tools, development, user-facing apps | Required |

$3

- token_only: When you already have a valid access token (e.g., from environment variables, CI/CD secrets)
- silent: When you need background authentication without user interaction (e.g., scheduled jobs, background services)
- interactive: When you need user login (e.g., CLI tools, development environments, user-facing applications)

Secure Token Storage

The module uses @azure/msal-node-extensions for enterprise-grade security:

- 🔒 Platform Keychains: Windows Credential Manager, macOS Keychain, Linux libsecret
- 🔐 Encryption at Rest: Tokens encrypted using platform-specific mechanisms
- 🔄 Automatic Refresh: Seamless token renewal without user intervention
- 🌐 Cross-Platform: Consistent security across Windows, macOS, and Linux

Usage Examples

$3

Perfect for automated processes where you already have a valid token:

`typescript
import { enableAuthModule } from '@equinor/fusion-framework-module-msal-node';
import { ModulesConfigurator } from '@equinor/fusion-framework-module';

const configurator = new ModulesConfigurator();

enableAuthModule(configurator, (builder) => {
builder.setMode('token_only');
builder.setAccessToken(process.env.ACCESS_TOKEN); // From CI/CD secrets
});

const framework = await initialize();
const token = await framework.auth.acquireAccessToken({
scopes: ['https://graph.microsoft.com/.default']
});
`

$3

For background services that need to authenticate without user interaction:

`typescript
import { enableAuthModule } from '@equinor/fusion-framework-module-msal-node';
import { ModulesConfigurator } from '@equinor/fusion-framework-module';

const configurator = new ModulesConfigurator();

enableAuthModule(configurator, (builder) => {
builder.setMode('silent');
builder.setClientId(process.env.AZURE_CLIENT_ID);
builder.setTenantId(process.env.AZURE_TENANT_ID);
});

const framework = await initialize();

// This will use cached credentials or fail if no valid cache exists
try {
const token = await framework.auth.acquireAccessToken({
scopes: ['https://graph.microsoft.com/.default']
});
console.log('Authenticated successfully');
} catch (error) {
console.error('Silent authentication failed:', error.message);
}
`

$3

For CLI tools and development environments that require user login:

`typescript
import { enableAuthModule } from '@equinor/fusion-framework-module-msal-node';
import { ModulesConfigurator } from '@equinor/fusion-framework-module';

const configurator = new ModulesConfigurator();

enableAuthModule(configurator, (builder) => {
builder.setMode('interactive');
builder.setClientId(process.env.AZURE_CLIENT_ID);
builder.setTenantId(process.env.AZURE_TENANT_ID);
builder.setServerPort(3000); // Optional: custom port
builder.setServerOnOpen((url) => {
console.log(🌐 Please open your browser and navigate to: ${url});
});
});

const framework = await initialize();

// This will open a browser for user login
const result = await framework.auth.login({
scopes: ['https://graph.microsoft.com/.default']
});
console.log('Login successful:', result.account?.username);
`

Configuration

$3

| Setting | Description | Required For |
|---------|-------------|--------------|
| clientId | Azure AD application client ID | silent, interactive |
| tenantId | Azure AD tenant ID | silent, interactive |
| accessToken | Pre-obtained access token | token_only |

$3

| Setting | Description | Default | Mode |
|---------|-------------|---------|------|
| serverPort | Local server port for auth callbacks | 3000 | interactive |
| serverOnOpen | Callback when browser opens | undefined | interactive |

$3

`bash


Required for silent/interactive modes

AZURE_CLIENT_ID=your-client-id
AZURE_TENANT_ID=your-tenant-id

Required for token_only mode

ACCESS_TOKEN=your-access-token
`

API Reference

$3

Enables the MSAL Node module in your Fusion Framework application.

Parameters:
- configurator: ModulesConfigurator - The modules configurator instance
- configure: (builder: IAuthConfigurator) => void - Configuration function

$3

The authentication provider interface available at framework.auth:

`typescript
interface IAuthProvider {
// Acquire an access token for the specified scopes
acquireAccessToken(options: {
scopes: string[];
interactive?: boolean
}): Promise;

// Login (interactive mode only)
login(options: { scopes: string[] }): Promise;

// Logout (interactive mode only)
logout(): Promise;
}
`




Troubleshooting

$3

| Issue | Solution |
|-------|----------|
| Invalid client/tenant ID | Verify your Azure AD app registration settings |
| Port already in use | Change the serverPort` or kill the process using the port |
| Silent auth fails | Ensure you've logged in interactively first to cache credentials |
| Token expired | The module handles refresh automatically; check your scopes |
| Credential storage errors | See our credential storage guide |

$3

- 📖 Credential Storage Troubleshooting - Platform-specific setup help
- 🐛 Report Issues - Bug reports and feature requests

Additional Resources

- Microsoft Graph API Documentation
- Azure AD App Registration Guide
- MSAL Node Documentation
- Fusion Framework Documentation