Registry / auth-security / node-sp-auth-config

node-sp-auth-config

JSON →
library3.0.5jsnpmunverified

node-sp-auth-config is a utility package designed to simplify the creation and management of authentication configuration files for the node-sp-auth library, which handles unattended HTTP authentication to SharePoint from Node.js applications. It provides a wizard-like interactive CLI experience (`sp-auth`) and a programmatic API for building authentication options. The library supports a wide range of SharePoint versions, including SharePoint Online, 2019, 2016, 2013, and 2010, along with various authentication methods such as user credentials (SAML/ADFS, NTLM), Add-In Only permissions, and Form-Based Authentication. By default, it encrypts sensitive data like passwords using a machine-bound hash. The current stable version is 3.0.5 and it regularly releases updates in conjunction with its core dependency, node-sp-auth. Its primary differentiator is streamlining the often complex setup of SharePoint authentication credentials into a guided, persistent configuration process.

npm install node-sp-auth-config
INSTALL
IMPORT
SIG · NODE-SP-AUTH-CONFI
N
node-sp-auth-config
auth-securityjavascriptv3.0.5
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

AuthConfig
✓ import { AuthConfig } from 'node-sp-auth-config';
✗ import AuthConfig from 'node-sp-auth-config';
AuthConfig is a named export for ESM and TypeScript environments. Attempting a default import will result in an undefined value.
AuthConfig
✓ const { AuthConfig } = require('node-sp-auth-config');
✗ const AuthConfig = require('node-sp-auth-config');
For CommonJS modules, AuthConfig must be destructured from the module export, as it's a named export, not the default.
sp-auth CLI
✓ npx sp-auth init --path ./config/my.json
✗ node sp-auth init
The CLI tool `sp-auth` is executable directly via `npx` (if locally installed) or globally if installed with `npm install -g node-sp-auth-config`.

Demonstrates how to programmatically initialize `node-sp-auth-config` to retrieve SharePoint authentication options. It shows a non-interactive setup using pre-defined credentials, suitable for CI/CD environments, and how the resulting `authOptions` can be used with `node-sp-auth`.

import { AuthConfig } from 'node-sp-auth-config'; import * as path from 'path'; import * as fs from 'fs'; // This quickstart demonstrates how to programmatically use node-sp-auth-config // to generate authentication options in a non-interactive, headless mode. // In a real scenario, the environment variables would hold your actual credentials. // The generated configuration can then be passed to the 'node-sp-auth' library. async function demonstrateAuthConfig() { const configFileName = 'demonstration.config.json'; const configFilePath = path.join(__dirname, configFileName); console.log(`Attempting to get SharePoint auth context in headless mode.`); console.log(`Config will be saved (or updated) at: ${configFilePath}`); try { const authConfig = new AuthConfig({ configPath: configFilePath, encryptPassword: true, saveConfigOnDisk: true, headlessMode: true, // Prevents interactive prompts, crucial for CI/CD or automated scripts authOptions: { // Provide example authOptions for headless mode siteUrl: process.env.SP_SITE_URL ?? 'https://yourtenant.sharepoint.com/sites/dev', strategy: 'UserCredentials', username: process.env.SP_USERNAME ?? 'your.user@yourtenant.onmicrosoft.com', password: process.env.SP_PASSWORD ?? 'YourVerySecretPassword123!', } }); const context = await authConfig.getContext(); console.log('\n--- Configuration Context Retrieved ---'); console.log(JSON.stringify(context, null, 2)); console.log('\nThese are the authentication options to pass to node-sp-auth:'); console.log(JSON.stringify(context.authOptions, null, 2)); if (fs.existsSync(configFilePath)) { console.log(`\nConfig file was saved/updated at: ${configFilePath}`); // For a clean demonstration, you might remove the file afterward: // fs.unlinkSync(configFilePath); // console.log(`Cleaned up temporary config file: ${configFilePath}`); } else { console('\nNo new config file was explicitly saved as it was run in headlessMode with provided authOptions.'); } } catch (error) { console.error('Error in authentication configuration process:', error instanceof Error ? error.message : error); } } demonstrateAuthConfig();
sp-auth --version
Debug
Known issues
breakingThe underlying `node-sp-auth` package, which `node-sp-auth-config` is designed to configure, has been flagged as 'Inactive' and 'Security review needed' by Snyk. This indicates a lack of recent maintenance and potential unaddressed security vulnerabilities in the core authentication mechanism.
fix
Thoroughly evaluate the security implications of using `node-sp-auth` for your specific use case. Consider alternative, actively maintained SharePoint authentication solutions if continuous security patches are critical. Monitor the `node-sp-auth` GitHub repository for any future updates or community-led forks.
affects: >=1.0.0
gotchaConfiguration files generated by `node-sp-auth-config` with encrypted passwords use a machine-bound hash. This means these configuration files are not portable and cannot be directly transferred and used on a different machine or environment.
fix
For cross-environment deployments (e.g., CI/CD), avoid relying on disk-saved encrypted passwords. Instead, provide authentication parameters programmatically via the `authOptions` constructor parameter, or use environment variables (e.g., `SPAUTH_SITEURL`, `SPAUTH_USERNAME`, `SPAUTH_PASSWORD`).
affects: >=1.0.0
gotchaWhen `headlessMode: true` is enabled, the library will not prompt for missing configuration parameters. If `authOptions` are not explicitly provided and no valid configuration file exists at `configPath`, the process will terminate gracefully with an error.
fix
In headless environments, ensure all necessary `authOptions` are passed directly in the `AuthConfig` constructor, or that `configPath` points to a pre-existing, fully configured JSON file. Alternatively, ensure the relevant `SPAUTH_` environment variables are set.
affects: >=1.0.0
Errors
Common errors & fixes
Error: No auth options were provided and no existing config file found.
This typically occurs when `AuthConfig.getContext()` is called in `headlessMode` without a pre-existing config file or programmatic `authOptions`.
fix
Provide all required `authOptions` in the `AuthConfig` constructor or ensure `configPath` points to a valid and complete configuration file. Set `headlessMode: false` to enable interactive prompts during development.
Error: digital envelope routines::unsupported
This Node.js error usually indicates an incompatibility between the Node.js version and underlying OpenSSL functionality used by `node-sp-auth` or its dependencies.
fix
Try using a different Node.js LTS version (e.g., Node.js 16 or 18 if on newer, or Node.js 20+ if on older). For Node.js versions 17 and higher, you might need to run your script with `NODE_OPTIONS=--openssl-legacy-provider node your-script.js` to enable legacy OpenSSL support.
The token audience is NOT valid.
SharePoint online authentication failed
These errors, originating from the underlying `node-sp-auth` library, often point to incorrect SharePoint Online tenant settings, misconfigured Azure AD app registrations (for Add-In Only permissions), or invalid user credentials (username/password, ADFS).
fix
Carefully review all authentication parameters, including `siteUrl`, `tenantId`, `clientId`, `clientSecret`, `username`, and `password`. Verify that the SharePoint Add-In or Azure AD application has the correct permissions and is properly registered and trusted within your SharePoint tenant. For ADFS, confirm the federation service configuration. Check `node-sp-auth`'s issue tracker for similar problems.
Upgrade
Version history
3.0.5latest on npm
Audit
Dependencies
node-sp-authrequiredCore library for which node-sp-auth-config generates authentication configurations.
Agent activity
26 hits · last 30 days
node
22
OpenAI (training)
1
Resources
node-sp-auth-config — npm install node-sp-auth-config · libregistry